Block Directives (Apache: The Definitive Guide)

3.3. Block Directives

Apache has a number of block directives that limit the application of other directives within them to operations on particular virtual hosts, directories, or files. These are extremely important to the operation of a real web site because within these blocks -- particularly <VirtualHost> -- the webmaster can, in effect, set up a large number of individual servers run by a single invocation of Apache. This will make more sense when you get to Section 3.5, "Two Sites and Apache", further on in this chapter.

The syntax of the block directives is detailed next.

3.3.1. <VirtualHost>

<VirtualHost host[:port]>
...
</VirtualHost>
Server config

The <VirtualHost> directive within a Config file acts like a tag in HTML: it introduces a block of text containing directives referring to one host; when we're finished with it, we stop with </VirtualHost>. For example:

....
<VirtualHost www.butterthlies.com>
ServerAdmin sales@butterthlies.com
DocumentRoot /usr/www/site.virtual/htdocs/customers
ServerName www.butterthlies.com
ErrorLog /usr/www/site.virtual/name-based/logs/error_log
TransferLog /usr/www/site.virtual/name-based/logs/access_log
</VirtualHost>
...

<VirtualHost> also specifies which IP address we're hosting and, optionally, the port. If port is not specified, the default port is used, which is either the standard HTTP port, 80, or the port specified in a Port directive. host can also be _default_ , in which case it matches anything no other <VirtualHost> section matches.

In a real system, this address would be the hostname of our server. The <VirtualHost> directive has three analogues that also limit the application of other directives:

<Directory>
<Files>
<Location>

This list shows the analogues in ascending order of authority, so that <Directory> is overruled by <Files>, and <Files> by <Location>. Files can be nested within <Directory> blocks. Execution proceeds in groups; in the following order:

<Directory> (without regular expressions) and .htaccess are executed simultaneously.[25] .htaccess overrides <Directory>.

[25]That is, they are processed together for each directory in the path.
<DirectoryMatch> and <Directory> (with regular expressions).
<Files> and <FilesMatch> are executed simultaneously.
<Location> and <LocationMatch> are executed simultaneously.

Group 1 is processed in the order of shortest directory to longest.[26] The other groups are processed in the order in which they appear in the Config file. Sections inside <VirtualHost> blocks are applied after corresponding sections outside.

[26]Shortest meaning "with the fewest components" rather than "with the fewest characters."

3.3.2. <Directory> and <DirectoryMatch>

<Directory dir  >
...
</Directory>

The <Directory> directive allows you to apply other directives to a directory or a group of directories. It is important to understand that dir refers to absolute directories, so that <Directory /> operates on the whole filesystem, not the DocumentRoot and below. dir can include wildcards -- that is, "?" to match a single character, " * " to match a sequence, and "[ ]" to enclose a range of characters. For instance, [a-d] means "any one of a, b, c, d." If the character "~" appears in front of dir, the name can consist of complete regular expressions.[27]

[27]See Mastering Regular Expressions, by Jeffrey E.F. Friedl (O'Reilly & Associates).

<DirectoryMatch> has the same effect as <Directory ~ >. That is, it expects a regular expression. So, for instance, either:

<Directory ~ /[a-d].*>

or:

<DirectoryMatch /[a-d].*>

means "any directory name that starts with a, b, c, or d."

3.3.3. < Files> and < FilesMatch>

<Files file>
...
</Files>

The <Files> directive limits the application of the directives in the block to that file, which should be a pathname relative to the DocumentRoot. It can include wildcards or full regular expressions preceded by "~". <FilesMatch> can be followed by a regular expression without "~". So, for instance, you could match common graphics extensions with:

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

Or, if you wanted our catalogs treated in some special way:

<FilesMatch catalog.*>

Unlike <Directory> and <Location>, <Files> can be used in a .htaccess file.

3.3.4. < Location> and < LocationMatch>

<Location URL>
...
</Location>

The <Location> directive limits the application of the directives within the block to those URLs specified, which can include wildcards and regular expressions preceded by "~". In line with regular expression processing in Apache v1.3, "*" and "?" no longer match to "/". <LocationMatch> is followed by a regular expression without the "~".

Most things that are allowed in a <Directory> block are allowed in <Location>, but although AllowOverride will not cause an error in a <Location> block, it makes no sense there.

3.3.5. < IfDefine>

<IfDefine name>
...
</IfDefine>

The <IfDefine> directive enables a block, provided the flag -Dname is used when Apache starts up. This makes it possible to have multiple configurations within a single Config file. This is mostly useful for testing and distribution purposes rather than for dedicated sites.

3.3.6. < IfModule>

<IfModule [!]module-name>
...
</IfModule>

The <IfModule> directive enables a block, provided the named module was compiled or dynamically loaded into Apache. If the "!" prefix is used, the block is enabled if the named module was not compiled or loaded. <IfModule> blocks can be nested. The module-name should be the name of the module's source file, e.g. mod_log_config.c.