Module core

The AcceptPathInfo directive controls whether requests that contain trailing pathname information, that follows an actual filename or nonexistent file in an existing directory, are accepted or rejected. The trailing pathname information can be made available to scripts in the PATH_INFO environment variable.

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

Parameter: On | Off | Default

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

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

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

The AcceptThreads directive specifies the maximum number of accept threads per server child process. If a value is not specified, the server will use a limit of four accept threads. The accept threads are used to accept new connections from the client. This number may need to be changed to reflect the number of concurrent connections which are being accepted. If a large number of connections to the Web server start at approximately the same time, the number of accept threads may need to be adjusted to a higher value.

Parameter: number

• The number value specifies the maximum number of accept threads per server child process. Valid values include 1 through 20.

When returning a document to the client, the server looks for the first access control file in the list of names in every document directory path. This only happens if the access control files are enabled for the directory. For example:

AccessFileName .acl

Before returning the document /QIBM/UserData/web/index.html, the server will read /.acl, /QIBM/.acl, /QIBM/UserData/.acl and /QIBM/UserData/web/.acl for directives, unless they have been disabled with the following:

<Directory/> 
   AllowOverride None 
</Directory> 

Parameter: filename

• Filename is any valid filename on the IBM i server.

If multiple occurrences of this directive are configured in a container, only the last occurrence is processed. All other occurrences are ignored.

See also AllowOverride.

The AddDefaultCharset directive specifies the character set name that will be added to any response that does not have a parameter on the content type in the HTTP headers. This will override any character set specified, in the document body, by a META tag.

Parameter: on | off | charset

• AddDefaultCharset on enables HTTP Server's internal default charset of iso-8859-1 as required by the directive.
• AddDefaultCharset off disables this functionality.
• Alternate charset can be specified, for example, AddDefaultCharset on utf-8.

The Server response-header field contains information about the software used by the origin server to handle the request, sometimes including information about specific modules that are loaded. Some security policies may dictate that such identifying information be removed from all network daemons.

Setting AddServerHeader to off prevents IBM HTTP Server for i from adding the Server header to outgoing responses.

The value of the outgoing Server header can be logged by adding the string %{Server}o to whichever LogFormat is referenced by your CustomLog directives.

The AllowEncodedSlashes directive allows URLs which contain encoded path separators (%2F for / and additionally %5C for \ on according systems) to be used. Normally, such URLs are refused with a 404 (Not found) error. Turning AllowEncodedSlashes on is useful when used in conjunction with PATH_INFO environment variable.

If encoded slashes are needed in path info, use of NoDecode is strongly recommended as a security measure. Allowing slashes to be decoded could potentially allow unsafe paths.

Parameter: on | off

• The on parameter value specifies that URLs with encoded path separators can be used.
• The off parameter value specifies that URLs with encoded path separators will result in a 404 (Not found) error.
• The NoDecode parameter value specifies that URLs with encoded path separators can be used but encoded slashes are not decoded but left in their encoded state.

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

Parameter: override

• Override can be set to one or more of the following

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

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

Example:

AllowOverride None

AllowOverrideList Redirect RedirectMatch

In the example above only the Redirect and RedirectMatch directives are allowed. All others will cause an internal server error.

Example:

AllowOverride AuthConfig

AllowOverrideList CookieTracking CookieName

In the example above AllowOverride grants permission to the AuthConfig directive grouping and AllowOverrideList grants permission to only two directives from the FileInfo directive grouping. All others will cause an internal server error.

See alsoAccessFileName , AllowOverride.

CGIPassAuth allows scripts access to HTTP authorization headers such as Authorization, which is required for scripts that implement HTTP Basic authentication. Normally these HTTP headers are hidden from scripts. This is to disallow scripts from seeing user ids and passwords used to access the server when HTTP Basic authentication is enabled in the web server. This directive should be used when scripts are allowed to implement HTTP Basic authentication.

The setting is respected by any modules which use ap_add_common_vars(), such as mod_cgi. Notably, it affects modules which don't handle the request in the usual sense but still use this API; example of this is mod_include. Third-party modules that don't use ap_add_common_vars() may choose to respect the setting as well.

The DefaultFsCCSID directive specifies the CCSID that your server runs under, the server character set environment, and the EBCDIC CCSID that is used when the server converts:

• Input request data for user CGI programs or Apache modules.
• Output response data from user CGI programs, or Apache modules, to be sent back to the requester (client browser).

A configuration file can contain more than one DefaultFsCCSID directive, but the last directive in the configuration file determines the CCSID.

If the HTTP Server startup value -fsccsid is specified on the STRTCPSVR command or as a parameter on the HTTP Administration's start server , the value specified overrides all other settings and is used for the server CCSID.

If there is no startup value specified, but there is a DefaultFsCCSID directive in the configuration file, the directive value will be used for the server CCSID.

If there is no startup value specified and there is no DefaultFsCCSID directive in the configuration file, then the QCCSID system value is used. If the QCCSID system value is set to 65535, then the server job will be started with that CCSID. However, the CCSID that the server actually uses for conversions will be the job default ccsid which is set to an appropriate value based on the language (LANGID) of the server job.

To display the CCSID of the server, complete the following task:

1. Start a 5250 session on your IBM i server.
2. Type WRKACTJOB (Work Active Job).
3. Type a 5 (Work with...) next to your server job.
4. Type a 2 (Display job definition attributes) on the Work with Job screen.
5. Page down until you see the job CCSID fields.

Example

In this case, the QCCSID system value was used to start the server job. We see that the Coded character set identifier is 65535. However, the Default coded character set identifier has been set to 37 because the Language identifier is ENU (United States English). The server will use CCSID 37 as the EBCDIC CCSID.

Language identifier . . . . . . . . . . . . . . . :   ENU       
Country or region identifier  . . . . . . . . . . :   US        
Coded character set identifier  . . . . . . . . . :   65535     
Default coded character set identifier  . . . . . :   37

This directive has been disabled. For backwards compatibility of configuration files, it may be specified with the value none, meaning no default media type.

Parameter: MIME-type

• The MIME-type value specifies the document content-type.

For example:

DefaultType None

Use the /QIBM/UserData/HTTPA/conf/mime.types configuration file and the AddType to configure media type assignments via file extensions, or the ForceType directive to configure the media type for specific resources. Otherwise, the server will send the response without a Content-Type header field and the recipient may attempt to guess the media type.

In its one parameter form, Define is equivalent to passing the -D argument to STRTCPSVR command. For example: STRTCPSVR SERVER(*HTTP) HTTPSVR(instanceName '-t -D DUMP_VHOSTS'). It can be used to toggle the use of <IfDefine> sections without needing to alter -D arguments in the HTTP server STRTCPSVR command.

In addition to that, if the second parameter is given, a config variable is set to this value. The variable can be used in the configuration using the ${VAR} syntax. The variable is always globally defined and not limited to the scope of the surrounding config section.

<IfDefine TEST>
  Define servername test.example.com
</IfDefine>
<IfDefine !TEST>
  Define servername www.example.com
  Define SSL
</IfDefine>

DocumentRoot /var/www/${servername}/htdocs

Variable names may not contain colon ":" characters, to avoid clashes with http://httpd.apache.org/docs/2.4/mod/mod_rewrite.html#rewritemap 's syntax.

<Directory> and </Directory> are used to enclose a group of directives that only apply to the named directory and subdirectories of that directory. Any directive that is allowed in a directory context may be used.

Parameter: directory

• A directory is either the full path to a directory or a wildcard string. Refer to <DirectoryMatch> for details regarding wildcard strings. Full path directory example:

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

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

<Directory /> 
   AllowOverride None 
</Directory> 

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

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

• Apply directive AllowOverride None (disabling .htaccess files).
• Apply directive AllowOverride FileInfo (for directory /home/web).
• Apply any FileInfo directives in /home/web/.htaccess.

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

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

Suppose that the filename being accessed is /home/ABC/public_html/ABC/index.html. The server considers each of /, /home, /home/ABC, /home/ABC/public_html and /home/ABC/public_html/ABC in that order. The regular expression would not be considered until all normal <Directory> and .htaccess files have been applied. Then the regular expression will match on /home/ABC/public_html/ABC and be applied.

<DirectoryMatch> and </DirectoryMatch> are used to enclose a group of directives that only apply to the named directory and the files within that directory. It is the same as <Directory>; however, it takes an argument as a regular expression. For example:

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

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

Parameter: regex

• Regex is a UNIX-style regular expression that is matched against the URL. Subexpressions are grouped within parentheses. Then, parenthetically enclosed regular expressions will be substituted in a subsequent $n statement.

Compatability

Prior to IBM i 7.2, this directive implicitly applied to sub-directories (like <Directory>) and could not match the end of line symbol ($). In IBM i 7.2 and later, only directories that match the expression are affected by the enclosed directives.

Trailing Slash

This directive applies to requests for directories that may or may not end in a trailing slash, so expressions that are anchored to the end of line ($) must be written with care.

Named groups and backreferences are captured and written to the environment with the corresponding name prefixed with "MATCH_" and in upper case. This allows elements of paths to be referenced from within expressions and modules like mod_rewrite. In order to prevent confusion, numbered (unnamed) backreferences are ignored. Use named groups instead.

For example:

<DirectoryMatch "^/www/webserver/htdocs/(?<sitename>host\d)$">
    Options Indexes FollowSymLinks
    RewriteEngine On
    RewriteCond "%{env:MATCH_SITENAME}"  "^host1"
    RewriteRule .* success.html
    Require all granted
</DirectoryMatch>

See also<Directory> .

The DocumentRoot directive sets the directory from which HTTP Server will serve files. If the URL is not matched by a directive like Alias, the server appends the path from the requested URL to the document root and makes the path to the document.

Parameter: directory-path

• Directory-path is any valid directory path on the IBM i server.

For example:

DocumentRoot /usr/web 

An access to http://www.my.host.com/index.html refers to /usr/web/index.html.

If the DocumentRoot directive is used in the server context and the directory does not exist, the server will not start. If the DocumentRoot directive is used in a virtual host context and the directory does not exist, that virtual host will inherit the document root from the server context (the server will start).

The <Else> applies the enclosed directives if and only if the most recent <If> or <ElseIf> section in the same scope has not been applied. For example:

<If "-z req('Host')">

# ...

</If>

<Else>

# ...

</Else>

The <If> would match HTTP/1.0 requests without a Host: header and the <Else> would match requests with a Host: header.

See also

<If>

<ElseIf>

The <ElseIf> applies the enclosed directives if and only if both the given condition evaluates to true and the most recent <If> or <ElseIf> section in the same scope has not been applied. For example:

<If "-R '10.1.0.0/16'">

# ...

</If>

<ElseIf "-R '10.0.0.0/8'">

# ...

</ElseIf>

<Else>

# ...

</Else>

The <ElseIf> would match if the remote address of a request belongs to the subnet 10.0.0.0/8 but not to the subnet 10.1.0.0/16.

See also

<If>

<ElseIf>

If an error can be detected within the configuration, this directive can be used to generate a custom error message, and halt configuration parsing. The typical use is for reporting required modules which are missing from the configuration.

# Example

# ensure that mod_include is loaded

<IfModule !include_module>

Error "mod_include is required by mod_foo. Load it with LoadModule."

</IfModule>

# ensure that exactly one of SSL,NOSSL is defined

<IfDefine SSL>

<IfDefine NOSSL>

Error "Both SSL and NOSSL are defined. Define only one of them."

</IfDefine>

</IfDefine>

<IfDefine !SSL>

<IfDefine !NOSSL>

Error "Either SSL or NOSSL must be defined."

</IfDefine>

</IfDefine>

This directive controls whether httpd may use the sendfile support from the kernel to transmit file contents to the client. By default, when the handling of a request requires no access to the data within a file (for example, when delivering a static file) Apache uses sendfile to deliver the file contents without ever reading the file if the operating system supports it. This sendfile mechanism avoids separate read and send operations, and buffer allocations.

In the event of a problem or error, HTTP Server can be configured to do one of four things:

1. Output a simple hard coded error message.
2. Output a customized message.
3. Internally redirect to a local URL to handle the problem/error.
4. Redirect to an external URL to handle the problem/error.

The first option is the default, while options 2 through 4 are configured using the ErrorDocument directive, which is followed by HTTP Server response code and a message or URL.

expression syntax can be used inside the directive to produce dynamic strings and URLs.

For option 3, the document parameter must begin with a '/' character and it is assumed to be relative to DocumentRoot. If the document parameter contains a ':' character it is assumed to be an external URL (option 4). If neither of these are true, option 2 is assumed.

Parameter One: error-code

• The error-code parameter specifies the error code associated with a hard coded error message, a customized message, a local URL, or an external URL that handles the problem/error.

Parameter Two: document

• The document parameter specifies a hard coded error message, a customized message, a local URL, or an external URL that handles the problem/error.

Messages in this context begin with a single quote ("), which does not form part of the message itself. The server will sometimes offer additional information regarding the problem/error.

URLs must begin with a slash (/) for local URLs, or be a full URL which the client can resolve. Alternatively, a message can be provided to be displayed by the browser. Note that deciding whether the parameter is an URL, a path or a message is performed before any expression is parsed. For example:

ErrorDocument 500 http://QIBM.example.com/cgi-bin/tester 
ErrorDocument 404 /cgi-bin/bad_urls.html 
ErrorDocument 401 /subscription_info.html 
ErrorDocument 403 "Sorry cannot allow you access today.  
ErrorDocument 403 Forbidden!
ErrorDocument 403 /cgi-bin/forbidden.pgm?referrer=%{escape:%{HTTP_REFERER}} 

Apache on the IBM i allows error code keywords on this directive, in addition to HTTP response codes. This will allow customers more granularity in their error page customization. To do this, the syntax for ErrorDocument was enhanced to also allow one of these key words as the error_code. Valid keywords, their equivalent HTTP response codes and the cause are as follows:

An example - a customer puts the following into their configuration file:

ErrorDocument byrule "Sorry cannot allow you access." 
ErrorDocument openfailed "You do not have authority to this file." 

When an HTTP response code of 403 (FORBIDDEN) occurs and it is determined that the reason is the client is on the deny list, the response back to the browser will be "Sorry cannot allow you access". If, however, the 403 response code is a result of the user not having authority to the file, the message will be "You do not have authority to this file". This gives the user more granularity to customize error responses to the client.

The ErrorLog directive sets the name of the file to which the server will log any errors it may encounter. If the filename does not begin with a slash (/) then it is assumed to be relative to the ServerRoot. Specifying a value of off or *off will cause the server to not log errors.

Parameter: filename-or-pipe | off | *off

• The filename parameter is relative to the ServerRoot or a full path to the file.
• A pipe (|) followed by a program to spawn to handle the error log information. Data written to the pipe from the server will be in the FSCCSID that is in use by the server.
• The off or *off value turns off error reading.

All messages logged to the Error log will be logged in the primary language installed for the IBM HTTP Server. The error log file will be created with a coded character set identifier (CCSID) that is compatible with the language. The CCSID value is an ASCII CCSID.

It is recommended that you allow the server to create the log file. Specifically:

• For IFS files, the user must create the directories that contain the log file and must grant the QTMHHTTP user write access to the directory. The server will create the log file.
• For QSYS.LIB logs, the user must create the library that contains the logs. The server will create the file and members in the specified library.
• If the filename does not begin with a slash (/) then it is assumed to be relative to the ServerRoot.
• If LogCycle is active and if the path ends without a '/' character, then the path is considered to be the complete log file name. In that case, the server will add an extension in the format QCYYMMDDHH, where these variables have the following values:
  • Q is a default value that indicates to the server that this is a log file.
  • C is the century indicator (0 for pre-2000, 1 for post-2000)
  • YY is the year indicator
  • MM is the month indicator
  • DD is the day indicator HH is the hour indicator (00 = 00:00 (midnight), 23=23:00)
    Note: Will not be generated for file system QDL.

    For example, a path of "/logs/errorlog" results in a file such as "/logs/errorlog.Q100030300".

• If LogCycle is active and if the path ends with a '/' character, then the path is considered to be the directory that will contain the log file. In that case, the server will create log files named in the QCYYMMDDHH format. For example, a path of "/logs/errorlog/" results in a file such as "/logs/errorlog/Q100030300".
• If LogCycle is active and the log file is in the QSYS file system, the name must end it the file component of the IFS path. Example:

  # Config file directives
  LogCycle Daily
  ErrorLog /QSYS.LIB/MYLIB.LIB/MYLOGS.FILE

  The resulting daily log rollover files will be of the form /QSYS.LIB/MYLIB.LIB/MYLOGS.FILE/Qcyymmddhh.MBR

• LogCycle Hourly is not valid if the log file is in the QDLS file system as that file system only supports 8 character file names and 3 character extensions.
• If LogCycle is not active, no special naming is used. The name of the log file given on the ErrorLog directive is used as given for the name of the log file. If the name is a directory, a default name of http.log will be concatenated to the directory name to create the log file. For example:

  # Config file directives 
  LogCycle Off 
  LogFormat "%h %l %u %t \"%r\" %>s %b" common 
  CustomLog /logs/path/ common 

  The resulting log file will be /logs/path/http.log.

Security:

See Security tips for HTTP Server details on why your security could be compromised if the directory where log files are stored is writable by anyone other than the user that starts the server. If a program is used, then it will be run under the user who started httpd. This will be root if the server was started by root (be sure that the program is secure).

See also LogLevel.

ErrorLogFormat allows to specify what supplementary information is logged in the error log in addition to the actual log message.

Specifying connection or request as first parameter allows to specify additional formats, causing additional information to be logged when the first message is logged for a specific connection or request, respectively. This additional information is only logged once per connection/request. If a connection or request is processed without causing any log message, the additional information is not logged either.

It can happen that some format string items do not produce output. For example, the Referer header is only present if the log message is associated to a request and the log message happens at a time when the Referer header has already been read from the client. If no output is produced, the default behavior is to delete everything from the preceding space character to the next space character. This means the log line is implicitly divided into fields on non-whitespace to whitespace transitions. If a format string item does not produce output, the whole field is omitted. For example, if the remote address %a in the log format [%t] [%l] [%a] %M is not available, the surrounding brackets are not logged either. Space characters can be escaped with a backslash to prevent them from delimiting a field. The combination '% ' (percent space) is a zero-width field delimiter that does not produce any output.

The above behavior can be changed by adding modifiers to the format string item. A - (minus) modifier causes a minus to be logged if the respective item does not produce any output. In once-per-connection/request formats, it is also possible to use the + (plus) modifier. If an item with the plus modifier does not produce any output, the whole line is omitted.

A number as modifier can be used to assign a log severity level to a format item. The item will only be logged if the severity of the log message is not higher than the specified log severity level. The number can range from 1 (alert) over 4 (warn) and 7 (debug) to 15 (trace8).

For example, here's what would happen if you added modifiers to the %{Referer}i token, which logs the Referer request header.

Some format string items accept additional parameters in braces.

The log ID format %L produces a unique id for a connection or request. This can be used to correlate which log lines belong to the same connection or request, which request happens on which connection. A %L format string is also available in mod_log_config, to allow to correlate access log entries with error log lines. If mod_unique_id is loaded, its unique id will be used as log ID for requests.

Example 1

ErrorLogFormat "[%t] [%l] %7F: %E: [client\ %a] %M% ,\ referer\ %{Referer}i"

Example 2

#Advanced example with request/connection log IDs

• ErrorLogFormat "[%{uc}t] [%-m:%-l] [R:%L] [C:%{C}L] %7F: %E: %M"
• ErrorLogFormat request "[%{uc}t] [R:%L] Request %k on C:%{c}L pid:%P tid:%T"
• ErrorLogFormat request "[%{uc}t] [R:%L] UA:'%+{User-Agent}i'"
• ErrorLogFormat request "[%{uc}t] [R:%L] Referer:'%+{Referer}i'"
• ErrorLogFormat connection "[%{uc}t] [C:%{c}L] local\ %a remote\ %A"

The FileETag directive configures the file attributes that are used to create the ETag (entity tag) response header field when the document is based on a static file. (The ETag value is used in cache management to save network bandwidth.) The FileETag directive allows you to choose which of these -- if any -- should be used. The recognized keywords are:

Parameter: component

• INode indicates the file's inode number will be included in the calculation.
  Note: INode is the file ID number for the object. This number uniquely identifies the object within a file system. It is part of the stat structure (the st_ino field of the stat structure).
• MTime indicates the date and time the file was last modified will be included.
• Size indicates the number of bytes in the file will be included.
• All indicates all available fields will be used (equivalent to 'FileETag INode MTime Size').
• None indicates that if a document is file-based, no ETag field will be included in the response.

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

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

The MTime attribute (if specified) may be used by remote proxy servers to calculate cache expiry times in the event that document expiry times are not available or provided.

See CacheLastModifiedFactor for more information.

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

Parameter: filename

• The filename parameter should include a filename or a wildcard string where '?' matches any single character and '*' matches any sequences of characters. For example:

  <Files "cat.html">
     # Insert stuff that applies to cat.html here
  </Files>

  <Files "?at.*">
     # This would apply to cat.html, bat.html, hat.php and so on.
  </Files>

• Regular expressions can also be used, with the addition of the '~' character. For example:

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

  would match most common Internet graphics formats. <FilesMatch> is preferred.

The <FilesMatch> directive provides for access control by filename, in the same way <Files> directive does. The <FilesMatch> directive, however, accepts a regular expression. For example:

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

This would match most common Internet graphic formats. (Note: The argument to <FilesMatch> does not need to be in quotes unless the regular expression includes a space character. )

The .+ at the start of the regex ensures that files named .png, or .gif, for example, are not matched.

Named groups and backreferences are captured and written to the environment with the corresponding name prefixed with "MATCH_" and in upper case. This allows elements of files to be referenced from within expressions and modules like mod_rewrite . In order to prevent confusion, numbered (unnamed) backreferences are ignored. Use named groups instead.

For example:

<FilesMatch "^(?<sitename>\w+)\.html$">
     Options Indexes FollowSymLinks
     Require all granted
     RewriteEngine On
     RewriteCond "%{env:MATCH_SITENAME}"  "^host"
     RewriteRule .* success.html
</FilesMatch>

Parameter: regex

• A UNIX-style regular expression that is matched against the URL. Subexpressions are grouped within parentheses. Then, parenthetically enclosed regular expressions will be substituted in a subsequent $n statement.

The ForceType directive forces all matching files to be served with the content type identification given by media-type when they are placed into an .htaccess file, a <Directory>, or <Location> section.

Parameter: media_type

• The media_type parameter is a MIME type/subtype to which all files in the directory will be forced.

You can also override more general ForceType settings by using the value of None:

# force all files to be image/gif:
<Location "/images">
  ForceType image/gif
</Location>

# but normal mime-type associations here:
 <Location "/images/mixed">
  ForceType None
</Location>

This directive primarily overrides the content types generated for static files served out of the filesystem. For resources other than static files, where the generator of the response typically specifies a Content-Type, this directive has no effect.

The HostNameLookups directive enables DNS lookups so the host names can be logged (and passed to CGIs/SSIs in the REMOTE_HOST environment variable).

Parameter: on | off | double

• The on value enables DNS lookups so the host names can be logged (and passed to CGIs/SSIs in the REMOTE_HOST environment variable).
• The default off value saves on the network traffic for those sites that do not truly need the reverse lookup. Heavily loaded sites should leave this directive set to off, since DNS lookups can take a considerable amount of time.
• The value double refers to doing double-reverse DNS. That is, after a reverse lookup is performed, a forward lookup is then performed on that command. At least one of the IP addresses in the forward lookup must match the Original address. When mod_access is used for controlling access by hostname, regardless of the setting, a double reverse lookup will be performed. This is necessary for security.

The HotBackup directive is used to specify whether or not a hot backup server should be started at the server startup time. With the hot backup server active, if the primary server job abnormally terminates, the hot backup will immediately take over and act as the primary and continue servicing requests. A new hot backup is automatically created, in the background, within one minute. However, if more than five consecutive server failures occur within a ten minute time period, no additional hot backups will be created and the server will fail. The server is allowed to fail in this situation to avoid system degradation, since the hot backup processing can consume system resources.

If the primary server process failure is not due to the network, all user connections remain active during the hot backup take over and the end users do not detect the loss of server; however, some HTTP requests in transient may be lost. If the failure is due to the loss of network, the server must be restarted.

For a full backup recovery, including system and network failures, refer to highly available Web server.

Parameter: on | off

• When set to on, if the primary server job abnormally terminates, the hot backup will immediately take over and act as the primary and continue servicing requests.
• With HotBackup off, only one multithreaded server child process is started.

This directive changes the rules applied to the HTTP Request Line (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 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.

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

Users should pay particular attention to the 400 responses in the access log for invalid requests which were unexpectedly rejected.

The HTTPSubsystemDesc directive specifies the user created subsystem that the HTTP server runs in. By default HTTP server runs under QHTTPSVR/QHTTPSVR subsystem.

The subsystem must already exist before using this directive, otherwise HTTP server will fail to start. The subsystem can be automatically started if it's not active when starting HTTP server but will not be ended when stopping the HTTP server

The HTTPStartJobQueue directive specifies the user created job queue to which the HTTP server jobs will be submitted. The default HTTP server job queue is QHTTPSVR/QZHBHTTP.

The job queue must already exist before using this directive, otherwise HTTP server will fail to start.

The HTTPStartJobDesc directive specifies the user created job description which defines how HTTP server jobs should be run. The default HTTP server job description is QHTTPSVR/QZHBHTTP.

The job description must already exist before using this directive, otherwise HTTP server will fail to start.

The HTTPRoutingData directive specifies the user defined routing data for HTTP server jobs. The default value is HTTPWWW. A maximum of 80 characters can be specified.

The routing entry must be already added to the HTTP subsystem before using this directive, otherwise HTTP server will fail to start.

The <If> directive evaluates an expression at runtime, and applies the enclosed directives if and only if the expression evaluates to true. For example:

<If "-z req('Host')">

would match HTTP/1.0 requests without a Host: header. Expressions may contain various shell-like operators for string comparison (=, !=, <, ...), integer comparison (-eq, -ne, ...), and others (-n, -z, -f, ...). It is also possible to use regular expressions,

<If "%{QUERY_STRING} =~ /(delete|commit)=.*?elem/">

shell-like pattern matches and many other operations. These operations can be done on request headers (req), environment variables (env), and a large number of other properties. The full documentation is available in ap_expr expressions parser.

Only directives that support the directory context can be used within this configuration section.

See also

<ElseIf>

<Else>

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

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

• parameter-name
• !parameter-name

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

Parameter: parameter-name

• The parameter-name parameter is defined as given on the STRTCPSVR command line vie -D Dparameter, at the time the server was started. <IfDefine> sections are nestable, which can be used to implement simple mutliple-parameter tests. For example:

  STRTCPSVR SERVER(*HTTP) HTTPSVR(instanceName '-D LDAP') 
  # in the instance configuration
  <IfDefine LDAP>
     LoadModule ibm_ldap_module /QSYS.LIB/QHTTPSVR.LIB/QZSRVLDAP.SRVPGM
  </IfDefine>

If customer has included "<IfDefine keyword> ... </IfDefine> in http.conf file, the directives that are in context will be only valid if the command "STRTCPSVR" has included this directive, in this case " STRTCPSVR '-Dkeyword' ", if not, the server will ignored then.

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

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

• module-name
• !module-name

Parameter: module-name

• The module-name parameter is a module name as given as the file name of the module at the time it was compiled. For example:

  mod_rewrite.c 

<IfModule> sections are nestable which can be used to implement simple multiple-module tests.

The Include directive allows inclusion of other configuration files from within the server configuration files. The filename can be either a relative or absolute path.

Parameter: filename|wildcard

• The filename value identifies other configuration files from within the server configuration files.
• The wildcard value identifies other configuration files that match a particular pattern from within the server configuration files.

Wildcard characters can be used in the filename or directory parts of the path to include several files at once, in alphabetical order. In addition, if Include points to a directory, rather than a file, HTTP server will read all files in that directory and any subdirectory. However, including entire directories is not recommended, because it is easy to accidentally leave temporary files in a directory that can cause HTTP server to fail. Instead, we encourage you to use the wildcard syntax to include files that match a particular pattern, such as Include conf/vhosts/*.conf, for example.

The Include directive will fail with an error if a wildcard expression does not match any file. The IncludeOptional directive can be used if non-matching wildcards should be ignored.

Wildcards may be included in the directory or file portion of the path. This example will fail if there is no subdirectory in conf/vhosts that contains at least one *.conf file:

Include conf/vhosts/*/*.conf

Alternatively, the following command will just be ignored in case of missing files or directories:

IncludeOptional conf/vhosts/*/*.conf

See also IncludeOptional

This directive allows inclusion of other configuration files from within the server configuration files. It works identically to the Include directive, with the exception that if wildcards do not match any file or directory, the IncludeOptional directive will be silently ignored instead of causing an error.

Parameter: filename|wildcard

• The filename value identifies other configuration files from within the server configuration files.
• The wildcard value identifies other configuration files that match a particular pattern from within the server configuration files.

See also Include

The KeepAlive directive enables keep-alive support (also known as persistent connections).

Parameter: on | off

• When set to on, the directive enables keep-alive support (also known as persistent connections).
• When set to off, keep-alive support (also known as persistent connections) is disabled.

Persistent connections enable a single TCP connection to be used for multiple HTTP requests. Normally, each HTTP request uses a separate connection. Reusing a single connection reduces the connection open/close overhead, thereby improving performance for that client. However with dynamic content, depending on your Web applications, using persistent connections can reserve server resources for each client, thereby reducing the throughput of your server as a whole. Therefore, care should be taken when modifying persistent connection related settings.

Set to off to disable persistent connections, on to enable. If the KeepAlive directive value is not off or zero, on is assumed.

See also KeepAliveTimeout and MaxKeepAliveRequests.

The KeepAliveTimeout directive is related to persistent connections and determines the number of seconds HTTP Server waits for a subsequent request before closing the connection. By adding a postfix of ms the timeout can be also set in milliseconds. The KeepAlive directive must be set to on, enabling persistent connections, for this directive to take effect. It is recommended that this value be set high enough to prevent time outs. Note that this is related to the time between requests and not during requests. Once a request is received, the connection timeout setting (set by the TimeOut directive) applies. The connection time-out applies until request processing is complete and (until the next request is received) the persistent connections related timer setting is applied.

Parameter: num[ms]

• The num value determines the number of seconds or milliseconds if it ends with 'ms' that HTTP Server waits for a subsequent request before closing the connection.

If KeepAliveTimeout is not set for a name-based virtual host, the value of the first defined virtual host best matching the local IP and port will be used.

See also KeepAlive, MaxKeepAliveRequests, and TimeOut.

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

<Limit POST PUT DELETE>
   require valid-user
</Limit>

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

Parameter: method

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

A <LimitExcept> section should always be used in preference to a <Limit> section when restricting access, since a <LimitExcept> section provides protection against arbitrary methods.

The <Limit> and <LimitExcept> directives may be nested. In this case, each successive level of <Limit> or <LimitExcept> directives must further restrict the set of methods to which access controls apply.

When using <Limit> or <LimitExcept> directives with the Require directive, note that the first Require to succeed authorizes the request, regardless of the presence of other Require directives.

For example, given the following configuration, all users will be authorized for POST requests, and the Require group editors directive will be ignored in all cases:

<LimitExcept GET>
  Require valid-user
</LimitExcept GET>

<LimitExcept POST>
  Require group editors
</LimitExcept POST>

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

For example:

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

Parameter: method

• Method names listed can be one or more of the following: GET, POST, PUT, DELETE, CONNECT, OPTIONS, TRACE, PATCH, PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK and UNLOCK. The method name is case sensitive. If GET is specified, HEAD is also allowed (not restricted).

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

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

Parameter: number

• The number parameter is an integer which represents the set limit on the allowed size (in bytes) of an HTTP Request message body within the context in which the directive is given (server, per-directory, per-file or per-location). The default value of '0' (zero) indicated unlimited allowed size.

For example, to limit the size of an uploaded file to 100K use the following:

LimitRequestBody 10240

An internal redirect happens, for example, when using the Action directive, which internally redirects the original request to a CGI script. A subrequest is Apache's mechanism to find out what would happen for some URI if it were requested. For example, mod_dir uses subrequests to look for the files listed in the DirectoryIndex directive.

LimitInternalRecursion prevents the server from crashing when entering an infinite loop of internal redirects or subrequests. Such loops are usually caused by misconfigurations.

The directive stores two different limits, which are evaluated on per-request basis. The first number is the maximum number of internal redirects that may follow each other. The second number determines how deeply subrequests may be nested. If you specify only one number, it will be assigned to both limits.

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

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

Parameter: number

• The number parameter is an integer from 0 (meaning unlimited) to 32767 bytes. The default value is 100.

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

This directive gives the server administrator greater control over abnormal client Request behavior, which may be useful for avoiding some forms of denial-of-service attacks. Under normal conditions, the value should not be changed from the default.

Parameter: number

• A number is an integer from 0 to 32766 (in bytes).

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

This directive gives the server administrator greater control over abnormal client Request behavior, which may be useful for avoiding some forms of denial-of-service attacks. Under normal conditions, the value should not be changed from the default.

Parameter: number

• A number is an integer from 0 to 8190 (in bytes).

The LimitXMLRequestBody directive limits (in bytes) the maximum size of an XML-based request body.

Parameter: number

• A number is an integer from 0 (meaning unlimited) to 2,147,483,647 (2 gigabytes).

The Listen directive instructs HTTP Server to listen to more than one IP address or port; by default the server responds to requests on all IP interfaces. It tells the server to accept incoming requests on the specified IP address or address-and-port combinations. If the first format is used, with an IP address number only, the server listens to the given IP address. If an IP address is given as well as a port, the server will listen on the given port and interface.

Parameter One: IP address

• The IP address parameter specifies a fully qualified IP address.

Parameter Two: port number

• The port number parameter is optional and if specified as word "FRCA", implies the incoming connections on the specified IP address and port are eligible to be monitored and served by FRCA cache support.
  Note: FRCA does not support SSL. Therefore, do not specify FRCA option for IP addresses and ports that are used for SSL connections.

Parameter Three: [protocol]

• The [protocol] parameter is optional and if specified as word "FRCA", implies the incoming connections on the specified IP address and port are eligible to be monitored and served by FRCA cache support.
  Note: FRCA does not support SSL. Therefore, do not specify FRCA option for IP addresses and ports that are used for SSL connections.

Multiple Listen directives may be used to specify a number of addresses and ports to listen to. The server will respond to requests from any of the listed addresses and ports.

To make the server accept connections on both port 80 and port 8000, use:

Listen 80 
Listen 8000

To make the server accept connections on two specified interfaces and port numbers, use:

Listen 194.170.2.1:80 
Listen 194.170.2.5:8000

IPv6 addresses must be surrounded in square brackets, as in the following example:

Listen [2001:db8::a00:20ff:fea7:ccea]:80 

To make the FRCA monitor and intercept connections on a specified interface and port numbers, use:

Listen 194.170.2.5:8000 FRCA

In the above example, since the optional parameter FRCA is specified, FRCA will be enabled for the specified IP address and port.

The optional protocol argument is not required for most configurations. If not specified, https is the default for port 443 and http the default for all other ports.

Listen 192.170.2.1:8443 https

Error condition: Multiple Listen directives for the same ip address and port will result in an Address already in use error message.

The ListenBacklog sets the maximum length of the queue for pending connections. Generally no tuning is needed; however, on some systems it is desirable to increase this when under a TCP SYN flood attack.

Parameter: backlog

• The backlog parameter is an integer value that sets the maximum length of the queue for pending connections.

The <Location> directive limits the scope of the enclosed directives by URL (the URL is the virtual path used to access a resource), and is similar to the <Directory> and <Proxy> directives, and starts a subsection which is terminated with a </Location> directive. Everything that is syntactically allowed in <Directory> is also allowed in <Location> (except a sub-<Files> section). However some directives, most notably the AllowOverride directive and two of its options (FollowSymLinks and SymLinksIfOwnerMatch) do not belong in <Location>. <Location> sections are processed in the order they appear in the configuration file (as opposed to <Directory> sections which are processed from the least match to the best match). They are processed after the <Directory> and <Proxy> sections, after .htaccess files are read, and after the <Files> sections. See <Directory>, <Proxy>, <Files>, and AllowOverride directives for more information on <Directory>, <Proxy>, and <Files> containers and access files.

Parameter : url

• The url parameter consists of a URL.

  For all origin (non-proxy) requests, the URL to be matched is of the form /path/. The URL should not include the http://servername prefix. For proxy requests, the matched URL is of the form http://servername/path (you must include the prefix).

  The URL may use wildcards in a wildcard string. '?' matches any single character; '*' matches any sequence of characters.

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

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

This would match URLs that contained the substring "/extra/data" or "/special/data". The directive <LocationMatch> behaves identical to the regex version of <Location>. The <Location> functionality is especially useful when combined with the SetHandler directive. For example, to enable origin requests, but allow them only from browsers at QIBM.com, you might use:

<Location /Origin>
   SetHandler server-Origin
   Require host .QIBM.com
</Location>

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

<LocationMatch "/(extra|special)/data">
    # ...
</LocationMatch>

This would match URLs that contained the substring "/extra/data" or "/special/data". (NOTE: the argument to LocationMatch does not need to be in quotes unless the regular expression includes a space character.)

If the intent is that a URL starts with /extra/data, rather than merely contains /extra/data, prefix the regular expression with a ^ to require this.

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

Named groups and backreferences are captured and written to the environment with the corresponding name prefixed with "MATCH_" and in upper case. This allows elements of URLs to be referenced from within expressions and modules like mod_rewrite. In order to prevent confusion, numbered (unnamed) backreferences are ignored. Use named groups instead.

For example:

<LocationMatch "^/combined/(?<sitename>host\d)/$">
    Options Indexes FollowSymLinks
    RewriteEngine On
    RewriteCond "%{env:MATCH_SITENAME}"  "^host1"
    RewriteRule .* success.html
    Require all granted
</LocationMatch>

The LogCycle directive controls the server's log cycle. This refers to how often the server will close all log files and open new files with a new date/time stamp.

Parameter: Off | Hourly | Daily | Weekly | Monthly

• If Off is specified, one continuous log file is generated. Log files are not rolled over.
• If Hourly is specified, log files are closed and a new one created at the end of each hour.
• If Daily is specified, log files are closed and a new one created at midnight each day.
• If Weekly is specified, log files are closed and a new one created at midnight each Sunday morning. Weekly may not work correctly if the system is not using the Gregorian calendar (this would be similar to the help behind system value QDAYOFWEEK).
• If Monthly is specified, log files are closed and a new one created at midnight on the first day of the month.

If LogCycle is active and the path defined on an ErrorLog, CustomLog, TransferLog, or FRCACustomLog directive ends without a (/) character, then the path is considered to be the complete log file name. In that case, the server will add an extension to the given file with the format QCYYMMDDHH, where these variables have the following values:

• Q is a default value that indicates to the server that this is a log file.
• C is the century indicator (0 for pre-2000, 1 for post-2000)
• YY is the year indicator
• MM is the month indicator
• DD is the day indicator
• HH is the hour indicator (00 = 00:00 (midnight), 23=23:00)
  Note: HH will not be generated for file system QDLS.

For example, a path of "/logs/errorlog" results in a file such as "/logs/errorlog.Q100030300".

If LogCycle is active and the path defined on an ErrorLog, CustomLog, TransferLog, or FRCACustomLog directive ends with a (/) character, then the path is considered to be the directory that will contain the log file. In that case, the server will create log files named in the QCYYMMDDHH format. For example, a path of "/logs/errorlog/" created on March 3, 2001 results in a file such as "/logs/errorlog/Q101030300".

If LogCycle is active and the path defined on an ErrorLog, CustomLog, TransferLog, or FRCACustomLog directive is in the QSYS file system, the name must end with the file component of the IFS path. Fore example:

# Config file directives
LogCycle Daily
LogFormat "%h %l %u %t \"%r\" %>s %b" common
CustomLog /QSYS.LIB/MYLIB.LIB/MYLOGS.FILE common

The resulting daily log rollovers will be of the form /QSYS.LIB/MYLIB.LIB/MYLOGS.FILE/Qcyymmddhh.MBR.

If LogCycle is not active, no special naming is used. The name of the log file given on an ErrorLog, CustomLog, TransferLog, or FRCACustomLog directive is used as given for the name of the log file.

If LogCycle Weekly is specified, rollover will occur when QDAYOFWEEK is equal to *SUN. However, if the system is not using the Gregorian calendar, this value may not be set correctly and the logs may not get rolled over as expected.

LogCycle Hourly is not valid if the log file is in the QDLS file system as that file system only supports 8 character file names and 3 character extensions.

The LogLength directive limits the size of any defined log file. To prevent problems due to unbounded growth of log files, this directive can be used to set an maximum file-size for log files. If the file exceeds this size, no more information will be written to it until logs and alertable message HTP8433 will be sent to QSYSOPR. The server will automatically restart logging requests when the logs are rolled over to the next log cycle. This directive can be specified multiple times in the configuration file.

Parameter: number-of-bytes

• The number-of-bytes parameter is an integer value that sets the maximum size limit of the log file. When any defined log file ( those defined with CustomLog, TransferLog, FRCACustomLog, or ErrorLog directives) exceeds this value, no more information will be logged until log rollover occurs. An alertable message TCP7201 will be sent to QSYSOPR. A value of 0 means there is no limit. If 'LogCycle Off' is specified and a non-zero value is specified for LogLength, when the LogLength size is reached no more logging will be done (even on starts and restarts of the server instance) since the same file will be used every time.

The LogLevel directive adjusts the verbosity of the messages recorded in the error logs. See the ErrorLog directive for more information. The following levels are available, in order of decreasing significance:

Parameter: [module:]level [module:level] ...

Level can be one of the following values:

• If emerg, system is unusable messages ("Child cannot open lock file. Exiting.").
• If alert, action must be taken immediately messages ("getpwuid: couldn't determine user name from uid.").
• If crit, critical conditions messages ("Socket: Failed to get socket, exiting child.").
• If error, error conditions messages ("Premature end of script headers.").
• If warn, warning conditions messages ("Child process 1234 did not exit, sending another SIGHUP."). If notice, normal but significant conditions messages ("httpd: caught SIGBUS, attempting to dump core in...").
• If info, informational messages ("Server seems busy, (you may need to increase ThreadPerChild)...").
• If debug, debug-level messages ("Opening config file...").
• If trace1, trace messages ("proxy: FTP: control connection complete").
• If trace2, trace messages (""proxy: CONNECT: sending the CONNECT request to the remote proxy"").
• If trace3, trace messages ("openssl: Handshake: start").
• If trace4, trace messages ("read from buffered SSL brigade, mode 0, 17 bytes").
• If trace5, trace messages ("map lookup FAILED: map=rewritemap key=keyname").
• If trace6, trace messages ("cache lookup FAILED, forcing new map lookup").
• If trace7, trace messages , dumping large amounts of data ("| 0000: 02 23 44 30 13 40 ac 34 df 3d bf 9a 19 49 39 15 |").
• If trace8, trace messages , dumping large amounts of data ("| 0000: 02 23 44 30 13 40 ac 34 df 3d bf 9a 19 49 39 15 |").

When a particular level is specified, messages from all other levels of higher significance will be reported as well. For example, when LogLevel info is specified, then messages with log levels of notice and warn will also be posted. Using a level of at least crit is recommended.

Specifying a level without a module name will reset the level for all modules to that level.

Specifying a level with a module name will set the level for that module only. It is possible to use the module source file name, the module identifier, or the module identifier with the trailing _module omitted as module specification. This means the following three specifications are equivalent:

LogLevel info ibm_ssl:warn

LogLevel info mod_ssl.c:warn

LogLevel info ibm_ssl_module:warn

It is also possible to change the level per directory:

<Directory "/www/apache/htdocs/app">
  LogLevel debug
</Directory>

Per directory loglevel configuration only affects messages that are logged after the request has been parsed and that are associated with the request. Log messages which are associated with the connection or the server are not affected.

See also ErrorLog, ErrorLogFormat

The LogMaint directive allows you perform log maintenance on the specified file and its derivatives. When log maintenance is performed on a file, it is purged from the system. Derivatives consist of either the path_to_file name provided, concatenated with the extension ".Qcyymmdd", or "Qcyymmdd" if the provided path_to_file value was a directory. LogCycle must be active in order to enable derivatives.

A separate LogMaint directive is required in the server configuration for each CustomLog or ErrorLog that requires log maintenance. The recommended way to configure maintenance is to match the path configured on the LogMaint directive with the path specified on the associated CustomLog or ErrorLog directive.

Parameter One: path_to_file

• The path_to_file value specifies the IFS-style path (for example, /QSYS.LIB/MYHTTP.LIB/MYLOGS.FILE) of the log file to be included in log maintenance. Refer to the LogCycle directive for more information on log file names and extensions.

Parameter Two: expire

• The expire value specifies an integer value indicating the number of days before a log file expires. Files older than this value are to be removed. A value of 0 means the log file will never expire. The age of the error log file is determined by the file creation date (as reported by the operating system). The file name suffix, such as errorlog.Q100082213, is not used to determine the age of the file. Files that are currently open and active in the server instance will not be removed.

Parameter Three: size_limit

• The size_limit value specifies an integer value indicating the maximum aggregate size of log files with the name path_to_file. When the combined size of the log files exceeds this value in bytes, files are deleted starting with the oldest file. Eligible files are deleted until the collective size is less than or equal to the value specified on this directive. A value of 0 means there is no size limit. Note that it is possible for the aggregate size of log files to exceed the total size_limit. This is possible due to the fact that the size of any open log files are not included in the size_limit total. Users should take this into account when they are calculating a value for size limit, and when setting a maximum value for the LogLength directive.

If both expire and size_limit are configured to non-zero values, the expired files are purged first. If the size_limits still exceeded after expired files are purged, the server continues purging files (oldest files first) until the collective log size is equal to or less than the size_limit.

The following example of log maintenance will be performed on the logs/access_log file and its derivatives (see below for details). The files will expire after 10 days. In addition, if the total limit exceeds 2,000,000 bytes, log maintenance will be performed.

LogFormat "%h %l %u %t \"%r\" %>s %b" common
CustomLog logs/access_log common
LogMaint logs/access_log 10 2000000

The following example of log maintenance will be performed on the /QSYS.LIB/MYHTTP.LIB/MYLOGS.FILE/Q* files. The files will expire after 25 days and there is no total limit on the size of the files.

LogFormat "%h %l %u %t \"%r\" %>s %b" common
CustomLog /QSYS.LIB/MYHTTP.LIB/MYLOGS.FILE common
LogMaint /QSYS.LIB/MYHTTP.LIB/MYLOGS.FILE 25 0

Only one occurrence of this directive can exist per server or virtual host container. If the directive occurs more than once, the last one specified in the server or virtual host is used.

The LogMaintHour directive may be used to control which hour of the day log maintenance occurs. The default is for log maintenance to occur at midnight. Log maintenance always occurs at the beginning of the hour. By using this directive, which hour of the day maintenance will occur can be controlled, to do maintenance in the early morning or in the evening after the normal work day is done.

The LogTime directive specifies whether your log should record entrees using local time or Greenwich Mean Time (GMT). This directive affects timestamps for log entries only.

Parameter: LocalTime | GMT

• LocalTime indicates the local time for log entry timestamps.
• GMT indicates the Greenwich Mean Time for log entry timestamp.

The MaxKeepAliveRequests directive limits the number of requests allowed per connection when KeepAlive is on. If it is set to 0, unlimited requests will be allowed.

Parameter: number

• The number parameter specifies an integer value that limits the number of requests allowed per connection when KeepAlive is on.

See KeepAlive, and KeepAliveTimeout.

The MaxRangeOverlaps directive limits the number of overlapping HTTP ranges the server is willing to return to the client. If more overlapping ranges than permitted are requested, the complete resource is returned instead.

Parameter: default | unlimited | none | number-of-ranges

• default indicates the number of overlapping ranges is limited to a compile-time default of 20.
• none indicates no overlapping Range headers are allowed.
• unlimited indicates the server does not limit the number of overlapping ranges it is willing to satisfy.
• The number-of-ranges parameter specifies a positive number representing the maximum number of overlapping ranges the server is willing to satisfy.

The MaxRangeReversals directive limits the number of HTTP Range reversals the server is willing to return to the client. If more ranges reversals than permitted are requested, the complete resource is returned instead.

Parameter: default | unlimited | none | number-of-ranges

• default indicates the number of range reversals is limited to a compile-time default of 20.
• none indicates no Range reversals headers are allowed.
• unlimited indicates the server does not limit the number of range reversals it is willing to satisfy.
• The number-of-ranges parameter specifies a positive number representing the maximum number of range reversals the server is willing to satisfy.

The MaxRanges directive limits the number of HTTP ranges the server is willing to return to the client. If more ranges than permitted are requested, the complete resource is returned instead.

Parameter: default | unlimited | none | number-of-ranges

• default indicates the number of ranges is limited to a compile-time default of 200.
• none indicates Range headers are ignored.
• unlimited indicates the server does not limit the number of ranges it is willing to satisfy.
• The number-of-ranges parameter specifies a positive number representing the maximum number of ranges the server is willing to satisfy.

By default, the server merges (or collapses) multiple consecutive slash ('/') characters in the path component of the request URL.

When mapping URL's to the filesystem, these multiple slashes are not significant. However, URL's handled other ways, such as by CGI or proxy, might prefer to retain the significance of multiple consecutive slashes. In these cases MergeSlashes can be set to OFF to retain the multiple consecutive slashes. In these configurations, regular expressions used in the configuration file that match the path component of the URL (LocationMatch, RewriteRule, ...) need to take into account multiple consecutive slashes.

This directive controls whether HTTP trailers are copied into the internal representation of HTTP headers. This merging occurs when the request body has been completely consumed, long after most header processing would have a chance to examine or modify request headers.

The option on is provided for compatibility with previous releases of HTTP server, where trailers were always merged.

Prior to i 7.2, NameVirtualHost was required to instruct the server that a particular IP address and port combination was usable as a name-based virtual host. In i 7.2 and later, any time an IP address and port combination is used in multiple virtual hosts, name-based virtual hosting is automatically enabled for that address.

This directive currently has no effect.

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

Parameter : option

• The option parameter can be set to one or more of the following:

  Option	Description
  None	None of the extra features are enabled.
  All	All options except for MultiViews.
  ExecCGI	Execution of CGI scripts is permitted.
  FollowSymLinks	The server will follow symbolic links in this directory. This is the default setting. Note: Even though the server follow the SymLink, it does not change the pathname used to match against <Directory> sections. This option gets ignored if set inside <Location> sections. The FollowSymLinks and SymLinksIfOwnerMatch Options work only in <Directory> sections or .htaccess files. Omitting this option should not be considered a security restriction, since symlink testing is subject to race conditions that make it circumventable.
  Includes	Server-side includes are permitted.
  IncludesNOEXEC	Server-side includes are permitted, but the #exec command and #include of CGI scripts are disabled.
  Indexes	If a URL which maps to a directory is requested and there is no DirectoyIndex (for example, index.html) in that directory, then the server will return a formatted listing of the directory.
  MultiViews	Content negotiated MultiViews are allowed. Note: This option gets ignored if set anywhere other than <Directory> , as mod_negotiation needs real resources to compare against and evaluate from.
  SymLinksIfOwnerMatch	The server will only follow symbolic links for which the target file or directory is owned by the same user id as the link. Note: The FollowSymLinks and SymLinksIfOwnerMatch Options work only in <Directory> sections or .htaccess files. This option should not be considered a security restriction, since symlink testing is subject to race conditions that make it circumventable.

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

For example, without any + and - symbols:

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

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

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

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

The option +IncludesNOEXEC can be used instead of +Includes.  If the previous is specified, then the SSI Exec tag is not processed during SSI processing.

The ProfileToken directive creates a 32-byte value called the ProfileToken. This token is used the same way as a userid/password combination to identify/authenticate a user, and prevents passing these values in the clear. The ProfileToken value can be used on any of the IBM i security APIs that accept a ProfileToken as input.

Parameter: on | off

• If on is specified, and basic authentication is performed successfully, the userid/password is passed in by the user (only an IBM i user) to generate a ProfileToken. A ProfileToken is not generated if this parameter is set to off, or if basic authentication was not successful.

  The ProfileToken is accessible in a CGI program via the HTTP_AS_AUTH_PROFILETKN environment variable. The HTTP_AS_AUTH_PRFILETKN environment variable is not set if a ProfileToken is not generated.

  The ProfileToken is accessible in HTTP Server modules via the headers section ( r->headers_in field), which is an internal representation of the HTTP request structure. The profile token is stored as the AS_Auth_ProfileTkn header in the headers section. HTTP Server modules can then retrieve this ProfileToken and either use it, or pass it on to another application. The AS_Auth_ProfileTkn header is not created if a ProfileToken is not generated.

This directive controls whether the server will ensure that the REDIRECT_URL environment variable is fully qualified. By default, the variable contains the verbatim URL requested by the client, such as "/index.html". With QualifyRedirectURL ON, the same request would result in a value such as "http://www.example.com/index.html".

Even without this directive set, when a request is issued against a fully qualified URL, REDIRECT_URL will remain fully qualified.

HTTP Methods that are not conforming to the relevant RFCs are normally rejected by request processing in Apache HTTP Server. To avoid this, modules can register non-standard HTTP methods they support. The RegisterHttpMethod allows to register such methods manually. This can be useful for if such methods are forwarded for external processing, e.g. to a CGI script.

This directive selects which authenticated users can access a directory.

Parameter: entity-name entity entity...

• If require user userid userid, then only the named users can access the directory.
• If require group groupname groupname, then only users in the named groups can access the directory.
• If require valid-user, then all valid users can access the directory.

Require must be accompanied by AuthName and AuthType directives, and directives such as PasswdFile and GroupFile (to define users and groups) in order to work correctly. For example:

AuthType Basic 
AuthName "Restricted Directory" 
PasswdFile web/users 
GroupFile /web/groups 
require group admin 

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

Access controls can be used in a named protection setup. To implement a named protection setup, place all of the access control directives in a file. Use the Include directive to include the file in your <Directory>, <File>, or <Location> context. This allows users that want to use the same type of protection setup within multiple contexts to add an include statement inside of each context.

The RuleCaseSense directive is used to control how requested URLs are handled.

Parameter: on | off

• When on is specified, the URLs are treated as case sensitive. This means that an exact match with case is required.
• When off is specified, the URLs are treated as case insensitive. Paths on directives and requested URLs are internally converted to upper case before they are compared.

The default value for the case sensitivity is off. Rules that map the same value in different cases to different things, for example ABC to XYZ, will not work correctly when RuleCaseSense is off. This type of mapping is not recommended.

When using protection for any URL, it is recommended that you set this directive to off. This ensures that all variations in case for your URLs are protected. If you do not protect any of your site, then this directive can be either on or off.  Setting it to Off allows your users to specify any case on their URLs and enables them to see your site.

If you use the QOpenSys file system, you will have to be careful to match the case of your file system in your directives. You will also need to be aware that case differences matter when serving files from the case sensitive file system. You should only turn this directive on when absolutely necessary.

RuleCaseSense affects the processing of the incoming URL in the "URL Fixup" and "URL translation" server phases. These phases manipulate the incoming URL and do not necessarily relate to other directives. RuleCaseSense affects the following directives: Alias, AliasMatch, RewriteBase, RewriteCond, RewriteMap, RewriteRule, ScriptAlias, and ScriptAliasMatch

The SendBufferSize directive tells the server to set the TCP buffer size to the number of specified bytes. The TCP send buffer size provides a limit on the number of outgoing bytes that are buffered by TCP. Once this limits reached, attempts to send additional bytes may result in the application blocking until the number of outgoing bytes buffered drops below this limit. The number of outgoing buffered bytes is decremented when the remote system acknowledges the sent data.

Parameter: bytes

• The bytes value is an integer that must be set to 0 or a value that is greater or equal to 512 (in bytes). If 0 is specified, the server will use the default TCP send buffer size that is configured for the IBM i server.

The ServerAdmin directive specifies the e-mail address to be used in trailing footer lines for hard coded error messages returned to clients. The specified value is used in hypertext link references generated by the server when "email" is specified for the ServerSignature directive.

Parameter: email-address

• The email-address parameter specifies a valid email address.

For example,

ServerAdmin www-admin@server.ibm.com

The ServerAlias directive sets the alternate names for a host, for use with name-based virtual hosts. The ServerAlias may include wildcards, if appropriate.

The directive allows servers to be accessible by more than one name. For example, HTTP Server might want to be accessible as ibm.org, or ftp.ibm.org, assuming the IP addresses pointed to the same server. In fact, one might want it so that all addresses at ibm.org were picked up by the server. This is possible with the ServerAlias directive placed inside the <VirtualHost> section.

For example,

<VirtualHost 10.22.33.55> 
   ServerAdmin webmaster@host.QIBM.com 
   DocumentRoot /usr/web/host.QIBM.com 
   ServerName host.QIBM.com 
   ServerAlias ibm.com *.ibm.org 
   ErrorLog logs/host.QIBM.com-error_log 
   TransferLog logs/host.QIBM.com-access_log 
</VirtualHost>

Note that you can use '*' and '?' as wildcard characters. You also might need ServerAlias if you are serving local users who do not always include the domain name. For example, if local users are familiar with typing "www" or "www.physics" then you will need to add ServerAlias www www.physics. It isn't possible for the server to know what domain the client uses for their name resolution because the client doesn't provide that information in the request.

Name-based virtual hosts for the best-matching set of <VirtualHost>s are processed in the order they appear in the configuration. The first matching ServerName or ServerAlias is used, with no different precedence for wildcards (nor for ServerName vs. ServerAlias).

The complete list of names in the VirtualHost directive are treated just like a (non wildcard) ServerAlias.

If multiple occurrences of this directive are configured in a container, only the last occurrence is processed. The other occurrences are ignored.

The ServerName directive sets the request scheme, hostname and port that the server uses to identify itself. ServerName is used (possibly in conjunction with ServerAlias) to uniquely identify a virtual host, when using name-based virtual hosts. Additionally, this is used when creating self-referential URLs when UseCanonicalName is set to a non-default value.

The ServerName directive may appear anywhere within the definition of a server. However, each appearance overrides the previous appearance (within that server). If ServerNamenot specified, the server attempts to deduce the client visible hostname by first asking the operating system for the system hostname, and if that fails, performing a reverse lookup on an IP address present on the system. however, this may not work reliably or may not return the preferred hostname.

Parameter: fully-qualified-domain-name

• The fully-qualified-domain-name parameter sets the server hostname.

For example,

ServerName simple.example.com:80
<VirtualHost 10.1.2.3> 
   ServerAdmin webmaster@host.QIBM.com 
   DocumentRoot /usr/web/host.QIBM.com 
   ServerName host.QIBM.com 
   ErrorLog logs/host.QIBM.com-error_log 
   TransferLog logs/host.QIBM.com-access_log
</VirutalHost>

This would be used if the canonical (main) name of the actual machine were simple.example.com. If you are using name-based virtual hosts, the ServerName inside a <VirtualHost> section specifies what hostname must appear in the request's Host: header to match this virtual host.

This directive allows a port to be added to the server name. This allows an administrator to assign the canonical port at the same time that the canonical name is assigned. If no port is specified, HTTP Server implies port 80 for http:// and port 443 for https:// requests. If no port is specified in the ServerName, then the server will use the port from the incoming request. For optimal reliability and predictability, you should specify an explicit hostname and port using the ServerName directive.

This setting also specifies the server name used when trailing footer lines are added to hard coded error messages (see ServerSignature).

If the server runs behind a device that processes SSL, such as a reverse proxy, load balancer or SSL offload appliance, specify the https:// scheme and the port number to which the clients connect in the ServerName directive to make sure that the server generates the correct self-referential URLs.

See also UseCanonicalName, NameVirtualHost and ServerAlias.

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

Parameter: pathname

• The pathname parameter sets the legacy URL pathname for a host, for use with name-based virtual hosts.

For example, an HTTP server exists with two name-based virtual hosts. In order to match the correct virtual host a client must send the correct Host: header. Old HTTP/1.0 clients do not send such a header and the server has no clue what virtual host the client tried to reach (and serves the request from the primary virtual host). To provide as much backward compatibility as possible, create a primary virtual host that returns a single page containing links with an URL prefix to the name-based virtual hosts.

A request to the URL http://www.sub1.domain.tld/sub1/ is always served from the sub1-virtual host. A request to the URL http://www.sub1.domain.tld/ is only served from the sub1-virtual host if the client sent a correct Host: header. If no Host: header is sent, the client gets the information page from the primary host. Note that there is one exception: a request to http://www.sub2.domain.tld/sub1/ is also served from the sub1-virtual host if the client did not send a Host: header. The RewriteRule directives are used to make sure that a client who sent a correct Host: header can use both URL variants (for example, with or without the URL prefix).

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

The directory-path parameter must specify a path in either the root ('/') or QOpenSys file system.

Parameter: directory-path

• The directory-path parameter sets the directory in which the server lives.

The ServerSignature directive specifies if trailing footer lines are to be generated for hard coded error messages returned to clients. When requests pass through a chain of servers, this feature is useful to identify which server generated the error message. The default value is off.

Parameter: on | off | email

• If on is specified, trailing footer lines containing the server name and version information are added to hard coded error messages.
• If off is specified (the default), trailing footer lines are suppressed and only hard coded error messages are returned.
• If email is specified, trailing footer lines are added and look identical to those generated when on is specified, however the server name is also a hypertext link that references the server administrator's e-mail address.

The value used for server name is that specified by the ServerName directive of the serving virtual host or server. The value used for version information is that specified by the ServerTokens directive. The value used for server administrator's e-mail address is that specified by the ServerAdmin directive.

For example, the value used for server name is that specified by the ServerName directive of the serving virtual host or server. The value used for version information is that specified by the ServerTokens directive. The value used for server administrator's e-mail address is that specified by the ServerAdmin directive.

For example,

ServerAdmin www-admin@myserver.com
ServerSignature email

The ServerTokens directive specifies which form of the Server: header value is included in response headers sent to clients. The value may consist of a minimal description of the server, a description with a generic OS-type included, a description that includes information about compiled-in modules, or a simple product description.

Parameter: Major | Minor | Minimal | OS | Full | Prod

• If Major is specified, the server sends: "Server : Apache/2"
• If Minor is specified, the server sends: "Server : Apache/2.4"
• If Minimal is specified, the server sends: "Server: Apache/2.4.12"
• If OS is specified, the server sends: "Server: Apache /2.4.12 (IBM i)"
• If Full is specified, the server sends: "Server: Apache /2.4.12 (IBM i) MymMod/1.2"
• If Prod is specified, the server sends: "Server: Apache"

This setting also specifies the version information used when trailing footer lines are added to hard coded error messages (see ServerSignature).

The ServerUserID directive specifies the user profile that the HTTP Server will run under. This directive tells what user profile to use when starting the worker threads under the child process.

Parameter: user_profile

• The user_profile parameter must be a valid user profile. This profile must be authorized to all the directories, files, and other server resources accessed by the Web server unless the server is configured to swap to another profile for specific requests or directories.

  This directive is now valid in all contexts. If userid is set and authentication is performed in a context, and the UserID value is set to %%SERVER%%, then ServerUserID will be used for that context. The ServerUserID is inherited through all contexts unlike UserID. If authentication is performed and the UserID directive is set to something other than %%SERVER%%, then ServerUserID is overridden by the UserID. If authentication is not performed at all, then ServerUserID is used from the correct context. This allows for specific and unique user id security models for separate virtual hosts, locations, directories, files or .htaccess, allowing for more security control (specific access versus "global") over the resources served by the HTTP Server.

See also UserID.

The SetHandler directive forces all matching files to be parsed through the handler given by handler-name. This happens when it is placed into an .htaccess file or a <Directory> or <Location> section. For example, if you had a directory you wanted to be parsed entirely as imagemap rule files, regardless of extension, you might put the following into an .htaccess file in that directory: See Handler for HTTP Server for more information

SetHandler imap-file 

Parameter: handler-name | None | expression

• The handler-name parameter is the name of the handler that will parse files in this directory.
• If value None is specified, an earlier defined SetHandler directive is overridden.
• Specify string-valued expressions to reference per-request variables, including backreferences to named regular expressions.

You could also use this directive to configure a particular handler for files with a particular file extension. For example:

<FilesMatch \.php$>
   SetHandler application/x-httpd-php
</FilesMatch>

String-valued expressions can be used to reference per-request variables, including backreferences to named regular expressions.

The SetInputFilter directive sets the filters that process client requests when they are received by the server. Parameter One: filter

Parameter: filter

• The filter parameter sets the filters that process client requests when they are received by the server.

For example,

<Directory /www/data/>
  SetInputFilter gzip
</Directory>

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

The order of the arguments determines the order in which the filters process the content. The first filter in the list processes content first, followed by the second in the list, and so on until all filters in the list have processed the content.

See the Apache HTTP Server Version 2.0 Filters documentation for more information regarding filters.

The SetOutputFilter directive sets the filters that process responses from the server before they are sent to the client.

Parameter: filter

• The filter parameter sets the filters that process responses from the server before they are sent to the client.

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

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

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

The order of the arguments determines the order in which the filters process the content. The first filter in the list processes content first, followed by the second in the list, and so on until all filters in the list have processed the content.

See the Apache HTTP Server Version 2.0 Filters documentation for more information regarding filters.

Use this directive to specify the maximum number of threads per server child process. If the directive is not specified, the global HTTP Server setting for maximum number of servers is used. The shipped value is 40. You can view and change global HTTP Server settings using the Change HTTP Attributes (CHGHTTPA) command.

Parameter: number

• The number value is an integer value that specifies the maximum number of threads per server child process.

The TimeOut directive defines the length of time HTTP Server will wait for I/O in various circumstances:

1. When reading data from the client, the length of time to wait for a TCP packet to arrive if the read buffer is empty.
2. When writing data to the client, the length of time to wait for an acknowledgement of a packet if the send buffer is full.
3. In mod_cgi, the length of time to wait for output from a CGI script.
4. In mod_proxy , the default timeout value if ProxyTimeout is not configured.

Parameter: number

• The number value is an integer value that specifies defines the amount of time (in seconds) HTTP Server will wait.

This directive overrides the behavior of TRACE for both the core server and mod_proxy. When "on" is specified for the TraceEnable directive, TRACE requests are permitted per RFC 2616, which disallows any request body to accompany the request. Setting the TraceEnable directive to "off" causes the core server and mod_proxy to return a 405 (Method not allowed) error response to the client.

For testing and diagnostic purposes only, request bodies may be allowed by specifying "extended" for the TraceEnable directive. The core will restrict the request body to 64 KB (plus 8 KB for chunk headers if Transfer-Encoding: chunked is used). The core will reflect the full headers and all chunk headers with the response body. As a proxy server, the request body is not restricted to 64 KB.

Parameter: on | off | extended

• A value of on permits TRACE requests.
• A value of off causes TRACE requests to return a 405 (Method not allowed) error response to the client.
• A value of extended permits TRACE requests that are not compliant for testing and diagnostic purposes.

Parameter: number

• The number value is an integer value that specifies defines the amount of time (in seconds) HTTP Server will wait.

Undoes the effect of a Define or of passing a -D argument to STRTCPSVR command.

This directive can be used to toggle the use of <IfDefine> sections without needing to alter -D arguments in HTTP server startup STRTCPSVR command.

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.

In many situations HTTP Server has to construct a self-referential URL. That is, a URL that refers back to the same server.

Parameter: on | off | DNS

• When set to on, HTTP Server will use the ServerName directive to construct a canonical name for the server. This name is used in all self-referential URLs, and for the values of SERVER_NAME and SERVER_PORT environment variables in CGIs.
• When set to off, HTTP Server will form self-referential URLs using the hostname and port supplied by the client if any are supplied (otherwise it will use the canonical name). These values are the same that are used to implement name based virtual hosts, and are available with the same clients. The CGI variables SERVER_NAME and SERVER_PORT will be constructed from the client supplied values as well.

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

• The DNS setting is intended for use with mass IP-based virtual hosting to support clients that do not provide a Host: header. With this option HTTP Server does a reverse DNS lookup on the server IP address that the client connected to in order to work out self-referential URLs.

See also ServerName.

This directive instructs the HTTP Server to use shutdown on the socket connections.

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

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

The term Virtual Host refers to the practice of running more than one web site (such as www.company1.com and www.company2.com) on a single machine. Virtual hosts can be "IP-based", meaning that you have a different IP address for every web site, or "name-based", meaning that you have multiple names running on each IP address. The fact that they are running on the same physical server is not apparent to the end user.

Parameter One: address

• The address parameter specifies a fully qualified IP address or hostname.

Parameter Two: port

• The port parameter specifies a port number. This parameter is optional. If a port is not specified the server port will be used.

<VirtualHost> and </VirtualHost> are used to enclose directives that apply only to a particular virtual host. Any directive that is allowed in a virtual host context may be used. When the server receives a document request on a particular virtual host, it uses the configuration directives enclosed in the <VirtualHost> section. The address parameter may be one of the following:

• The IP address of the virtual host.
• A fully qualified domain name for the IP address of the virtual host.
• The character *, which is used to match all IP addresses.
• The string _default_, which is used only with IP virtual hosting to catch unmatched IP addresses.

Each Virtual Host must correspond to a different IP address, different port number or a different host name for the server. In the former case, the server machine must be configured to accept IP packets for multiple addresses.

IPv6 addresses must be specified in square brackets because the optional port number could not be determined otherwise.

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

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

<VirtualHost *:80>
  ServerName www.domain.tld 
  ServerAlias domain.tld *.domain.tld
  DocumentRoot /www/domain
</VirtualHost>

<VirtualHost *:80>
  ServerName www.otherdomain.tld
  DocumentRoot /www/otherdomain
</VirtualHost>

ServerAlias domain.tld *.domain.tld