The server configuration file is ServerRoot/conf/httpd.conf, a simple, easy-to-manage 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 an upgraded server
  
  

  An upgraded server is one that has been upgraded to Stronghold Web Server 2.1 from Apache or a previous version of Stronghold.

• configure virtual hosts
  
  

Once you understand the configuration concepts discussed here, you can use Chapter 3 to find the specific configuration directives you need to customize httpd.conf for your site.

Stronghold's indexing and searching features require separate configuration, and Chapter 12 shows you how to do this.

Directives are configuration commands. Each directive controls a different aspect of Stronghold's behavior, and the objects on your server inherit this behavior. 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 also require special treatment, each object can have its own configuration within httpd.conf, containing directives that describe deviations from the global configuration. This granularity gives Stronghold (and its Apache cousin) its enormous flexibility. Infinitely many different configurations are possible.

Every directive has a context. The context of a directive is the scope in which it can apply. A directive can appear in the context of global server configuration, per-directory configuration files (.htaccess files), or between HTML-like container tags that limit their scope. For example:

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

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

When entering configuration directives, the following guidelines are useful:

• A directive that is not enclosed in a container applies globally.
  
  
• A directive within a .htaccess file applies only to the directory that contains the file, and its subdirectories.
  
  
• A directive that appears within a container applies to the virtual host, directory, location, access method, or file specified by the opening container tag.
  
  

These are the available containers:

Container	Description
<VirtualHost hostname:port#>	Specifies a virtual host to which the directives following the opening container tag apply. Hostname can be a fully-qualified domain name or an IP number. Always close a virtual host container with </VirtualHost>.
<Directory directory>	Specifies a directory on your server, and also applies to its subdirectories unless a subdirectory has its own <Directory> section. Directory is either the full path to a directory, a wildcard string, or a regular expression. Always close a directory container with </Directory>.
<Location URI>	Specifies a URI that does not necessarily map to a directory on your server. URI should, except for proxy requests, be of the form /path/, and should not include the http://servername. It doesn't necessarily have to protect a directory (it can be an individual file, or a number of files), and can include wildcards or regular expressions. Always close a location container with </Location>.
<Limit method>	Specifies an HTTP access method, such as GET, PUT, or POST, as the condition under which the enclosed directives apply. Always close a limit directive container with </Limit>.
<Files filename>	Specifies one or more files and can take regular expressions. You can specify paths to specific files, or construct an expression that matches any number of files. Always close a file directive container with </Files>.
<IfModule module>	Specifies a module which may be active or inactive, depending on whether it is specified 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 an IfModule container with </IfModule>. Dynamic module linking is discussed in greater detail in "Dynamic Module Linking" on page 4-4.

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 <File> container except <Limit>. Files are the smallest server objects.
  
  
• No container should be nested inside a <Limit> container. The <Limit> container is the container with the narrowest scope.
  
  
• <Directory> and <Location> containers should not be nested inside each other.
  
  

More specific containers always override the directives contained in more general containers. For example, imagine that httpd.conf contains these nested containers and their directives:

<VirtualHost www.virtual.com:80>
DirectoryIndex index.html
<Location /private/>
DirectoryIndex main.html
</Location>
</VirtualHost>

Now imagine that Stronghold receives a request for http://www.virtual.com/docs/, or any directory other than /private/. It looks for /docs/index.html, and then returns the file or generates a directory index if index.html does not exist. However, if Stronghold receives a request for http://www.virtual.com/private, it looks for the main.html file instead.

Wildcards are a simple method of denoting a variable value. Containers can take wildcards in place of ordinary hostnames, directory 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 you are running Stronghold Web Server as an internal server 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. You can use the asterisk wildcard to restrict access so that your server only responds to hosts on your LAN:

order allow, deny
allow from *.c2.net
deny from all

In this example, all hostnames ending in "c2.net" are allowed to access the server. All other hostnames are denied access.

Regular expressions are patterns that describe a set of strings. They consist of a some special characters and any number of ordinary characters. When combined as a regular expression, these can match zero or more real strings that you want to pick out.

Stronghold supports POSIX Extended Regular Expressions (EREs). Containers can take regular expressions as long as the beginning of the expression is denoted with a tilde (~). Some directives can also take regular expressions as values. The directive listings in Chapter 3 indicate which directives can take regular expressions as values.

Regular expressions allow you to construct statements that match a set of objects with certain properties, even if the set itself changes. For directives whose values are lists of directories or files, the configuration could be cumbersome to maintain if the members of the lists change frequently, or if the exact name of each member cannot easily be determined.

Metacharacters modify single 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 slash (/) escapes special characters
^	Start of line
$	End of line

Classes of characters are predefined for regular expressions, and you can use them 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, i.e., not spaces, tabs, or control characters
[:lower:]	Any lowercase, alphabetic character
[:print:]	Any non-blank character, but includes 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. If you have expression A and expression B, you can combine them in two ways:

• AB matches "AB."
  
  
• A|B matches "A" or "B."
  
  

When you upgrade an Apache or an older Stronghold server to Stronghold Web Server 2.1, your original configuration files remain intact. In order to implement SSL and other Stronghold modules, you must edit httpd.conf before you can run your new server.

1. Open httpd.conf.
   
   
2. Copy the <VirtualHost> containers to another part of the same file.
   
   

   If necessary, insert section headings to distinguish between the two copies. The original set of <VirtualHost> sections is for directives pertaining to non-SSL transactions, and the second set is for directives pertaining to SSL transactions.

3. In each original <VirtualHost> section, append the port number for non-SSL transactions to the hostname or IP number:
   
   

   <VirtualHost 204.17.33.11:80>
   
   

4. In each copied <VirtualHost> section, append the port number for SSL transactions to the hostname or IP number:
   
   

   <VirtualHost 204.17.33.11:443>
   
   

   This marks the beginning of an SSL <VirtualHost> section.

5. Add the following directives to the main server configuration:
   
   

   Listen 443
   
   

6. Add these directives to each SSL <VirtualHost> section:
   
   

   SSLFlag on
   SSLCertificateKeyFile private/filename
   SSLCertificateFile certs/filename
   

   NOTE:

   If you upgraded from Stronghold 1.3, you can copy your existing SSL virtual host directives from httpsd.conf.

   
   
7. Add directives that pertain to modules that were installed with your Stronghold upgrade, if you wish to use them.
   
   

   The directive listings in Chapter 3 of the Administration Guide indicate which module each directive pertains to.

8. Add a startup script to the conf/ directory:
   
   

   #!/bin/sh
   SSLTOP=path
   export SSLTOP
   ServerRoot/httpsd -d ServerRoot -f conf/httpd.conf
   
   

   Be sure to specify an absolute path for ServerRoot.

9. Add a stop script to the conf/ directory:
   
   

   #!/bin/sh
   kill cat ServerRoot/logs/httpd.pid
   
   

10. Add a reload script to the conf/ directory:
    
    

    #!/bin/sh
    kill \Q-HUP cat ServerRoot/logs/httpd.pid\Q
    
    

11. Run the stop script to stop the old Apache server.
    
    
12. Run the start script to start the new, SSL-enabled Stronghold server.
    
    

There are three ways to set up virtual host support:

• port-based virtual hosts
  
  

  This virtual host configuration is the only type that works with SSL.

• IP-based virtual hosts
  
  
• Host-header virtual hosts
  
  

Regardless of which virtual host configuration you choose, you must add each virtual host to httpd.conf in a separate <VirtualHost> container. Each section should include these directives:

Directive	Description
ServerName	The host name of this server.
ServerAdmin	The administrator for this host.
DocumentRoot	The root document directory for this host, a crucial alias for resolving URLs.
LogFormat	The format for the consolidated access/error log for this host. Although you can use separate access, error, and SSL logs for each host, combining them in a single configurable log saves file descriptors on sites that support many hosts.

In addition, you must add an SSL <VirtualHost> container for each virtual host. Each SSL section must include the directives listed above (except LogFormat), plus these SSL-specific directives:

Directive	Description
SSLFlag on	Enables SSL functionality for this virtual host.
SSLCertificateKeyFile	The path to the key file for this host, such as private/virtualhost.key.
SSLCertificateFile	The path to the certificate file for this host, such as certs/virtualhost.cert.

For example:

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

Note that the opening container tag must specify the SSL port number.

Port-based virtual hosts are supported by a single IP number. This approach assigns a unique port number to each host for both the regular and SSL configuration sets. For example:

<VirtualHost www.giraffe.com:880>
. . .
</VirtualHost>

<VirtualHost www.giraffe.com:444>
. . .
</VirtualHost>

<VirtualHost www.sloth.com:881>
. . .
</VirtualHost>

<VirtualHost www.sloth.com:445>
. . .
</VirtualHost>

Each virtual host must have two unique port numbers: one for ordinary transactions, and one for SSL-secured transactions. Furthermore, every link in every file belonging to a host must include a port number in order to direct the request to the appropriate host.

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

By assigning multiple IP numbers to your server machine, you can give each virtual host its own IP address. This is the most reliable virtual host configuration because it does not rely on browsers for support and does not require that users enter port numbers. The means for configuring multiple IP addresses vary from platform to platform, and the user guide for your operating system can provide assistance.

Once you've established multiple IP support, you can enter configuration sets for each virtual host in the configuration file. When you enter a virtual host container, you must specify the host with either an IP number or a hostname. If you enter a hostname, for example,

<VirtualHost www.c2.net:80>

then Stronghold performs a name lookup when it reads the file, to determine the IP number. If you use an IP number, for example,

<VirtualHost 140.174.185.14:80>

then Stronghold simply matches the IP of each incoming request to an IP in a virtual host container. When responding, Stronghold uses the hostname specified in the ServerName directive.

With the number of available IP numbers shrinking and the number of hostnames increasing, it's often most practical to use a single IP number for all virtual hosts on your site. This is host-based support, and it depends largely on the ability of browsers to include the Host field of request headers. The latest browsers, including Netscape Navigator and Microsoft Internet Explorer, support this feature. However, many older browsers do not.

As with IP-based virtual hosts, you must configure the Domain Naming System (DNS) to point all hostnames to your IP number. The means for doing this vary from platform to platform, and the user guide for your operating system can provide assistance. Once that is done, you only need to set the hostname for each virtual host so that Stronghold can recognize virtual host requests based on the Host header. For example:

<VirtualHost www.virtual.com:80>
ServerName www.virtual.com
ServerPath /virtual
DocumentRoot /www/virtual/htdocs
ServerAlias virtual.com *.virtual.com
</VirtualHost>

When it receives a request, Stronghold reads the Host header to get the hostname. If the host is www.virtual.com, virtual.com, ftp.virtual.com, or web.virtual.com, the server looks in /www/virtual/htdocs for the requested document.

Notice the ServerPath directive in the above example. By using ServerPath to associate a path with a particular virtual host, you provide a way for older browsers to imply which virtual hosts they are requesting. In the absence of a Host header, any request for http://www.virtual.com/virtual/ is directed to the document directory for that virtual host. Also, any initial request for http://www.virtual.com by an older browser will be directed to the main host's pages. You must, therefore, provide a link from the main page to www.virtual.com/virtual/. 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 virtual host requires a separate certificate. To support virtual hosts with multiple certificates, you must generate a key pair, request a certificate, and install the certificate when it arrives.

Run the genkey program just as you did for the original host, specifying a virtual host instead:

# genkey hostname

The key pair is saved at SSLTOP/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, Verisign, or Thawte, see Chapter 6.

[Top] [Prev] [Next] [Last]

© 1997 C2Net International Feedback: stronghold-docs@c2.net