Module core

AcceptPathInfo

Module: core
Syntax: AcceptPathInfo On | Off | Default
Default: AcceptPathInfo Default
Context: server config, virtual host, directory, .htaccess
Override: none
Origin: Apache
Example: AcceptPathInfo On

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>

AcceptThreads

Module: core
Syntax: AcceptThreads number
Default: AcceptThreads 4
Context: server config
Override: none
Origin: IBM
Example: AcceptThreads 5

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.

Note: The accept threads are created one time, and that is at startup time.
Parameter: number
  • The number value specifies the maximum number of accept threads per server child process. Valid values include 1 through 20.

AccessFileName

Module: core
Syntax: AccessFileName filename [filename ...]
Default: AccessFileName .htaccess
Context: server config, virtual host, Not in Limit
Override: none
Origin: Apache
Example: AccessFileName index.html

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.

AddDefaultCharset

Module: core
Syntax: AddDefaultCharset on | off | charset
Default: AddDefaultCharset off
Context: server config, virtual host, directory, .htaccess, Not in Limit
Override: FileInfo
Origin: IBM
Example: AddDefaultCharset off

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.

AddServerHeader

Module: core
Syntax: AddServerHeader on|off
Default: AddServerHeader on
Context: server config, virtual host
Override: none
Origin: IBM
Example: AddServerHeader off

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.

AllowEncodedSlashes

Module: core
Syntax: AllowEncodedSlashes on | off | NoDecode
Default: AllowEncodedSlashes off
Context: server config, virtual host
Override: none
Origin: Apache
Example: AllowEncodedSlashes on

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.

Note: Allowing encoded slashes does not imply decoding. Occurrences of %2F or %5C (only on according systems) will be left as such in the otherwise decoded URL string.

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.

AllowOverride

Module: core
Syntax: AllowOverride override [override ..]
Default: AllowOverride none
Context: Directory
Override: none
Origin: Apache
Example: AllowOverride all
Example: AllowOverride AuthConfig Indexes

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
Override Description
None If AllowOverrideList is also set to None, the server will not read the file.
All The server will allow all directives.
AuthConfig Allow use of the authorization directives such as AuthName, AuthType, PasswdFile, Require, <RequireAll>, <RequireAny>, <RequireNone>.
FileInfo Allow use of the directives controlling document types (ErrorDocument, ForceType, LanguagePriority, SetHandler, SetInputFilter, SetOutputFilter, and mod_mime Add* and Remove* directives), document meta data (Header, RequestHeader, SetEnvIf, SetEnvIfNoCase, BrowserMatch, CookieExpires, CookieDomain,CookieStyle,CookieTracking,CookieName), mod_rewrite directives (RewriteEngine, RewriteOptions, RewriteBase, RewriteCond, RewriteRule), mod_alias directives (Redirect, RedirectTemp, RedirectPermanent, RedirectMatch), and Action from mod_actions.
Indexes Allow use of the directives controlling directory indexing such as AddDescription , AddIcon, AddIconByEncoding, AddIconByType, DefaultIcon, DirectoryIndex, IndexOptions, HeaderName, IndexIgnore, IndexOptions and ReadmeName.
Limit Allow use of the directives controlling host access such as Allow, Deny and Order.
Nonfatal=[Override|Unknown|All] Allow use of AllowOverride option to treat syntax errors in .htaccess as non-fatal: instead of causing an Internal Server Error, disallowed or unrecognized directives will be ignored and a warning logged:
Nonfatal=Override treats directives forbidden by AllowOverride as non-fatal.
Nonfatal=Unknown treats unknown directives as non-fatal. This covers typos and directives implemented by a module that's not present.
Nonfatal=All treats both the above as non-fatal
Note: Note that a syntax error in a valid directive will still cause an internal server error.
Security: Nonfatal errors may have security implications for .htaccess users. For example, if AllowOverride disallows AuthConfig, users' configuration designed to restrict access to a site will be disabled.
Options Allow use of the directives controlling specific directory features such as Options.
Note:

AllowOverride is valid only in Directory sections specified without regular expressions, not in Location, DirectoryMatch or Files sections.

The use of .htaccess is not supported in QDLS and QSYS. For these file systems the AllowOverride override value needs to be None to avoid errors that keep a page from being served.

AllowOverrideList

Module: core
Syntax: AllowOverrideList None|directive [directive-type] ...
Default: AllowOverrideList None
Context: directory
Override: none
Origin: Apache
Example: AllowOverrideList Redirect RedirectMatch

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.

Note: AllowOverrideList is valid only in <Directory> sections specified without regular expressions, not in <Location>, <DirectoryMatch> or <Files> sections.

See alsoAccessFileName , AllowOverride.

CGIVar

Module: core
Syntax: CGIVar variable rule
Default: None
Context: Directory, .htaccess
Override: FileInfo
Origin: Apache
Example: CGIVar REQUEST_URI current-uri

This directive controls how some CGI variables are set.

REQUEST_URI rules:

original-uri (default)

The value is taken from the original request line, and will not reflect internal redirects or subrequests which change the requested resource.

current-uri

The value reflects the resource currently being processed, which may be different than the original request from the client due to internal redirects or subrequests.

DefaultFsCCSID

Module: ap_charset
Syntax: DefaultFsCCSID server-character-set-identification-number
Default: dependent on server settings
Context: server config
Override: none
Origin: IBM
Example: DefaultFsCCSID 37

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

DefaultNetCCSID

Module: mod_cgi
Syntax: DefaultNetCCSID client-character-set-identification-number
Default: Global HTTP Server setting for coded character set identifier.
Context: server config, virtual host, directory, .htaccess
Override: none
Origin: IBM
Example: DefaultNetCCSID 819
The DefaultNetCCSID directive specifies the client character set environment and defines the ASCII or UTF-8 CCSID that is used when converting:
  • Input request data for user CGI programs or Apache modules.
  • When serving EBCDIC documents and no ASCII CCSID can be deduced from the file CCSID.
  • 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 DefaultNetCCSID directive, but the last directive in the configuration file determines the CCSID. Starting in IBM i 5.4, the use of this directive is expanded to help you configure a single server to handle requests in more than one language. The directive is now allowed in a virtual host container and in directory containers. This directive is supported in the global scope. If the directive is not specified, the global HTTP Server setting for coded character set identifier is used. The shipped value is 00819 (ISO 8859-1 8-bit ASCII). You can view and change global HTTP Server settings using the Change HTTP Attributes (CHGHTTPA) command.

DefaultType

Module: core
Syntax: DefaultType media-type |none
Default: DefaultType none
Context: server config, virtual host, directory, .htaccess
Override: FileInfo
Origin: Apache
Example: DefaultType image/gif

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.

Define

Module: core
Syntax: Define parameter-name [parameter-value]
Default: None
Context: server, virtual host, directory
Override: none
Origin: Apache
Example: Define SSL
Example: Define servername www.example.com

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.

Virtual Host scope and pitfalls

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.

<Directory>

Module: core
Syntax: <Directory directory> ... </Directory>
Default: none
Context: server config, virtual host, Not in Limit
Override: none
Origin: Apache
Example: <Directory /usr/local/httpd/htdocs>

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

Notes:
  • The default HTTP Server access for <Directory /> is Allow from All. This means that HTTP Server will serve any file mapped from a URL. The GUI directory wizard automatically creates a root directory that denies access to all and doesn't allow htaccess file usage:
    <Directory />          
       Options None        
       AllowOverride None  
       order deny,allow    
       deny from all       
    </Directory> 

    Then override this for directories you want accessible. See the Security tips for HTTP Server or User profiles and required authorities for HTTP Server pages for more details. <Directory> directives can only be in virtual host and the server configuration see context above.

    Previously, <Directory> containers were used to enclose groups of directives that applied to proxy requests by appending the prefix "proxy:" to the beginning of the specified directory name. This is no longer supported. The server now has proxy containers for this purpose. The proxy now ignores directives enclosed in directory (or file) containers, and uses proxy containers. See <Proxy> and <ProxyMatch> for more information.
  • Directives within location containers (if matched) take precedence over directives within directory containers. See <Location> and <LocationMatch> directives for more information on location containers.

<DirectoryMatch>

Module: core
Syntax: <DirectoryMatch regex> ... </DirectoryMatch>
Default: none
Context: Server config, Virtual host
Override: none
Origin: Apache
Example: <DirectoryMatch "^/www/.*/[0-9]{3}">

<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 would match directories in /www/ that consisted of three numbers.

Note: The argument to DirectoryMatch does not need to be in quotes unless the regular expression includes a space character.
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> .

DocumentRoot

Module: core
Syntax: DocumentRoot directory-path
Default: DocumentRoot /QIBM/UserData/HTTPA/htdocs
Context: server config, virtual host, Not in Limit
Override: none
Origin: Apache
Example: DocumentRoot /QIBM/UserData/mydocs

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

<Else>

Module: core
Syntax:<Else>...</Else>
Default: None
Context: Server config, Virtual Host, directory, .htaccess
Override: All
Origin: Apache

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>

Expressions in Apache HTTP server, for a complete reference and more examples.

Nested <Else> configuration blocks are evaluated.

<ElseIf>

Module: core
Syntax:<ElseIf expression>...</ElseIf>
Default: None
Context: server config, Virtual Host, directory, .htaccess
Override: All
Origin: Apache

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>

<Else>

Expressions in Apache HTTP server, for a complete reference and more examples.

Nested <ElseIf> configuration blocks are evaluated.

Error

Module: core
Syntax: Error message
Default: None
Context: Server, Virtual Host, directory, .htaccess
Override: none
Origin: Apache

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>

EnableSendfile

Module: core
Syntax: EnableSendfile on|off
Default: EnableSendfile on
Context: server config, virtual host, directory, .htaccess
Override: FileInfo
Origin: Apache
Example: EnableSendfile off

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.

ErrorDocument

Module: core
Syntax: ErrorDocument error-code document
Default: none
Context: server config, virtual host, directory, .htaccess, Not in Limit
Override: FileInfo
Origin: Modified
Example: ErrorDocument 404 /cgi-bin/bad_urls.html
Example: ErrorDocument 500 http://QIBM.example.com/cgi-bin/tester
Example: ErrorDocument 401 /subscription_info.html
Example: ErrorDocument 403 "Sorry, cannot allow you access today."

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.

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. 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.   
Note: When you specify an ErrorDocument that points to a remote URL (for example, anything with a method such as "http" in front of it) the server will send a redirect to the client to tell it where to find the document, even if the document ends up being on the same server. This has several implications, the most important being that if you use an "ErrorDocument 401" directive then it must refer to a local document. This results from the nature of the HTTP basic authentication scheme.

IBM HTTP Server for 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:

Error code Error meaning
okredirect 302 The document has moved.
badrequest 400 The request is not valid.
badscript 400 The requested script file could not be processed; the request was invalid in some way.
connectfail 400 The server could not connect to the requested partner on the requested port.
nopartner 400 The server could not connect to the requested host name due to bad syntax or an unknown host.
proxyfail 400 or 502 The client tried to use the server as a proxy and, although this is allowed, it did not work. Possibly the destination server doesn't exist or is busy.
proxyrmterror (any code >= 400) The server received a response code from a remote server that indicates a remote server problem and the proxy error override function has been invoked (see ProxyErrorOverride for more details).
unknownmethod 400 The request did not include a recognized method.
notauthorized 401 The request requires a user ID and password. Either the user ID and password sent by the client are not valid for this request or the client did not send a user ID and password.
notmember 401 The requested file has a protection rule listing valid user IDs and passwords and the user ID of the requesting client is not included in the list.
pwchanged 401 The password is invalid.
pwexpired 401 The password for the user ID has expired.
badredirect 403 The server is trying to redirect the request and the Redirect directive is invalid or contains a loop.
baduser 403 The client requested a user's home directory that does not exist.
byrule 403 A directive (such as deny or allow directive) or rule was specified that will not allow this request.
dirbrowse 403 The request specified a directory that is turned off for browsing.
dotdot 403 The client request specified a parent (/.../) directory which is not allowed.
ipmask 403 The client's IP address is not a vlid IP address for the request.
ipmaskproxy 403 The client is trying to use the server as a proxy, however the client is not included in the list of host names or IP addresses that are allowed to do so.
methoddisabled 403 The method requested has been disabled.
noacl 403 Cannot access the .htaccess file.
noentry 403 The user is not included in the list of valid users for this request.
notallowed 403 The server found the requested file but the protection setup of the server prevented access.
openfailed 403 The file or directory has access restrictions for the current user.
multifail 404 The requested file could not be found on the server.
proxynotauth 407 The request requires a user ID and password for the proxy. Either the user ID and password sent by the client are not valid for this request or the client did not send a user ID and password.
proxynotmember 407 The requested file has a protection rule listing valid user IDs and passwords and the user ID sent by the client is not included in that list.
proxypwchanged 407 The password sent by the client is not valid for the proxy.
proxypwexpired 407 The password sent by the client has expired.
preconfail 412 A precondition specified by the client on this request was not met. For example, this could result from HTTP/1.1 request that contains a condition "if-not-modified-since xxx".
badrange 416 The request either has an invalid content range header or it has incorrect information in the content range header for the file being processed.
upgrade 426 The request was received for a file which must be accessed through SSL. An upgrade to SSL is required before accessing this resource.
scriptio 500 The client requested a CGI script but the server cannot get it to process input or output. The script may contain invalid code.
scriptnotfound 500 The client requested a CGI script that cannot be found.
scriptstart 500 The client requested a CGI script that the server can find but cannot be started. The script may contain invalid code.
systemerror 500 An internal error occurred.
noformat 501 The server cannot interpret the format of the file it is trying to serve. The file may be corrupted or have an unknown or invalid file extension.

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.

ErrorLog

Module: core
Syntax: ErrorLog filename-or-pipe | off | *off
Default: ErrorLog logs/error_log
Context: server config, virtual host
Override: none
Origin: Apache
Example: IFS example relative to server root: ErrorLog logs/errorlog
Example: Piped log example: ErrorLog |/QSYS.LIB/MYLIB.LIB/ERRPIPE.PGM
Example: QSYS example: ErrorLog /QSYS.LIB/MYLIB.LIB/MYLOGS.FILE

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.
Note: A new program will not be started for a VirtualHost if it inherits the ErrorLog from the main server. The program is specified in the form "qsys.lib/xxx.lib/xxx.pgm".

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

Module: core
Syntax: ErrorLogFormat [connection|request] format
Default: None
Context: server config, Virtual host
Override: none
Origin: Apache
Example: ErrorLogFormat "[%t] [%l] [pid %P] %F: %E: [client %a] %M"

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.

Modified Token Meaning
%-{Referer}i Logs a - if Referer is not set.
%+{Referer}i Omits the entire line if Referer is not set.
%4{Referer}i %4{Referer}i Logs the Referer only if the log message severity is higher than 4.

Some format string items accept additional parameters in braces.

Format String Description
%% The percent sign
%a Client IP address and port of the request
%{c}a Underlying peer IP address and port of the connection (see the mod_remoteip module)
%A Local IP-address and port
%{name}e Request environment variable name
%E APR/OS error status code and string
%F Source file name and line number of the log call
%{name}i Request header name
%k Number of keep-alive requests on this connection
%l Loglevel of the message
%L Log ID of the request
%{c}L Log ID of the connection
%{C}L Log ID of the connection if used in connection scope, empty otherwise
%m Name of the module logging the message
%M The actual log message
%{name}n Request note name
%P Process ID of current process
%T Thread ID of current thread
%t The current time
%{u}t The current time including micro-seconds
%{cu}t The current time in compact ISO 8601 format, including micro-seconds
%v The canonical ServerName of the current server.
%V The server name of the server serving the request according to the UseCanonicalName setting.
\ (backslash space) Non-field delimiting space
% (percent space) Field delimiter (no output)

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"

FileETag

Module: core
Syntax: FileETag component ...
Default: FileETag MTime Size
Context: server config, virtual host, directory, .htaccess
Override: FileInfo
Origin: Apache
Example: FileETag INode MTime Size

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.

<Files>

Module: core
Syntax: <Files filename> ... </Files>
Default: none
Context: server config, virtual host, .htaccess, Not in Limit
Override: none
Origin: Apache
Example: <Files index.html>

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.
Note: Unlike <Directory> and <Location> sections, <Files> sections can be used inside .htaccess files. This allows users to control access to their own files, at a file-by-file level. See Security tips for HTTP Server and User profiles and required authorities for HTTP Server for more details.

<FilesMatch>

Module: core
Syntax: <FilesMatch regex> ... </FilesMatch>
Default: none
Context: server config, virtual host, .htaccess, Not in Limit
Override: none
Origin: Apache
Example: <FilesMatch "\.(gif|jpe?g|png)$">

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

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.

ForceType

Module: core
Syntax: ForceType media_ type
Default: none
Context: directory, .htaccess
Override: FileInfo
Origin: Apache
Example: ForceType image/gif (forces all files in the container to be treated as a GIF file)

The ForceType directive forces all matching files to be served as the content type 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.
Note: This overrides any filename extensions that might determine the media type.

HostNameLookups

Module: core
Syntax: HostNameLookups on | off | double
Default: HostNameLookups off
Context: server config, virtual host, directory, Not in Limit
Override: none
Origin: Apache
Example: HostNameLookups on

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.
Note: The result of this double-reverse isn't generally available unless you set HostnameLookups double. For example, if you only set HostnameLookups on and a request is made to an object that is protected by hostname restrictions, regardless of whether the double-reverse fails or not, CGIs will still be passed to the single-reverse result in REMOTE_HOST.

HotBackup

Module: core
Syntax: HotBackup on | off
Default: HotBackup on
Context: server config
Override: none
Origin: IBM
Example: HotBackup on

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.
Note: When a server is configured as highly available (HAModel directive is specified), HotBackup behaves as if it is set to 'off' and can not be overwritten.

HTTPSubsystemDesc

Module: core
Syntax: HTTPSubsystemDesc library | subsystem
Default: HTTPSubsystemDesc QHTTPSVR/QHTTPSVR
Context: server config
Override: none
Origin: IBM
Example: HTTPSubsystemDesc HTTPTEST/HTTPSBS

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

Note: To make HTTP server run in subsystem other than QHTTPSVR, at least HTTPStartJobQueue directive is required to be specified and the desired subsystem is MUST in active status before starting HTTP server. If only HTTPSubsystemDesc directive is specified, only the specified subsystem is started and HTTP server jobs still run under QHTTPSVR. If only HTTPStartJobQueue is specified but the desired subsystem is not active at that moment, the HTTP server jobs will not be started until the subsystem is started

HTTPStartJobQueue

Module: core
Syntax: HTTPStartJobQueue library | jobqueue
Default: HTTPStartJobQueue QHTTPSVR/QZHBHTTP
Context: server config
Override: none
Origin: IBM
Example: HTTPStartJobQueue HTTPTEST/HTTPJOBQ

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.

Note: To make HTTP server run in subsystem other than QHTTPSVR, at least HTTPStartJobQueue directive is required to be specified and the desired subsystem is MUST in active status before starting HTTP server. If only HTTPSubsystemDesc directive is specified, only the specified subsystem is started and HTTP server jobs still run under QHTTPSVR. If only HTTPStartJobQueue is specified but the desired subsystem is not active at that moment, the HTTP server jobs will not be started until the subsystem is started.

HTTPStartJobDesc

Module: core
Syntax: HTTPStartJobDesc library | jobdescription
Default: HTTPStartJobDesc QHTTPSVR/QZHBHTTP
Context: server config
Override: none
Origin: IBM
Example: HTTPStartJobDesc HTTPTEST/HTTPJOBD

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.

Note: To make HTTP server run in subsystem other than QHTTPSVR, at least HTTPStartJobQueue directive is required to be specified and the desired subsystem is MUST in active status before starting HTTP server. If only HTTPSubsystemDesc directive is specified, only the specified subsystem is started and HTTP server jobs still run under QHTTPSVR. If only HTTPStartJobQueue is specified but the desired subsystem is not active at that moment, the HTTP server jobs will not be started until the subsystem is started.

HTTPRoutingData

Module: core
Syntax: HTTPRoutingData name
Default: HTTPRoutingData HTTPWWW
Context: server config
Override: none
Origin: IBM
Example: HTTPRoutingData HTTPSVR

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.

Note: To make HTTP server run in subsystem other than QHTTPSVR, at least HTTPStartJobQueue directive is required to be specified and the desired subsystem is MUST in active status before starting HTTP server. If only HTTPSubsystemDesc directive is specified, only the specified subsystem is started and HTTP server jobs still run under QHTTPSVR. If only HTTPStartJobQueue is specified but the desired subsystem is not active at that moment, the HTTP server jobs will not be started until the subsystem is started.

<If>

Module: core
Syntax: <If expression> ... </If>
Default: none
Context: Server config, Virtual Host, directory, .htaccess
Override: All
Origin: Apache
Example: <If "-z req('Host')">

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>

Nested <If> configuration blocks are evaluated.

<IfDefine>

Module: core
Syntax: <IfDefine [!]parameter-name> ... </IfDefine>
Default: none
Context: server config
Override: All
Origin: Apache
Example: <IfDefine LDAP>

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.

<IfDirective>

Module: core
Syntax: <IfDirective [!]directive-name> ... </IfDirective>
Default: none
Context: Server, Virtual Host, Directory, .htaccess
Override: All
Origin: Apache
Example:

<IfDirective RewriteRule> 
     RewriteEngine on
</IfDirective>

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

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

  • directive-name
  • !directive-name

In the former case, the directives between the start and end markers are only processed if a directive of the given name is available at the time of processing. The second format reverses the test, and only processes the directives if directive-name is not available.

This section should only be used if you need to have one configuration file that works across multiple versions of HTTP Server, regardless of whether a particular directive is available. In normal operation, directives need not be placed in <IfDirective> sections.

<IfFile>

Module: core
Syntax: <IfFile [!]filename> ... </IfFile>
Default: none
Context: Server, Virtual Host, Directory, .htaccess
Override: All
Origin: Apache
Example:

<IfFile /www/apache24/htdocs/abc.htaccess> 
     AllowOverride all
</IfFile>

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

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

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

<IfModule>

Module: core
Syntax: <IfModule [!]module-name> ... </IfModule>
Default: none
Context: server config, virtual host, directory, .htaccess
Override: none
Origin: Apache
Example: <IfModule test>

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.

<IfSection>

Module: core
Syntax: <IfSection [!]section-name> ... </IfSection>
Default: none
Context: server, virtual host, directory, .htaccess
Override: All
Origin: Apache
Example:

<IfSection VirtualHost>
   ...
</IfSection>

The <IfSection test>...</IfSection> section is used to mark directives that are conditional on the presence of a specific section directive. A section directive is any directive such as <VirtualHost> which encloses other directives, and has a directive name with a leading "<".

The directives within an <IfSection> section are only processed if the test is true. If test is false, everything between the start and end markers is ignored.

The section-name must be specified without either the leading "<" or closing ">". The test in the <IfSection> section can be one of two forms:

  • section-name
  • !section-name

In the former case, the directives between the start and end markers are only processed if a section directive of the given name is available at the time of processing. The second format reverses the test, and only processes the directives if section-name is not an available section directive.

For example:


<IfSection VirtualHost>
   ...
</IfSection>

This section should only be used if you need to have one configuration file that works across multiple versions of HTTP server, regardless of whether a particular section directive is available. In normal operation, directives need not be placed in <IfSection> sections.

Include

Module: core
Syntax: Include filename|wildcard
Default: none
Context: server config, virtual host, directory
Override: none
Origin: Apache
Example: Include conf/mydirectory/myfile
Example: Include conf/vhosts/*.conf

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

Note: The filename specified with this directive must be in a file in the Root or QOpenSys file systems. Other file systems are not supported.

See also IncludeOptional

IncludeOptional

Module: core
Syntax: Include filename|wildcard
Default: None
Context: server config, Virtual Host, directory
Override: none
Origin: Apache
Other Considerations: Note: The changes in green only supported by i 7.4 which upgraded to apache 2.4.34

This directive allows inclusion of other configuration files from within the server configuration files. It works identically to the Include directive, but it will be silently ignored (instead of causing an error) if wildcards are used and they do not match any file or directory or if a file path does not exist on the file system.

See also Include

KeepAlive

Module: core
Syntax: KeepAlive on | off
Default: KeepAlive on
Context: server config, virtual host, Not in Limit
Override: none
Origin: Apache
Example: KeepAlive off

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.

KeepAliveTimeout

Module: core
Syntax: KeepAliveTimeout num[ms]
Default: KeepAliveTimeout 300
Context: server config, virtual host
Override: none
Origin: Apache
Example: KeepAliveTimeout 500

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.

See also KeepAlive, MaxKeepAliveRequests, and TimeOut.

In a name-based virtual host context, the value of the first defined virtual host best matching the local IP and port will be used.

<Limit>

Module: core
Syntax: <Limit method [method]... > ... </Limit>
Default: none
Context: directory, .htaccess
Override: AuthConfig, Limit
Origin: Apache
Example: <Limit GET PUT>

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>

Module: core
Syntax: <LimitExcept method [method] ... > ... </LimitExcept>
Default: none
Context: directory, .htaccess
Override: AuthConfig, Limit
Origin: Apache
Example: <LimitExcept GET >... </LimitExcept>

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

LimitRequestBody

Module: core
Syntax: LimitRequestBody number
Default: LimitRequestBody 0
Context: serve config, virtual host, directory, .htaccess
Override: All
Origin: Apache
Example: LimitRequestBody 100

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

LimitInternalRecursion

Module: core
Syntax: LimitInternalRecursion number [number]
Default: LimitInternalRecursion 10
Context: server, virtual host
Override: none
Origin: Apache
Example: LimitInternalRecursion 5

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 deep subrequests may be nested. If you specify only one number, it will be assigned to both limits.

LimitRequestFields

Module: core
Syntax: LimitRequestFields number
Default: LimitRequestFields 100
Context: server config, Not in Limit
Override: none
Origin: Apache
Example: LimitRequestFields 800

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.

LimitRequestFieldsize

Module: core
Syntax: LimitRequestFieldsize number
Default: LimitRequestFieldsize 32766
Context: server config, Not in Limit
Override: none
Origin: Apache
Example: LimitRequestFieldsize 8000

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

LimitRequestLine

Module: core
Syntax: LimitRequestLine number
Default: LimitRequestLine 8190
Context: server config, Not in Limit
Override: none
Origin: Apache
Example: LimitRequestLine 8000

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

LimitXMLRequestBody

Module: core
Syntax: LimitXMLRequestBody number
Default: LimitXMLRequestBody 1000000
Context: server config, virtual host, directory (but not location), .htaccess, Not in Limit
Override: none
Origin: Apache
Example: LimitXMLRequestBody 1000000

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

Listen

Module: core
Syntax: Listen [IP address:] port number [protocol]
Default: Listen 80
Context: server config
Override: none
Origin: Apache
Example: Listen 8000
Example: Listen 8000 FRCA
Note: FRCA support for the Listen directive is not available for V5R1 and earlier releases of HTTP Server.

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. The protocol is used to determine which module should handle a request, and to apply protocol specific optimizations with the AcceptFilter directive. You only need to set the protocol if you are running on non-standard ports. For example, running an https site on port 8443:
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.

ListenBacklog

Module: core
Syntax: ListenBacklog backlog
Default: ListenBacklog 511
Context: server config, Not in Limit
Override: none
Origin: Apache
Example: ListenBacklog 400

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.

<Location>

Module: core
Syntax: <Location url> ... </Location>
Default: none
Context: server config, virtual host, Not in Limit
Override: none
Origin: Apache
Example:
Alias /a /b
<Location /a>

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.

Note: URLs do not have to line up with the file system. <Location> operates completely outside the file system.

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
   order deny,allow
   deny from all
   allow from .QIBM.com
</Location>
Note: The slash character has special meaning depending on where in a URL it appears. People may be used to its behavior in the file system where multiple adjacent slashes are frequently collapsed to a single slash (for example, /home///QIBM is the same as /home/QIBM). For <Location> this is not necessarily true. The <LocationMatch> directive and the regex version of <Location> require you to explicitly specify multiple slashes if that is your intention. For example, <LocationMatch ^/ABC> would match the request URL /ABC but not the request URL //ABC. The (non-regex) <Location> directive behaves similarly when used for proxy requests. But when (non-regex) <Location> is used for non-proxy requests it will implicitly match multiple slashes with a single slash. For example, if you specify <Location /ABC/def> and the request is to /ABC//def, the request will match the location.

<LocationMatch>

Module: core
Syntax: <LocationMatch regex> ... </LocationMatch>
Default: none
Context: server config, virtual host, Not in Limit
Override: none
Origin: Apache
Example: <LocationMatch "/(extra|special)/data">

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

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>

LogCycle

Module: core
Syntax: LogCycle Off | Hourly | Daily | Weekly | Monthly
Default: LogCycle Daily
Context: server config, Not in Limit
Override: none
Origin: IBM
Example: LogCycle Monthly

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.
Note: Daily and monthly log rollovers will always occur at midnight. Hourly rollovers will occur at the top of the hour. At the end of a log cycle, HTTP Server will roll over all logs. That means that it will flush all entries to the log file, close the current logs, and create a log file with a timestamp for the next log cycle.

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.

LogLength

Module: core
Syntax: LogLength number-of-bytes
Default: LogLength 0
Context: server config, Not in Limit
Override: none
Origin: IBM
Example: LogLength 1000000

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.
Security notes:
  • 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. Be sure that the program is secure.

LogLevel

Module: core
Syntax: LogLevel [module:]level [module:level] ...
Default: LogLevel warn
Context: server config, virtual host, directory
Override: none
Origin: Apache
Example: LogLevel debug
Example: LogLevel info ibm_ssl_module:warn

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

LogMaint

Module: core
Syntax: LogMaint path_to_file expire size_limit
Default: none
Context: server config, virtual host
Override: none
Origin: IBM
Example: LogMaint logs/access_log 10 2000000
Note: If this directive is not present, log maintenance is not performed. If the directive is present, all parameters are required. Values of 0 for expire and size_limit have a special meaning of no limit. If a LogMaint directive with values of 0 for both expire and size_limits specified, no log maintenance will be done on the specified file.

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.

Note: If invalid values are used for expire or size_limit, an error message will be placed into the job log and the HTTP Server will not start.

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.

Note: If LogCycle is configured to Off, then log maintenance is not performed.

LogMaintHour

Module: core
Syntax: LogMaintHour variable
Default: LogMaintHour 0
Context: server config, virtual host
Override: none
Origin: IBM
Example: LogMaintHour 3

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.

LogTime

Module: core
Syntax: LogTime LocalTime | GMT
Default: LogTime LocalTime
Context: server config, virtual host, Not in Limit
Override: none
Origin: IBM
Example: LogTime GMT

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.

MaxKeepAliveRequests

Module: core
Syntax: MaxKeepAliveRequests number
Default: MaxKeepAliveRequests 100
Context: server config, virtual host, Not in Limit
Override: none
Origin: Apache
Example: MaxKeepAliveRequests 50

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.

MaxRangeOverlaps

Module: core
Syntax: MaxRangeOverlaps default | unlimited | none | number-of-ranges
Default: MaxRangeOverlaps 20
Context: Server config, Virtual Host, directory
Override: none
Origin: Apache

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.

MaxRangeReversals

Module: core
Syntax: MaxRangeReversals default | unlimited | none | number-of-ranges
Default: MaxRangeReversals 20
Context: Server config, Virtual Host, directory
Override: none
Origin: Apache

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.

MergeSlashes

Module: core
Syntax: MergeSlashes on | off
Default: MergeSlashes on
Context: Server, Virtual Host
Override: none
Origin: Apache
Example: MergeSlashes Off

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.

MergeTrailers

Module: core
Syntax: MergeTrailers on | off
Default: MergeTrailers off
Context: Server Config, Virtual Host
Override: none
Origin: Apache
Example: MergeTrailers on

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.

MaxRanges

Module: core
Syntax: MaxRanges default | unlimited | none | number-of-ranges
Default: MaxRanges 200
Context: Server config, Virtual Host, directory
Override: none
Origin: Apache

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.

MergeTrailers

Module: core
Syntax: MergeTrailers on | off
Default: MergeTrailers off
Context: Server Config, Virtual Host
Override: none
Origin: Apache
Example: MergeTrailers on

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.

NameVirtualHost

Module: core
Syntax: NameVirtualHost address[:port]
Default: none
Context: server config
Override: none
Origin: Apache
Example: NameVirtualHost 10.1.1.1

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.

Options

Module: core
Syntax: Options [+|-]option [[+|-]option ...]
Default: Options FollowSymlinks
Context: server config, Virtual Host, directory, .htaccess
Override: Options
Origin: Apache
Example: Options +Indexes +FollowSymLinks

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.

Note: Using -IncludesNOEXEC or -Includes disables server-side includes completely regardless of the previous setting. The default in the absence of any other settings is FollowSymlinks.

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.

ProfileToken

Module: core
Syntax: ProfileToken on | off
Default: ProfileToken off
Context: directory
Override: AuthConfig
Origin: IBM
Example: ProfileToken on

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.

ReceiveBufferSize

Module: core
Syntax: ReceiveBufferSize bytes
Default: ReceiveBufferSize 0
Context: server config
Override: none
Origin: Apache
The ReceiveBufferSize directive can be used to control the TCP receive buffer size for the server. The server will set the TCP receive buffer size to the number of bytes specified.
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 receive buffer size that is configured for the IBM i server.

RegexDefaultOptions

Module: core
Syntax: RegexDefaultOptions [none] [+|-]option [[+|-]option] ...
Default: RegexDefaultOptions DOLLAR_ENDONLY
Context: Server
Override: none
Origin: Apache
Example: RegexDefaultOptions +ICASE +DOLLAR_ENDONLY

This directive adds some default behavior to ANY regular expression used afterwards.

Any option preceded by a '+' is added to the already set options.

Any option preceded by a '-' is removed from the already set options.

Any option without a '+' or a '-' will be set, removing any other already set option.

The none keyword resets any already set options.

option can be:

ICASE
  • Use a case-insensitive match.
DOTALL
  • Perl's /s flag.
DOLLAR_ENDONLY
  • '$' matches at end of subject string only.
# 
RegexDefaultOptions +ICASE +DOLLAR_ENDONLY
...
# Remove the ICASE option, but keep all the other already set options
RegexDefaultOptions -ICASE
...
# Set the default option to DOTALL, resetting any other option
RegexDefaultOptions DOTALL
...
# Reset all defined option
RegexDefaultOptions none
...

Require

Module: core
Syntax: require entity-name entity entity...
Default: none
Context: directory, .htaccess
Override: AuthConfig
Origin: Apache
Example: require group admin

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.

Note: The require valid-user directive parameter should NOT be configured in the same context as any require user or require group directive parameters. The require directives are processed in order (from top to bottom) as they appear in the configuration file. Since require valid-user allows access to any authenticated user, the require valid-user directive parameter effectively overrides the presence of any require user or require group directives.

RuleCaseSense

Module: core
Syntax: RuleCaseSense on | off
Default: RuleCaseSense off
Context: server config
Override: none
Origin: IBM
Example: RuleCaseSense on

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

SendBufferSize

Module: core
Syntax: SendBufferSize bytes
Default: SendBufferSize 0
Context: server config
Override: none
Origin: Apache
Example: SendBufferSize 4000

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.

SendFileMinSize

Module: core
Syntax: SendFileMinSize bytes
Default: SendBufferSize 16000
Context: server
Override: none
Origin: Apache
Example: SendBufferSize 150
This directive specifies the minimum size of a file that is allowed to be sent via sendfile. SendFileMinSize is an IBM i specific directive. This directive may also limit the caching of local files when using the CacheLocalFD. A file that is Cached using CacheLocalFD must be served using sendfile. Because of this, when using CacheLocalFD, a file is only cached when its size is greater than SendFileMinSize.
Note: Files larger than SendFileMinSize will not be cached dynamically.

ServerAdmin

Module: core
Syntax: ServerAdmin email-address
Default: none
Context: server config, Not in Limit
Override: none
Origin: Apache
Example: ServerAdmin www-admin@myserver.com

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
Note: This setting is not used if ServerSignature is not set to "email", or for errors handled by custom error messaging (see ErrorDocument for more details on custom error messaging).

ServerAlias

Module: core
Syntax: ServerAlias host1 [host2 ...]
Default: none
Context: virtual host
Override: none
Origin: Apache
Example: ServerAlias ibm.com® * .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.

ServerName

Module: core
Syntax: ServerName fully-qualified-domain-name [:port]
Default: none
Context: server config, virtual host, Not in Limit
Override: none
Origin: Apache
Example: ServerName www.example.com

The ServerName directive sets the server hostname. This setting is used when creating redirection URLs. If it is not specified, the server attempts to deduce the client visible hostname by performing a reverse lookup on an IP address of the systems hostname; 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. This setting also specifies the server name used when trailing footer lines are added to hard coded error messages (see ServerSignature).

Note: TCP/IP must be properly configured to recognize all possible server host names.

See also UseCanonicalName, NameVirtualHost and ServerAlias.

ServerPath

Module: core
Syntax: ServerPath pathname
Default: none
Context: virtual host, Not in Limit
Override: none
Origin: Apache
Example: ServerPath /sub1/

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

ServerRoot

Module: core
Syntax: ServerRoot directory-path
Default: none
Context: server config
Override: none
Origin: Apache
Example: ServerRoot /www/webserver

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.

ServerSignature

Module: core
Syntax: ServerSignature on | off | email
Default: ServerSignature off
Context: server config, virtual host, directory, .htaccess, Not in Limit
Override: none
Origin: Apache
Example: ServerSignature on

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
Note: This setting is not used for errors handled by custom error messaging (see ErrorDocument for more details on custom error messaging).

ServerTokens

Module: core
Syntax: ServerTokens Major | Minor | Minimal | OS | Full | Prod
Default: ServerTokens Prod
Context: server config
Override: none
Origin: Apache
Example: ServerTokens Full

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

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

ServerUserID

Module: core
Syntax: ServerUserID user_profile
Default: ServerUserID QTMHHTTP
Context: All
Override: AuthConfig
Origin: IBM
Example: ServerUserID webmaster

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.

Note: To start the server you must have authority to the specified profile.

See also UserID.

SetHandler

Module: core
Syntax: SetHandler handler-name| None
Default: none
Context: server config, virtual host, directory, .htaccess
Override: none
Origin: Apache
Example: SetHandler imap-file

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

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>
Note: The core directives ForceType and SetHandler are used to associate all the files in a given container (<Location>, <Directory>, or <Files>) with a particular MIME-type or handler. These settings override any filename extension mappings defined in mod_mime.
Note: Because SetHandler overrides default handlers, normal behavior such as handling of URLs ending in a slash (/) as directories or index files is suppressed.

SetInputFilter

Module: core
Syntax: SetInputFilter filter [filter ...]
Default: none
Context: directory, .htaccess
Override: none
Origin: Apache
Example: SetInputFilter gzip

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 Link outside Information Center documentation for more information regarding filters.

SetOutputFilter

Module: core
Syntax: SetOuputFilter filter [filter ...]
Default: none
Context: directory, .htaccess
Override: none
Origin: Apache
Example: SetOutputFilter INCLUDES

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 Link outside Information Center documentation for more information regarding filters.

ThreadsPerChild

Module: core
Syntax: ThreadsPerChild number
Default: Global HTTP Server setting for maximum number of servers.
Context: server config
Override: none
Origin: Apache
Example: ThreadsPerChild 20

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.

TimeOut

Module: core
Syntax: TimeOut number
Default: TimeOut 300
Context: server config, virtual host
Override: none
Origin: Apache
Example: TimeOut 500

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 any individual block of output from a CGI script.
  4. In mod_proxy , the default timeout value if ProxyTimeout is not configured.

TraceEnable

Module: core
Syntax: TraceEnable on | off | extended
Default: TraceEnable on
Context: server config
Override: none
Origin: Apache
Example: TraceEnable on

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.

Finally, for testing and diagnostic purposes only, request bodies may be allowed using the non-compliant TraceEnable extended directive. The core (as an origin server) will restrict the request body to 64kb (plus 8kb 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 64kb.

Note: Despite claims to the contrary, enabling the TRACE method does not expose any security vulnerability in Apache HTTP server. The TRACE method is defined by the HTTP/1.1 specification and implementations are expected to support it.

UnDefine

Module: core
Syntax: UnDefine parameter-name
Default: none
Context: server config
Override: none
Origin: Apache
Example: UnDefine SSL

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.

UseCanonicalName

Module: core
Syntax: UseCanonicalName on | off | DNS
Default: UseCanonicalName on
Context: server config, virtual host, directory, Not in Limit
Override: Options
Origin: Apache
Example: UseCanonicalName off

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.
Important: If CGIs make assumptions about the values of SERVER_NAME they may be broken by this option. The client is essentially free to give whatever value they want as a hostname. But if the CGI is only using SERVER_NAME to construct self-referential URLs then it should be fine.

See also ServerName.

UseShutdown

Module: core
Syntax: UseShutdown On | Off
Default: UseShutdown Off
Context: server config
Override: none
Origin: Apache
Example: UseShutdown On

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

<VirtualHost>

Module: core
Syntax: <VirtualHost addr[:port] [addr[:port]]...> ... </VirtualHost>
Default: none
Context: server config, Not in Limit
Override: none
Origin: Apache
Example 1: Using an IPv4 address:
<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> 
Example 2: Using an IPv6 address:
<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 only in combination with NameVirtualHost * 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.

Note: The use of <VirtualHost> does not affect what addresses the server listens on. You may need to ensure that HTTP Server is listening on the correct addresses using the Listen directive.
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.
Note: Any IP address that matches a NameVirtualHost directive will use neither the "main" server config nor the _default_ virtual host. See the name-based virtual hosting documentation for further details.
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_.

Name-based vs IP-based Virtual Hosts

IP-based virtual hosts use the IP address of the connection to determine the correct virtual host to serve. Therefore you need to have a separate IP address for each host. With name-based virtual hosting, the server relies on the client to report the hostname as part of the HTTP headers. Using this technique, many different hosts can share the same IP address. Name-based virtual hosting is usually simpler, since you need only configure your DNS server to map each hostname to the correct IP address and then configure the Apache HTTP Server to recognize the different hostnames. Name-based virtual hosting also eases the demand for scarce IP addresses. Therefore you should use name-based virtual hosting unless there is a specific reason to choose IP-based virtual hosting. Some reasons why you might consider using IP-based virtual hosting:
  • Some ancient clients are not compatible with name-based virtual hosting. For name-based virtual hosting to work, the client must send the HTTP Host header. This is required by HTTP/1.1, and is implemented by all modern HTTP/1.0 browsers as an extension. If you need to support obsolete clients and still use name-based virtual hosting, a possible technique is discussed at the end of this document.
  • Name-based virtual hosting cannot be used with SSL secure servers because of the nature of the SSL protocol.
  • Some operating systems and network equipment implement bandwidth management techniques that cannot differentiate between hosts unless they are on separate IP addresses.

Using Name-based Virtual Hosts

To use name-based virtual hosting, you must designate the IP address (and possibly port) on the server that will be accepting requests for the hosts. This is configured using the NameVirtualHost directive. In the normal case where any and all IP addresses on the server should be used, you can use * as the argument to NameVirtualHost. If you're planning to use multiple ports (e.g. running SSL) you should add a Port to the argument, such as *:80. Note that mentioning an IP address in a NameVirtualHost directive does not automatically make the server listen to that IP address. In addition, any IP address specified here must be associated with a network interface on the server.

The next step is to create a <VirtualHost> each different host that you would like to serve. The argument to the <VirtualHost> directive should be the same as the argument to the NameVirtualHost directive (ie, an IP address, or * for all addresses). Inside each <VirtualHost> block, you will need at minimum a ServerName directive to designate which host is served and a DocumentRoot directive to show where in the filesystem the content for that host lives.

Main host goes away

If you are adding virtual hosts to an existing web server, you must also create a <VirtualHost> block for the existing host. The ServerName and DocumentRoot included in this virtual host should be the same as the global ServerName and DocumentRoot. List this virtual host first in the configuration file so that it will act as the default host. For example, suppose that you are serving the domain www.domain.tld and you wish to add the virtual host www.otherdomain.tld, which points at the same IP address. Then you simply add the following to httpd.conf:
NameVirtualHost *:80
<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>
You can alternatively specify an explicit IP address in place of the * in both the NameVirtualHost and <VirtualHost> directives. For example, you might want to do this in order to run some name-based virtual hosts on one IP address, and either IP-based, or another set of name-based virtual hosts on another address.
Many servers want to be accessible by more than one name. This is possible with the ServerAlias directive, placed inside the <VirtualHost> section. For example in the first <VirtualHost> block above, the ServerAlias directive indicates that the listed names are other names which people can use to see that same web site:
ServerAlias domain.tld *.domain.tld 
Requests for all hosts in the domain.tld domain will be served by the www.domain.tld virtual host. The wildcard characters * and ? can be used to match names. Of course, you can't just make up names and place them in ServerName or ServerAlias. You must first have your DNS server properly configured to map those names to an IP address associated with your server. Finally, you can fine-tune the configuration of the virtual hosts by placing other directives inside the <VirtualHost> containers. Most directives can be placed in these containers and will then change the configuration only of the relevant virtual host. To find out if a particular directive is allowed, check the Context of the directive. Configuration directives set in the main server context (outside any <VirtualHost> container) will be used only if they are not overridden by the virtual host settings. Now when a request arrives, the server will first check if it is using an IP address that matches the NameVirtualHost. If it is, then it will look at each <VirtualHost> section with a matching IP address and try to find one where the ServerName or ServerAlias matches the requested hostname. If it finds one, then it uses the configuration for that server. If no matching virtual host is found, then the first listed virtual host that matches the IP address will be used.

As a consequence, the first listed virtual host is the default virtual host. The DocumentRoot from the main server will never be used when an IP address matches the NameVirtualHost directive. If you would like to have a special configuration for requests that do not match any particular virtual host, simply put that configuration in a <VirtualHost> container and list it first in the configuration file.