Chapter 6: Text-based configuration

The server configuration file is <ServerRoot>/conf/httpd.conf, a simple text file that Stronghold reads each time it starts. This chapter introduces you to this file and shows you how to:

use configuration directives
configure virtual hosts
Be sure to read this section, especially if you are upgrading from Stronghold 2.3 or earlier and the server already includes virtual hosts.
reconfigure an SSL/TLS-only server

You are running and SSL/TLS-only server if you entered port 0 as the regular (non-secure) port during installation.

Once you understand the configuration concepts discussed here, use Chapter 5 to find specific directives to customize httpd.conf

Each time you edit the configuration file, you must restart the server in order to apply your changes. See "Restarting Stronghold" on page 1-3 for instructions

	Stronghold's indexing and searching features require separate configuration, and chapter 1 discusses this.

Using Directives

Directives are configuration commands. Each directive controls a different aspect of Stronghold's behaviour, Including how it treats the objects on the site. Different directives take different kinds of values as arguments, such as

paths to files or directories

When the value of a directive is a path, the path is always relative to the root server

directory <ServerRoot> unless it begins with a slash (/).

values that set the properties of a server feature
regular expressions and wildcards

Since many of the objects on your server require special treatment, each object can have its own configuration within httpd.conf. An object's configuration describes deviations from the global configuration. This granularity gives Stronghold (and its Apache cousin) its enormous flexibility. Infinitely many different configurations are possible.

Figure 6-1: Configuration granularity

Containers

Directives can be applied in different `contexts' where a directive's context is the scope in which it applies. The configuration file uses containers to constrain directives to a context such as a particular virtual host, a URL, an HTTP access method, a directory, or a file. For example:

<Directory /logos/jpegs> ... </Directory>

This example shows an opening container tag, which specifies an object on the server, followed by a closing container tag that begins with a slash (/). The directives that apply only to the /logos/jpegs directory go between the opening and closing container tags.

When entering configuration directives, use the following guidelines:

A directive that is not enclosed in a container applies globally.
The global configuration is usually the main server host on the default port (80).
A directive within a per-directory configuration (htaccess) file applies only to the directory that contains the file and to its sub directories.
A directive that appears within a container applies to the object specified in the opening container tag.

These are the available containers:

<VirtualHost IP:port>

This container specifies a virtual host distinguished by an IP address and a port number. Always close a virtual host container with </VirtualHost>. For more detailed information about using this container, see "Configuring Virtual Hosts" on page 6-10.

<Directory directory>

This container specifies a directory on your server, and it also applies to all its subdirectories, except for any subdirectories that have their own <Directory> sections. <Directory> is either the full path to a directory or a wildcard string. Always close a directory container with </Directory>.

This container is also used to configure proxy service, as described in "Configuring the Proxy Server" on page 4-4.

<DirectoryMatch regex>

This container is the same as the <Directory> container, except that it uses a regular expression instead of a literal directory path. For example,

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

matches directories in /www/ that consist of three numbers.

<Location URI>

This container specifies a URI that does not necessarily map to a directory on the server. URI should, except for proxy requests, be of the form /path/, and should not include the http://<hostname> portion. It doesn't necessarily have to protect a directory (it can be an individual file, or a number of files), and can include wildcards. Always close this container with </Location>.

<LocationMatch regex>

This container is the same as the <Location> container, except that it uses a regular expression instead of a URI. For example,

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

matches URIs that contained the substring "/extra/data" or "/special/data."

<Limit method>

This container specifies an HTTP access method, such as GET, PUT, or POST, as the condition under which the enclosed directives apply. Always close this container with
</Limit>.

<Files filename>

This container specifies a filename or the end of a filename and can take wildcards. The directives it contains apply to the named file or to any file ending in the filename. Always close this container with </Files>.

	Wildcards in <Files> containers do not match slash (/)

<FilesMatch regex>

This container is the same as the <Files> container, except that it uses a regular expression instead of a filename. For example,

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

matches common Internet graphics formats.

<IfModule module>

This container specifies a module which may be active or inactive, depending on whether it is activated by the AddModule directive. The directives in this container apply only if the module is active. If the value is module, the directives apply only if the module is inactive. Always close this container with </IfModule>.

Dynamic module linking is discussed in greater detail in "Dynamic Module Linking" on page 8-8.

<IfDefine parameter>

This container encloses directives that apply if the specified parameter was defined at the command line (or in the start-server script) on startup. The parameter is defined using the -D command-line flag and is entirely arbitrary. For example, several different servers can run with different parameters that each enable a different section of the same configuration file. This is equivalent to running several different servers with several different configuration files. Always close this container with </IfDefine>.

<Perl>

This container encloses Perl code used to configure the server. It is ignored unless mod_perl is compiled in and Perl server configuration is enabled.

Each of these can be nested inside the others, with the following exceptions:

<VirtualHost> should not be nested inside another container.
No container should be nested inside a <Files> or <FilesMatch> container except <Limit> because files are the smallest server objects.
No container should be nested inside a <Limit> container. <Limit> is the container with the narrowest scope.
<Directory>, <DirectoryMatch>, <Location>, and <LocationMatch> containers should not be nested inside each other.

Directives that appear outside all containers apply globally. The server reads them first. Directives inside containers are processed in the following order:

<Directory> containers without regular expressions and .htaccess files.
The .htaccess files override <Directory> containers. Multiple <Directory> containers without regular expressions are processed from the shortest directory path to the longest. For example, <Directory /animals> is processed before <Directory/ animals/hyrax>, even if it appears later in the configuration file.

<DirectoryMatch> and <Directory> containers with regular expressions

<Files> and <FilesMatch> containers

<Location> and <LocationMatch> containers

<VirtualHost> containers and the containers nested inside them

The processing order above applies to containers inside <VirtualHost> containers.

This processing order allows more specific containers to override the directives inside more general containers. Except for <Directory> containers without regular expressions, containers of each type are processed in the order in which they appear. Configuration elements inserted with the Include directive are treated as if they are located at the point of inclusion.

Wildcards

Wildcards are a simple method of denoting variable values. Containers can take wildcards in place of ordinary <hostname>s, paths, and so on. Some directives can also take wildcards as values.

There are two wildcards:

Wildcard	Description
*	Matches zero or more of any string
?	Matches exactly one of any string, that is, the first match found

For example, imagine that Stronghold Web Server 3.0 Administration Guide is an internal server private proxy on your organization's local area network (LAN). Each host on the LAN has a <hostname> that ends with your organization's basic domain name, such as c2.net. The asterisk wildcard can be used to restrict access so that your server only responds to hosts on the LAN:

AddAlt "JPEG banner" banner*.jpeg

In this example, any filename that begins with "banner" and has the .jpeg filename extension is given the "JPEG banner" description in directory index listings. Any number of filenames qualify, such as banner1.jpeg, banner_advertisement.jpeg, and so on.

Regular Expressions

Regular expressions are patterns that describe a set of strings. They consist of any number of ordinary characters and metacharacters. When combined as a regular expression, these can match zero or more real strings. Stronghold supports POSIX Extended Regular Expressions (EREs).

Some directives can take regular expressions as values. Containers can also take regular expressions as long as the beginning of the expression is denoted with a tilde (~). For example:

<Directory ~ "^/www/.*/[a-z]{3}"> ... </Directory>

Stronghold also includes several "match" containers designed specifically for regular expressions. The tilde character is not required in these containers. Where regular expressions are required, use the match containers. For example, the <DirectoryMatch> container can accomplish the same task as the <Directory> container above:

<DirectoryMatch "^/www/.*/[a-z]{3}"> ... </DirectoryMatch>

Metacharacters modify regular characters within a regular expression:

Metacharacter	Description
(`characters`)	all of `characters`
[`characters`]	any of `characters`
[^`characters`]	none of `characters`
[`a`-`z`]	all characters from `a` to `z`.
.	wildcard; matches any single character
?	0 or 1 of the preceding character
*	0 or more of the preceding character
+	1 or more of the preceding character
{`n`}	exactly `n` of the preceding character
{`n`,}	`n` or more of the preceding character
{,`n`}	no more than `n` of the preceding character
{`n`,`m`}	at least `n` but no more than `m` of the preceding character
\ `x`	literal character; the backslash (\) escapes special characters
^	start of line
$	end of line

Certain classes of characters are predefined and can be used instead of expressions:

Character Class	Description
[:alnum:]	any alphabetic or numeric character
[:alpha:]	any alphabetic character
[:blank:]	any space or tab
[:cntrl:]	any control character
[:digit:]	any digit
[:graph:]	any non-blank character (not spaces, tabs, or control characters)
[:lower:]	any lower case, alphabetic character
[:print:]	any non-blank character, including spaces
[:punct:]	any punctuation character
[:space:]	any whitespace character such as newline, line break, or paragraph break
[:upper:]	any uppercase character
[:xdigit:]	any hexadecimal character, 0--9, a--f, and a-f

Finally, regular expressions can be combined. Expression A and expression B, can be combined in two ways:

AB matches "AB"
A|B matches "A" or "B"

Configuring an Upgraded Server

When you upgrade an Apache or an older Stronghold server to Stronghold Web Server 3.0, your original configuration files remain intact. When you upgrade from Stronghold 2.1 or earlier, you must "unify" your server by combining the contents of its httpsd.conf file with the httpd.conf file. In order to implement SSL and other Stronghold modules, you must edit httpd.conf before you can run your new server. This section provides instructions for configuring a Stronghold server that has been upgraded from Apache or an early version of Stronghold.

Configuring Virtual Hosts

In addition to the "main" host, the server can support a number of virtual hosts. To function properly, virtual hosts must meet some basic configuration requirements. In addition, the server must be able to distinguish between virtual hosts. Virtual hosts can be distinguished in three different ways:

by IP number (recommended)
This scheme requires that each virtual host have a different IP number. Each IP number is associated with a different <hostname> in the Domain Naming System (DNS).
by port number
This scheme requires that each SSL/TLS host and each regular (non-secure) virtual host operate on a different port. It also requires that users enter a special port number to reach the correct host. All the <hostname>s can be associated with the same IP number in DNS.
by <hostname>

This scheme requires that

each virtual host have a different <hostname> and
every request include a Host header that gives the <hostname> of the requested virtual host.

	Name-based virtual hosts do not work with SSL/TLS because SSL and TLS encrypt all HTTP headers--including the Host header required to determine which name-based virtual host is being addressed.

Since version 2.4, Stronghold uses a new configuration scheme for name-based virtual hosts. Be sure to familiarize yourself with it if the site contains name-based virtual hosts.

Configuration Requirements

Each SSL/TLS virtual host must have

its own key pair and matching certificate and
a <VirtualHost> container that specifies an IP number and a port number:

<VirtualHost 205.254.204.194:80> ... </VirtualHost>

Each virtual host should be designated by its IP address, even if it is not an IP-based virtual host, to avoid time-consuming DNS lookups. Because regular hosts and SSL/TLS hosts use different ports and require separate configurations, each virtual host container tag must also specify a port number, even if it does not pertain to a port-based virtual host.

	If stronghold is running as an SSL/TLS-only server, it is not necessary to specify a port because all hosts listen on the globally-configured SSL/TLS port

Each <VirtualHost> container should include these directives:

Directive	Description
`ServerName`	The `<hostname>` of this host; it must be a fully-qualified domain name that resolves to the IP number specified in the opening container tag
`ServerAdmin`	The email address of this host's administrator
`DocumentRoot`	The root document directory for this host, necessary to resolve URLs; requests are fulfilled from this directory except where configured otherwise
`CustomLog`	A consolidated `access/error` log for this host. Combining these in a single custom log saves file descriptors on sites that support many hosts. Optionally to give each virtual host its own `TransferLog`, `ErrorLog`, and `SSLLogFile` if file descriptors are not an obstacle.

For example:

<VirtualHost 205.254.204.194:80> ServerName www.example.com ServerAdmin webmaster@example.com DocumentRoot /www/htdocs/example CustomLog logs/example.log "%h %l %u %t \"%r\" %s %b" </VirtualHost>

Each SSL/TLS container must include the directives above (except CustomLog), plus these SSL/TLS-specific directives:

Directive	Description
`SSLFlag` `on`	Enables SSL/TLS functionality for this virtual host
`SSLCertificateKeyFile`	The path to the key file for this host relative to `<ServerRoot>/ssl/,` usually private/`<hostname>`.key
`SSLCertificateFile`	The path to the certificate file for this host relative to `<ServerRoot>/ssl/`, usually certs/`<hostname>`.cert
`SSLLogFile`	The SSL/TLS log file for this host relative to `<ServerRoot>`, such as `logs/ssl/<hostname>_cipher_log`

For example:

<VirtualHost www.example.com:443> ServerName www.example.com DocumentRoot /usr/local/www/htdocs/example ServerAdmin webmaster@example.com SSLFlag on SSLCertificateKeyFile private/example.key SSLCertificateFile certs/example.cert SSLLogFile logs/ssl/example_cipher_log </VirtualHost>

Note that the opening container tag must specify the SSL/TLS port number, usually port 443. Port-based virtual hosts each use a different port number.

When configuring a virtual host as a mirror proxy intended to perform server-side authentication with a proxy client certificate a SSLProxyMachineCertPath or SSLProxyMachineCertFile directive is required. For more information, see "Proxy Client Certificates" on page 2-19.

IP-Based Virtual Hosts

When multiple IP addresses are assigned to the server machine, each virtual host can be distinguished with its own IP address. This is the recommended virtual host configuration because it

does not rely on browsers for support,
does not require that users enter special port numbers, and
supports SSL and TLS

The means for configuring multiple IP addresses at the system level vary from platform to platform, and the operating system documentation can provide assistance. Once multiple IP support is established at the system level, containers for each virtual host can be entered in the configuration file. When entering a virtual host container, specify an IP address and a port number, like this:

<VirtualHost 140.174.185.14:80>

Stronghold simply matches the IP address of each incoming request with an IP address in one of the virtual host containers. When responding, Stronghold uses the <hostname> specified by that container's ServerName directive.

Port-Based Virtual Hosts

Port-based virtual hosts may share a single IP address, but each is distinguished by two unique port numbers: one for ordinary transactions, and one for SSL/TLS-secured transactions. For example:

<VirtualHost 127.65.42.1:880> ServerAdmin webmaster@example.com DocumentRoot /usr/local/www/htdocs/example ServerName www.example.com </VirtualHost> <VirtualHost 127.65.42.1:4430> ServerAdmin webmaster@example.com DocumentRoot /usr/local/www/htdocs/example ServerName www.example.com SSLFlag on SSLCertificateKeyFile private/www.example.com.key SSLCertificateFile certs/www.example.com.cert </VirtualHost>

In this example, no other virtual hosts on this server can use port 880 or 4430. Each port-based virtual host must be assigned ports for SSL/TLS and regular (non-secure) transactions that are not used by any other virtual hosts on the server.

Under this scheme, every link in every file belonging to a host must take one of two forms:

a path only, such as

<a href=/olympics/luge.html>

a URL with a port number, such as

<a href=http://www.host.net:8065/olympics/luge.html>

Inevitably, users enter URLs without port numbers. When this happens under a port-based virtual host scheme, port 80 receives the request. When a user specifies HTTPS without a port number, port 443 receives the request. Be sure that one of the hosts listens on ports 80 and 443 and that its main page contains links to the virtual host ports.

	If port-based virtual hosts are configured, name-based virtual hosts cannot be present in the same server configuration.

Name-Based Virtual Hosts

Name-based virtual host support depends largely on the compliance of browsers with the HTTP/1.1 protocol, which requires the Host header in all client requests. The Host header allows the server to determine which host is being requested. It also allows multiple virtual hosts to share a single IP address. The latest browsers, including Netscape Navigator and Microsoft Internet Explorer, support HTTP/1.1. Many older browsers do not.

Name-based virtual hosts do not support SSL/TLS. Under SSL and TLS, all HTTP headers are encrypted, including the Host header required to determine which host is being requested. Without the Host header, Stronghold cannot determine which virtual host configuration to apply. Without the correct configuration, Stronghold also cannot determine which site certificate to send or which private key to use when decrypting SSL/TLS requests.

The Domain Naming System (DNS) must be configured to point all <hostname>s to the server IP address. The means for doing this vary from platform to platform, and the operating system documentation can provide assistance.

For each IP address that is used for name-based virtual hosts, the server's global configuration must contain a NameVirtualHost directive. The IP address specified by NameVirtualHost is used only for name-based virtual hosts; the main server and other types of virtual hosts never respond to that IP number. This means that a separate IP address must be reserved for use with name-based virtual hosts. If you only have one IP address, all hosts (including the main host) must be name-based virtual hosts in order to work.

For example:

<ServerRoot> /www ServerName www.main.net DocumentRoot /www/main/htdocs NameVirtualHost 205.254.204.194 <VirtualHost 205.254.204.194:80> ServerName www.kayak.com DocumentRoot /www/kayak/htdocs ... </VirtualHost> <VirtualHost 205.254.204.194:80> ServerName www.anorak.com DocumentRoot /www/anorak/htdocs ... </VirtualHost>

When it receives a request, Stronghold reads the Host header to get the <hostname>. If the host is www.kayak.com, the server looks in /www/kayak/htdocs for the requested document. If it is www.anorak.com, Stronghold uses the /www/anorak/htdocs directory instead.

Now imagine that 205.254.204.194 is the only IP address available. In that case, the globally configured server never responds to a request, because that IP address is reserved for name-based virtual hosts. To solve this problem, create a name-based virtual host configuration to represent the main server. For example:

<ServerRoot> /www ServerName www.main.net DocumentRoot /www/main/htdocs NameVirtualHost 205.254.204.194 <VirtualHost 205.254.204.194:80> ServerName www.main.net DocumentRoot /www/main/htdocs ... </VirtualHost> <VirtualHost 205.254.204.194:80> ServerName www.kayak.com DocumentRoot /www/kayak/htdocs ... </VirtualHost> <VirtualHost 205.254.204.194:80> ServerName www.anorak.com DocumentRoot /www/anorak/htdocs ... </VirtualHost>

In the absence of a Host header, any request for a name-based virtual host is still directed to the main server's pages. You must, therefore, provide a link from the main server's pages to the name-based virtual hosts. Furthermore, any links in the virtual host's pages should be relative in order to work with older browsers. This is a cumbersome approach and may become less important as browsers evolve.

Certificates and Key Pairs for Virtual Hosts

Because Microsoft Internet Explorer and Netscape Navigator check the URL against the <hostname> on any server certificate, each SSL/TLS virtual host requires a separate certificate. The genkey utility generates a key pair, request a certificate, and install the certificate for each SSL/TLS virtual host. The key pair is saved at
<ServerRoot>/ssl/private/<hostname>.key. Along with the key pair, genkey generates a certificate signing request (CSR) to send to a Certification Authority (CA), typically Verisign or Thawte. For more detailed information about certificates, certification authorities, Versign, or Thawte, see Chapter 2, "Authentication and Encryption.".

For complete genkey instructions, see "To generate a key pair and request a certificate" on page 2-28.

Reconfiguring an SSL/TLS-Only Server

When you install Stronghold Web Server 3.0, you have the option to enter "0" when prompted for a port to use for unsecured transactions. This disables normal, unsecured transactions. Of you later decide to introduce non-secure transactions on your server, follow these instructions

To convert an secure-only server to a dual secure/nonsecure server

open httpd.conf in a text editor
locate the Configuration Manager section, which starts like this:

### Configuration manager virtual host###

Insert the following virtual host configuration above the Configuration manager section and below all other virtual hosts:
Listen 80 <VirtualHost_defautl_:80> Servername <hostname> ServerAdminenail-address SSLFlag off DocumentRoot /full/path/to/document/root TransferLog logs/error/access_log ErrorLog logs/error_log </VirtualHost>

This virtual host responds to HTTP requests for the main host.
run the restart-server script to restart the server.
Stronghold rereads the httpd.conf file and implements these changes.
If your also add nonsecure counterparts for your existing, SSL/TLS-only virtual hosts, you must first make sure those hosts use and IP/port number configuration. For example:

<VirtualHost 209.60.53.41:443>

For each IP- or port-based SSL/TLS virtual host, add a nonsecure counterpart. Insert any new, non-SSL virtual hosts above the <Virtualhost_default_:80> container. Each must also use and IP address and a port number. For example, the nonsecure counterpart to the example above looks like this:

<VirtualHost 209.60.53.41:80> ServerName <hostname> ServerAdmin login@<hostname> SSLFlag off DocumentRoot /full/path/to/document/root TransferLog logs/<hostname>_access_log ErrorLog logs/<hostname>_error_log </VirtualHost>

Note that single, HTTP-only virtual hosts with no counterparts can be name-based.