Fundamental directive, context, and server area concepts on HTTP Server

The IBM® HTTP Server for i is configured using directives. A directive is used to define an attribute of the HTTP Server or how the HTTP Server operates. For example, the Listen directive defines what port the HTTP Server should wait on to handle incoming requests.

HTTP Server directives are extensive, functional, and built around the concept of context.

Directive categories of HTTP Server

The HTTP Server directives may be categorized into two main groups. These are Assignment directives and Container directives.

Assignment directives: Used to configure the function or characteristics of the HTTP Server. For example, the Listen directive assigns the port the HTTP Server should use to handle incoming requests.

Container directives: Used to group directives together within the HTTP Server. The container directives group one or more assignment directives which are used to control the function intended specifically within the context of the container. For example, the <Directory> directive is used to enclose a group of assignment directives that only apply to the directory and subdirectory context.; When dealing with container directives, individual assignment directives may not be valid within one or more container directives due to improper context. See Directives for HTTP Server for more information on the specific context a directive may or may not be used.

HTTP Server directive contexts

Understanding the context concept is necessary to increase the productivity and usefulness of your HTTP Server. The IBM Web Administration for i interface assists in managing context areas of your server. By selecting a different area of the server area, you are changing the context you are managing.

These types of directive contexts are supported:

server config: Also called "Server Area", "Global Level" or "Global Context". The attributes set by directives in the server config context can and most likely will be inherited by the container directives and assignment directives used in the configuration.

directory: Also called "Container Context", the directory context should not be confused with <Directory> containers. If the directive supports this context, the directive can be used in most containers (<Directory>, <File>, <Proxy>, and <Location> for example). This context support does not apply to virtual hosts. There are limited exceptions where directives are not supported in all of the containers associated with this context. See Directives for HTTP Server for specific directive exceptions.

virtual host: The virtual host context refers to directives that are allowed to be configured, or assigned, in the <Virtual Host> container directive.

.htaccess: Also called ".htaccess files", the .htaccess context refers to directives supported in per-directory configuration files. Per-directory configuration files are read by the server from the physical directory where they reside. The directives within this file are applied to any objects that are to be served from the directory where the file exists, and may also be carried forward to sub-directories. Note that the use of .htaccess files is not recommended due to the additional overhead incurred by the server.

HTTP Server container types

The directives used to configure HTTP Server containers are encased in greater than (>) and lesser than (<) brackets. For example, <Directory> is a container directive. Each container is comprised of an opening directive, such as <Directory>, and closed with the same context directive prefixed with a slash (/). For example, </Directory>.

There are six different types of container directives. Five of the six container directives listed below have variants which results in a total of eleven different container directives (shown below with the opening and closing tags).

Directory and DirectoryMatch: <Directory directory>...</Directory>; <DirectoryMatch regex>...</DirectoryMatch>

Files and FilesMatch: <Files filename>...</Files>; <FilesMatch regex>...</FilesMatch>

Location and LocationMatch: <Location URL>...</Location>; <LocationMatch regex>...</LocationMatch>

Proxy and ProxyMatch: <Proxy criteria>...</Proxy>; <ProxyMatch regex>...</ProxyMatch>

VirtualHost: <VirtualHost addr[:port] >...</VirtualHost>

Limit and LimitExcept: <Limit method method>...</Limit>; <LimitExcept method method>...</LimitExcept>

Version: <IfVersion> [[!]operator] version> ... </IfVersion>

If , Else and ElseIf

Require

Note: Not all directives enclosed by brackets (<>) are container directives. For example, directives <IfModule> ,<IfDefine> and <Macro> are used to define parts of the HTTP Server configuration that are conditional and are ignored once the server has started; however, they are not directive containers.

Context and server area relationship

The following table shows server area and context relationship.

Server area	Context
Global configuration	server config
Directory container	directory (<Directory>; or <DirectoryMatch>;)
File container	directory (<File>; or <FileMatch>;)
Location container	directory (<Location>; or <LocationMatch>)
Proxy container	directory (<Proxy>; or <ProxyMatch>;)
Virtual host container	virtual host (<VirtualHost>)
Limit except container	<Limit> or <LimitExcept> Note: The context depends on the location of the <Limit> and <LimitExcept> container. It will inherit the context of the area it is in. For example, if the <Limit> and <LimitExcept) are within a directory container, the <Limit> or <LimitExcept> will be assigned the same values as the directory container.
Version containe	<IfVersion>

See Directives for HTTP Server for more information on all the supported HTTP Server directives and the context in which the directives may be used.

Directives within containers

The container directives <Directory>, <Location> and <Files> can contain directives which only apply to specified directories, URLs or files respectively. This also includes .htaccess files that can be used inside a directory container to apply directives to that directory.

Files that are included in the configuration file are processed by the HTTP Server at start time. Changes to files that are included in the configuration file (such as include files and group files, but not .htaccess files) do not take effect until the server is restarted.

Everything that is syntactically allowed in <Directory> is also allowed in <Location> (except a sub-<Files> section). Semantically however some things, and the most notable are AllowOverride and the two options FollowSymLinks and SymLinksIfOwnerMatch, make no sense in <Location>, <LocationMatch> or <DirectoryMatch>. The same for <Files> -- while syntactically correct, they are semantically incorrect.

Directive inheritance

Directives inherit first from the top most (or "parent") directive container, then from more specific directive containers within.

In the following example, Directory A is the parent container to Directory B. Directive b first inherits its parameters from Directory A and directive a by default. If the parameters for directive b are defined, then directive b does not inherit, but uses its own parameter settings. Note that directive a does not inherit any parameter settings from directive b, since directive a is the parent to directive b. Inheritance only goes from parent to child.

<Directory A>
 directive a
 <Directory B>
   directive b
 </Directory>
</Directory>

Note: Best practice for security of your HTTP Server is to put all security directives into each container to ensure that each directory or file is secured.

How the directives are merged

The order of merging is:

<Directory> (except regular expressions) and .htaccess done simultaneously (with .htaccess overriding <Directory>)
<DirectoryMatch>, and <Directory> with regular expressions
<Files> and <FilesMatch> done simultaneously
<Location> and <LocationMatch> done simultaneously

Apart from <Directory>, each directive group (directives within container directives) is processed in the order that they appear in the configuration files. <Directory> (directive group 1 above) is processed in the order shortest directory component to longest. If multiple <Directory> sections apply to the same directory they are processed in the configuration file order. Configurations included through the Include directive will be treated as if they were inside the including file at the location of the Include directive.

Container directives inside a <VirtualHost> container directive are applied after the corresponding directives outside of the virtual host definition. This allows virtual hosts to override the main server configuration.

Using container directives

General guidelines:

If you are attempting to match objects at the file system level then you must use the <Directory> and <Files> container directives.
If you are attempting to match objects at the URL level then you must use the <Location> container directive.

Notable exception:

Proxy control is done via <Proxy> containers. Directives which are valid in a <Directory> container are also valid in a <Proxy> container. A <Proxy> container is very similar to a <Location> container, since it deals with virtual paths and locations rather than with physical paths. The directives in <Proxy> containers are processed after the directives in <Location> containers are processed, but before directives in <Directory> containers are processed. The directives in <Proxy> containers are also inherited into more specific <Proxy> containers in the same way as the directives in a <Directory> container.

.htaccess parsing:

Modifying .htaccess parsing within a <Location> container directive has no affect. The .htaccess parsing has already occurred.

<Location> and symbolic links:

It is not possible to use Options FollowSymLinks or Options SymLinksIfOwnerMatch inside a <Location>, <LocationMatch> or <DirectoryMatch> container directives (the Options are simply ignored). Using the Options in question is only possible inside a <Directory> container directive (or a .htaccess file).

<Files> and Options:

Using an Options directive inside a <Files> container directive has no effect.

Note: A <Location>/<LocationMatch> sequence is performed just before the name translation phase (where Aliases and DocumentRoots are used to map URLs to filenames). The results of this sequence are removed after the translation has completed.