The server configuration file is 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:
Be sure to read this section, especially if you are upgrading from Stronghold 2.3 or earlier and the server already includes virtual hosts.
You are running an SSL/TLS-only server if you entered port 0 as the regular (non-secure) port when you installed Stronghold on a cross-platform system.
Once you understand the configuration concepts discussed here, refer to the Apache Desktop Reference to find specific directives to customize the httpd.conf file.
Each time you edit the configuration file, you must reload the server in order to apply your changes. See Reloading Stronghold for details.
The configuration files for Stronghold for Red Hat Linux Advanced Server are in various locations:
The /usr/share/ssl directory also contains CA, a directory that contains all you need to be a CA. This is useful if you plan to use client certificates to authenticate users on your site.
All Stronghold configuration files are in the ServerRoot/conf/ directory.
The httpd.conf file, Stronghold’s main configuration file, references:
For detailed information about Configuration, see the Apache Desktop Reference by opening a browser to http://your.server/stronghold/ and clicking on Apache manual on the side bar.
For detailed information about php4.conf, open a browser to http://your.server/stronghold/ and click on PHP on the side bar.
The ServerRoot/conf/ssl/ directory contains the configuration files for OpenSSL:
The ServerRoot/conf/tomcat/ directory contains the configuration for Tomcat Java Servlet Engine (if it is installed). For configuration information, open a browser to http://your.server/stronghold/ and click on Tomcat documentation on the side bar.
Directives are configuration commands. Each directive controls a different aspect of Stronghold’s behavior, including how it treats the objects on the site. Different directives take different kinds of values as arguments, such as:
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 (/).
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 its enormous flexibility.
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:
These are the available containers:
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.
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.
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.
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 does not 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>.
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."
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>.
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 (/).
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.
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".
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 commandline 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>.
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:
Directives that appear outside all containers apply globally. The server reads them first. Directives inside containers are processed in the following order:
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 are a simple method of denoting variable values. Containers can take wildcards in place of ordinary hostnames, 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 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 redhat.com. The asterisk wildcard can be used to restrict access so that your server responds only 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 the directory index listings. Any number of filenames qualify, such as banner1.jpeg, banner_advertisement.jpeg, and so on.
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 |
Regular expressions can be combined. Expression A and expression B can be combined in two ways:
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:
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).
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 hostnames can be associated with the same IP number in DNS.
This scheme requires that:
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.
Each SSL/TLS virtual host must have:
<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 and ErrorLog 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 | |
|---|---|---|
| SSLEngine on | Enables SSL/TLS functionality for this virtual host. This directive was formerly SSLFlag. | |
| SSLCertificateKeyFile | The path to the key file for this host relative to ServerRoot/conf/ssl/, usually private/hostname.key | |
| SSLCertificateFile | The path to the certificate file for this host relative to ServerRoot/conf/ssl/, usually certs/hostname.cert | |
| SSLLog | The SSL/TLS log file for this host relative to ServerRoot/, such as logs/ssl/hostname_ssl_engine_log. This directive used to be SSLLogFile. |
For example:
<VirtualHost www.example.com:443> ServerName www.example.com DocumentRoot /usr/local/www/htdocs/example ServerAdmin webmaster@example.com SSLEngine on SSLCertificateKeyFile private/example.key SSLCertificateFile certs/example.cert SSLLog 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 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:
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 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 SSLEngine 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 href=/olympics/luge.html>
<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 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 enables 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 hostnames 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 have only 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.
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, requests a certificate, and installs a self-signed temporary certificate for each SSL/TLS virtual host. The key pair is saved at ServerRoot/conf/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, GeoTrust, or Thawte. For more detailed information about certificates, certification authorities, Versign, GeoTrust, or Thawte, see Authentication and Encryption.
When you install Stronghold Web Server 4.0, you have the option to enter "0" when prompted for a port to use for unsecured transactions. This disables normal, unsecured transactions. If you later decide to introduce non-secure transactions on your server, follow these instructions.
To convert a secure-only server to a dual secure/nonsecure server:
Listen 80 <VirtualHost_default_:80> ServernameServerAdminemail-address SSLEngine 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.
<VirtualHost 209.60.53.41:443>
<VirtualHost 209.60.53.41:80> ServerNameServerAdmin login@ SSLEngine off DocumentRoot /full/path/to/document/root TransferLog logs/ _access_log ErrorLog logs/ _error_log </VirtualHost>
Single, HTTP-only virtual hosts with no counterparts can be name-based.