Chapter 7:  Configuration Reference

Once Stronghold Web Server 3.0 is installed, it can be configured to suit your site. This chapter provides a quick reference to all configuration directives for the core Apache server, its precompiled modules, and its optional dynamically loadable modules. The directives control different aspects of server behavior including:

• General Configuration
• Additional Features
• Custom Log Formats
• Performance Tuning
• Proxy Service and Caching
• Logging
• Directory Tree
• File Handling and Preprocessing
• Content Delivery
• Client Authentication and Access Control
• Server Authentication
• Encryption
• Compatibility Directives

For each directive, this chapter gives several types of information:

• syntax

  This is the format of a directive's value.

• context

  There are three possible contexts, each denoting a level in the configuration hierarchy:

Although many directives can appear in more than one context, only one is given for each. The given context is the narrowest one in which the directive can appear; it can also appear in any larger context.

• module

  This is the module that facilitates the directives' functionality. If a directive applies to the core Apache server and not to any module, "core" is listed instead of a module name. If you add or remove modules, be sure to comment out the directives that pertain to it, or use the <Ifmodule> container to configure modules conditionally.

• default value (where applicable)

  This is the value given in the default httpd.conf file created when the server is installed.

• AllowOverride value (where applicable)

  This is the value of the AllowOverride directive that enables use of the current directive in .htaccess files.

General Configuration

Stronghold Web Server's general configuration directives control the most fundamental aspects of the server and its virtual hosts:

• Server Setup Directives
• Virtual Hosts
• SSL Setup
• .htaccess Configuration
• Environment Variables

Server Setup Directives

Most server setup directives are set by the installation program, but they can be changed at any time. They are not associated with any modules, but only with Stronghold's server core.

StrongholdLicenseFile

This sets the license file for the Stronghold Web Server 3.0 . The license file contains the license block you received via email when you downloaded or purchased the software. It looks like this:

*****BEGIN LICENSE BLOCK*****
MIIBOgIBAAJBAPkt+UzfOtml9SeKQp7vYV5DpGLiJs4lWScx9Rz5Zq7vQlMBqUBA
cqbANVQKK4SgbkqGBA6yQxEz5pYy2zTUeAECAwEAAQJAT0JOYCNJZt2hAzi5RDDE
eeVuLn3c9glvOEZtvw+dl9qmQzjLFC1cY1zi8+OeB3l9IX5YhsqcyeWBDpimmM5y
AQIhAPzX9vAx2zrztthis1is2not3a4real5license6blockHWUlMx7AOVOSJly
+lEGYXr0MI2sIzJbaJsmSjrktvcnbPECIBvT9SS4iAVz/x+Vy865lv6l4A2rdK6V
xCAabpgUAg7RAiEA7F1P+CL5Q5VYR8yRhdKD5NlWZMNREHgLL5Btp112+oECIGHw
+Ul0wkvw068K5wh+OBjC2o3P9gjv3QEyPsDY8ATh
*****END LICENSE BLOCK*****

The license block must be present in order to run the server. When using an evaluation copy of Stronghold, your license block expires when the evaluation period ends.

ServerRoot

The <ServerRoot> directive sets the directory in which the server binary is installed. It should contain all subdirectories required for server operation, such as conf/ and logs/. See The Server Directory Tree for a complete list of subdirectories the server expects to find here.

DocumentRoot

This directive sets the directory from which Stronghold Web Server 3.0 serves files. Unless matched by a directive like Alias, the server appends the path from the requested URI to the document root to form the path of the document. For example, if DocumentRoot/user/web is specified, then an access to http://www.my_host.com/index.html refers to /user/web/index.html

ErrorDocument

ErrorDocument controls Stronghold Web Server 3.0 's responses in the event of a problem. It is followed by an HTTP server error code and one of the following:

• the name of a file containing an error message or CGI program
• a quoted error message
• the URL of an error message file or CGI program

ErrorDocument 404 /cgi-bin/bad_urls.pl
ErrorDocument 500 http://www.c2.net/cgi-bin/tester
ErrorDocument 403 "Sorry, can't allow access today"

For a complete list of error codes and their meanings, see Appendix B Server Status Codes.

Listen

The Listen directive instructs the server to listen to one or more IP addresses or ports. The value for Listen can be an IP address or hostname and a port number, or a port number alone.

User

The User directive sets the user ID as which the server will answer requests. In order to use this directive, the server must be run initially as root. <id> is one of the following:

• username: Refers to a user by name, or
• # uid: Refers to a user by their UID. (N.B. this requires the hash symbol).

If the server is started by a non-root user, it will fail to change to the lesser privileged user and will instead continue to run as that original user. If the server starts as root, then it is normal for the parent process to remain running as root. The parent process does not serve any requests, so this does not represent a violation of access controls using the specified user ID.

Group

The Group directive sets the group under which the server answers requests. In order to use this directive, the server must run as root initially. <id> is one of the following:

• name: Refers to the group by name, or
• gid: Refers to a group by its number.

Options

The Options directive controls which server features are available. It is useful for limiting the freedom of virtual host customers. Options can be set to one or more of the following:

Any option can be prepared by a plus of minus sign (+ or -) to configure exceptions to a high-level Options directive. Simply add or subtract from the default option list like this:

<Virtualhost www.manatee.org:80>
options -ExecCGI+MultiViews
</VirtualHost>

If multiple options could apply to a directory, then the most specific one is taken complete, the options are not merged. For example:

<Directory /web/docs>
Options Index FollowSymLinks
lt;/Directory>
<Directory /web/docs/spec>
Options Includes
</Directory>

In this example, only "Includes" is set for the /web/docs/spec directory. The "Indexes" and "FollowSymLinks" options are set for all other subdirectories of /web/docs.

ServerAdmin

The ServerAdmin directive sets the email address of this host's administrator. The server uses it to notify the administrator when the host's certificate is about to expire.

It may be worth setting up a separate address for this, for example,
ServerAdmin webmaster@foo.bar.com as users do not always mention that they are talking about the server.

Include

This directive includes another configuration file, specified by a filename. The contents of the file are parsed at the current point in httpd.conf.

ServerSignature

The ServerSignature directive configures a trailing footer line under server-generated documents such as error messages, mod_proxy FTP directory listings, mod_info output, and so on. This is useful in a chain of proxies where the user often cannot tell which of the chained servers actually produced a returned error message.

The default "off" setting suppresses the error line.
• The "on" setting adds a line with the server version number and ServerName of the serving virtual host.
• The "email" setting adds a line with the server version number and ServerName of the serving virtual host, and additionally creates a "mailto:" reference to the ServerAdmin of the referenced document.

Virtual Hosts

Virtual host directives control basic, host-specific attributes of virtual hosts. For a broader discussion of virtual host configuration, see "Configuring Virtual Hosts" on page 6-10

ServerName

The ServerName directive sets the hostname of a host. This directive is only used for name-based virtual hosts and creating redirection URLs. The main server and all virtual hosts must each have the ServerName directive. If it is omitted, then the server attempts to deduce it from its own IP address. However, this may not always return the preferred hostname. For example, ServerName www.foo.com might be used even if the canonical name of the server platform were monster.foo.com.

NameVirtualHost

The NameVirtualHost directive is required for all name-based virtual hosts but is set at the global level (in other words, outside all <VirtualHost> containers). It specifies the IP address to which the hostname of the name-based virtual host resolves. Repeat this directive for each name-based host on each address.

Although IP can be a hostname, an IP address is recommended, such as:

NameVirtualHost 111.22.33.44

Optionally, specify a port number on which the name-based virtual host should be used, like this:

NameVirtualHost 111.22.33.44:8080

For more information about configuring name-based virtual hosts, see "Name-Based Virtual Hosts" on page 6-14.

ServerAlias

The ServerAlias directive sets alternate names for a host, for use with name-based virtual hosts. Each host can be a full hostname or a wildcard string.

UseCanonicalName

In many situations, the server must construct self-referential URLs. A self-referential URL refers back to the host itself. When UseCanonicalName is set to "on," Stronghold uses the ServerName and Port directives to construct a canonical name for the server. When UseCanonicalName is set to "off" Stronghold forms self-referential URLs using the hostname and port supplied by the client. If none is supplied by the client, it uses the canonical name. This name is used in all self-referential URLs, and for the values of SERVER_NAME and SERVER_PORT in CGIs.

ServerPath

The ServerPath directive sets the legacy URL pathname for a host, for use with name-based virtual hosts.

SSL Setup

These directives are required to enable SSL functionality for any host on the server. When SSL is enabled, server authentication is required but client authentication is not. See "Server Authentication" on page 7-94 for the required server authentication directives.

SSLEngine

This directive toggles the usage of the SSL/TLS Protocol Engine. This is usually used inside a <VirtualHost> section to enable SSL/TLS for a particular virtual host. By default the SSL/TLS Protocol Engine is disabled for both the main server and all configured virtual hosts.

Example:

<VirtualHost _default_:443>
SSLEngine on
...
</VirtualHost>

SSLPrototcol

This directive can be used to control the SSL protocol flavors Stronghold should use when establishing its server environment. Clients then can only connect with one of the provided protocols.

The available (case-insensitive) protocols are:

• SSLv2
  This is the Secure Sockets Layer (SSL) protocol, version 2.0. It is the original SSL protocol as designed by Netscape Corporation.

• SSLv3
  This is the Secure Sockets Layer (SSL) protocol, version 3.0. It is the successor to SSLv2 and the currently (as of February 1999) de-facto standardized SSL protocol from Netscape Corporation.

  It's supported by almost all popular browsers.

• TLSv1
  This is the Transport Layer Security (TLS) protocol, version 1.0. It is the successor to SSLv3 and currently (as of February 1999) still under construction by the Internet Engineering Task Force (IETF). It is still not supported by any popular browsers.

• All
  This is a shortcut for "+SSLv2 +SSLv3 +TLSv1" and a convenient way for enabling all protocols except one when used in combination with the minus sign on a protocol as the example above shows.

• enable SSLv3 and TLSv1, but not SSLv2
  SSLProtocol all -SSLv2

SSLRoot

SSLRoot is the root directory for SSL files such as keys and certificates. SSL file directives (except logging directives) can be relative to SSLRoot.

SSLMutex

SSLMutex supersedes SSLSessionLockFile see Compatibility Directives on page 7-115

This configures the SSL engine's semaphore (aka. lock) which is used for mutual exclusion of operations which have to be done in a synchronized way between the pre-forked Apache server processes. This directive can only be used in the global server context because it's only useful to have one global mutex. The following Mutex types are available:

• none
  This is the default where no Mutex is used at all. Use it at your own risk. But because currently the Mutex is mainly used for synchronizing write access to the SSL session cache you can live without it as long as you accept a sometimes garbled session cache. So it's not recommended to leave this the default. Instead configure a real Mutex.

• file:/path/to/mutex
  This is the portable and (under Unix) always provided Mutex variant where a physical (lock-)file is used as the Mutex. Always use a local disk filesystem for /path/to/mutex and never a file residing on a NFS- or AFS-filesystem. Note: Internally, the Process ID (PID) of the Apache parent process is automatically appended to /path/to/mutex to make it unique, so you don't have to worry about conflicts yourself. Notice that this type of mutex is not available under the Win32 environment. There you have to use the semaphore mutex.

• sem
  This is the most elegant but also most non-portable Mutex variant where a SysV IPC Semaphore (under Unix) and a Windows Mutex (under Win32) is used when possible. It is only available when the underlying platform supports it.

  Example:

  SSLMutex file:/usr/local/apache/logs/ssl_mutex

  
  

SSLPassPhraseDialog

When Stronghold starts up it has to read the various Certificate (see SSLCertificateFile) and Private Key (see SSLCertificateKeyFile) files of the SSL-enabled virtual servers. Because for security reasons the Private Key files are usually encrypted, Stronghold needs to query the administrator for a passphrase in order to decrypt those files. This query can be done in two ways which can be configured by type:

• builtin
  This is the default where an interactive terminal dialog occurs at startup time just before Apache detaches from the terminal. Here the administrator has to manually enter the passphrase for each encrypted Private Key file. Because a lot of SSL-enabled virtual hosts can be configured, the following reuse-scheme is used to minimize the dialog: When a Private Key file is encrypted, all known passphrase (at the beginning there are none, of course) are tried. If one of those known, passphrase succeeds no dialog pops up for this particular Private Key file. If none succeeded, another passphrase is queried on the terminal and remembered for the next round (where it perhaps can be reused). This scheme allows mod_ssl to be as flexible as possible (because for n encrypted Private Key files you can use N different passphrases - but then you have to enter all of them, of course) while minimizing the terminal dialog (i.e. when you use a single passphrase for all N Private Key files this passphrase is queried only once).

• exec:/path/to/program
  Here an external program is configured which is called at startup for each encrypted Private Key file. It is called with two arguments (the first is of the form servername:portnumber, the second is either "RSA" or "DSA"), which indicate for which server and algorithm it has to print the corresponding passphrase to stdout. The intent is that this external program first runs security checks to make sure that the system is not compromised by an attacker, and only when these checks were passed successfully it provides the passphrase.

  Both these security checks, and the way the passphrase is determined, can be as complex as you like. Mod_ssl just defines the interface: an executable program which provides the passphrase on stdout. Nothing more or less! So, if you're really paranoid about security, here is your interface.

Example:

SSLPassPhraseDialog exec:/usr/local/apache/sbin/pp-filter

SSLRandomSeed

Context: server config
Module: mod_ssl
Default: none

This configures one or more sources for seeding the Pseudo Random Number Generator (PRNG) in OpenSSL at startup time (context is startup) and/or just before a new SSL connection is established (context is connect). This directive can only be used in the global server context because the PRNG is a global facility.

The following source variants are available:

• builtin
  This is the always available builtin seeding source. Its usage consumes minimum CPU cycles under runtime and hence can be always used without drawbacks. The source used for seeding the PRNG contains of the current time, the current process id and (when applicable) a randomly chosen 1KB extract of the inter-process scoreboard structure of Apache. The drawback is that this is not really a strong source and at startup time (where the scoreboard is still not available) this source just produces a few bytes of entropy. So you should always, at least for the startup, use an additional seeding source.

• file:/path/to/source
  This variant uses an external file /path/to/source as the source for seeding the PRNG. When bytes is specified, only the first bytes number of bytes of the file form the entropy (and bytes is given to /path/to/source as the first argument). When bytes is not specified the whole file forms the entropy (and 0 is given to
  /path/to/source as the first argument). Use this especially at startup time, for instance with an available /dev/random and/or /dev/urandom devices (which usually exist on modern Unix derivatives like FreeBSD and Linux).

  But be careful: Usually /dev/random provides only as much entropy data as it actually has, i.e. when you request 512 bytes of entropy, but the device currently has only 100 bytes available two things can happen: On some platforms you receive only the 100 bytes while on other platforms the read blocks until enough bytes are available (which can take a long time). Here using an existing /dev/urandom is better, because it never blocks and actually gives the amount of requested data.

  The drawback is just that the quality of the received data may not be the best. On some platforms like FreeBSD one can even control how the entropy is actually generated, i.e. by which system interrupts. More details one can find under rndcontrol(8) on those platforms.

  Alternatively, when your system lacks such a random device, you can use tool like EGD (Entropy Gathering Daemon) and run it's client program with the exec:/path/to/program/ variant (see below).

• exec:/path/to/program
  This variant uses an external executable /path/to/program as the source for seeding the PRNG. When bytes is specified, only the first bytes number of bytes of its stdout contents form the entropy. When bytes is not specified, the entirety of the data produced on stdout form the entropy. Use this only at startup time when you need a very strong seeding with the help of an external program (for instance as in the example above with the truerand utility you can find in the Stronghold distribution which is based on the AT&T truerand library). Using this in the connection context slows down the server too dramatically, of course. So usually you should avoid using external programs in that context.

  Example:

  SSLRandomSeed startup builtin
  SSLRandomSeed startup file:/dev/random
  SSLRandomSeed startup file:/dev/urandom 1024
  SSLRandomSeed startup exec:/usr/local/bin/truerand 16
  SSLRandomSeed connect builtin
  SSLRandomSeed connect file:/dev/random
  SSLRandomSeed connect file:/dev/urandom 1024

  
  

SSLSessionCache

This configures the storage type of the global/inter-process SSL session cache. This cache is an optional facility which speeds up parallel request processing. For requests to the same server process (via HTTP keep-alive), OpenSSL already caches the SSL session information locally. Because modern clients request inlined images and other data via parallel requests (usually up to four parallel requests are common) those requests are served by different pre-forked server processes. Here an inter-process cache helps to avoid unneccessary session handshakes.

The following two storage types are currently supported:

• none
  This is the default and just disables the global/inter-process session cache. There is no drawback in functionality, but a noticeable speed penalty can be observed.

• dbm:/path/to/datafile
  This makes use of a DBM hashfile on the local disk to synchronize the local OpenSSL memory caches of the server processes. The slight increase in I/O on the server results in a visible request speedup for your clients, so this type of storage is generally recommended.

• shm:/path/to/datafile[(size)]
  This makes use of a high-performance hash table (approx. size bytes in size) inside a shared memory segment in RAM (established via /path/to/datafile) to synchronize the local OpenSSL memory caches of the server processes. This storage type is not available on all platforms.

  Examples:

  SSLSessionCache dbm:/usr/local/apache/logs/cache
  SSLSessionCache shm:/usr/local/apache/logs/cache(512000)

  
  

SSLSessionCacheTimeout

This directive sets the timeout in seconds for the information stored in the global/inter-process SSL session cache and the OpenSSL internal memory cache. It can be set as low as 15 for testing, but should be set to higher values like 300 in real life.

Example:

SSLSessionCacheTimeout 600

SSLOptions

AllowOverride: Options

This directive can be used to control various run-time options on a per-directory basis. Normally, if multiple SSLOptions could apply to a directory, then the most specific one is taken completely; the options are not merged. However if all the options on the SSLOptions directive are preceded by a plus (+) or minus (-) symbol, the options are merged. Any options preceded by a "+" are added to the options currently in force, and any options preceded by a "-" are removed from the options currently in force.

The available options are:

• StdEnvVars
  When this option is enabled, the standard set of SSL related CGI/SSI environment variables are created. This per default is disabled for performance reasons, because the information extraction step is a rather expensive operation. So one usually enables this option for CGI and SSI requests only.

• CompatEnvVars
  When this option is enabled, additional CGI/SSI environment variables are created for backward compatibility to other Apache SSL solutions.

• ExportCertData
  When this option is enabled, additional CGI/SSI environment variables are created:

  SSL_SERVER_CERT, SSL_CLIENT_CERT and SSL_CLIENT_CERT_CHAINn (with n = 0,1,2,..). These contain the PEM-encoded X.509 Certificates of server and client for the current HTTPS connection and can be used by CGI scripts for deeper Certificate checking. Additionally all other certificates of the client certificate chain are provided, too. This bloats up the environment a little bit which is why you have to use this option to enable it on demand.

• FakeBasicAuth
  When this option is enabled the Subject Distinguished Name (DN) of the Client X509 Certificate is translated into a HTTP Basic Authorization username. This means that the standard Apache authentication methods can be used for access control. The user name is just the Subject of the Client's X509 Certificate (can be determined by running OpenSSL's openssl x509 command:

  openssl x509 -noout -subject -in certificate.crt).

  Note that no password is obtained from the user. Every entry in the user file needs this password: "xxj31ZMTZzkVA", which is the DES-encrypted version of the word "password". Those who live under MD5-based encryption (for instance under FreeBSD or BSD/OS, etc.) should use the following MD5 hash of the same word:
  
  "$1$OXLyS...$Owx8s2/m9/gfkcRVXzgoE/".

• StrictRequire
  This forces forbidden access when SSLRequireSSL or SSLRequire successfully deciding that access should be forbidden. Usually the default is that in the case where a "Satisfy any" directive is used, and other access restrictions are passed, denial of access due to SSLRequireSSL or SSLRequire is overridden (because that's how the Apache Satisfy mechanism should work.) But for strict access restriction you can use SSLRequireSSL and/or SSLRequire in combination with an "SSLOptions +StrictRequire". Then an additional "Satisfy Any" has no chance once mod_ssl has decided to deny access.

• OptRenegotiate
  This enables optimized SSL connection renegotiation handling when SSL directives are used in per-directory context. By default a strict scheme is enabled where every per-directory reconfiguration of SSL parameters causes a full SSL renegotiation handshake. When this option is used mod_ssl tries to avoid unnecessary handshakes by doing more granular (but still safe) parameter checks. Nevertheless these granular checks sometimes maybe not what the user expects, so enable this on a per-directory basis only.

  Example:

  SSLOptions +FakeBasicAuth -StrictRequire
  <Files ~ "\.(cgi|shtml)$">
  SSLOptions +StdEnvVars +CompatEnvVars -ExportCertData
  <Files>

  
  

SSLCARevocationPath

This directive sets the directory where you keep the Certificate Revocation Lists (CRL) of Certification Authorities (CAs) whose clients you deal with. These are used to revoke the client certificate on Client Authentication. The files in this directory have to be PEM-encoded and are accessed through hash filenames. Usually you have not only to place the CRL files there. Additionally you have to create symbolic links named hash-value.rN. And you should always make sure this directory contains the appropriate symbolic links. Use the Makefile which comes with mod_ssl to accomplish this task.

Example:

SSLCARevocationPath /usr/local/apache/conf/ssl.crl/

SSLCARevocationFile

This directive sets the all-in-one file where you can assemble the Certificate Revocation Lists (CRL) of Certification Authorities (CA) whose clients you deal with. These are used for Client Authentication. Such a file is simply the concatenation of the various PEM-encoded CRL files, in order of preference.

This can be used alternatively and/or additionally to SSLCARevocationPath.

Example:

SSLCARevocationFile /usr/local/apache/conf/ssl.crl/ca-bundle-client.crl

SSLCertificatePath

This directive sets the directory where you keep the Certificates of Certification Authorities (CAs) whose clients you deal with. These are used to verify the client certificate on Client Authentication. The files in this directory have to be PEM-encoded and are accessed through hash filenames. So usually you can't just place the Certificate files there: you also have to create symbolic links named hash-value.N. And you should always make sure this directory contains the appropriate symbolic links.Use the Makefile which comes with mod_ssl to accomplish this task.

Example:

SSLCACertificatePath /usr/local/apache/conf/ssl.crt/

Additional Features

Environment Variables

Environment variables are system parameters that Stronghold's CGI module uses. These directives specify the environment variables that Stronghold automatically passes to the CGI module, including browser-dependent variables.

PassEnv

SetEnv

With SetEnv, you can explicitly set a CGI environment variable. For example

SetEnv LIBDIR /www/lib

SetEnvIf

The SetEnvIf directive defines environment variables based on attributes on the request. THese attributes can be the values of various HTTp request header fields or other aspects of the request, including the following:

Some of the more commonly used request header field names include Host, User-Agent, and Referer.

For example:

SetEnvIf Request_URL "\.(gif)|(jpg)|(xbm)$" object_is_image
SetENvIf Referer www\.mydomainin\.com intra_site_referral

The first example sets the environment variable object_is_image if the requested file is an image file. The second example sets intra_site_referral if the referring page is somewhere on the www.mydomain.com site.

SetEnvIfNoCase

SetEnvIfNoCase is semiautomatically identical to the SetEnvIf directive, except that the regular expression matching is cas-sensitive. or example:

SetEnvIfNoCase Host Apache\.org site=apache.

This causes the site environment variable to be set to "apache" if the Host HTTP header was included and contained Apache.Org. apache.org, or any other variation.

UnSetEnv

UnSetEnv excludes variables from being set or passed. For example, if PassEnv and SetEnv are set for the root document directory, but a subdirectory cannot use the given variables, you can use UnSetEnv to exempt the subdirectory from those variable settings.

BrowseMatch

The server configuration can include one or more BrowserMatch directives, which define environment variables based on the User-Agent HTTP header in client requests. Stronghold reads multiple BrowserMatch entries in the order in which they appear in httd.conf. regex is a POSIX.2 regular expression that denotes a User-Agent string match. If a User-Agent string matches more than one BrowserMatch argument, Stronghold merges the arguments, regex is followed by one or more variable strings that can take the following forms:

For example, BrowserMatch is included in the default configuration to disable Keepalive support for Netscape 2.x browsers, which have problems related to keepalive:

BrowserMatch Mozilla/2 nokeepalive

BrowserMatchNoCase

BrowserMatchNoCase is identical to BrowseMatch above, except that its argument are case-insensitive.

Custom Log Formats

When mod_ssl is built into Apache or at least loaded (under DSO situation) additional functions exist for the Custom Log Format of mod_log_config. First there is an additional "%{varname}x" extension format function which can be used to expand any variables provided by any module, especially those provided by mod_ssl.

For backward compatibility there is additionally a special "%{name}c" cryptography format function provided.

Example:

CustomLog logs/ssl_request_log \
"%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b".

.htaccess Configuration

Although the httpd.conf file can control all aspects of the server, some directives can also be used in per-directory configuration files, usually called.htaccess files. This configuration can be useful if directories moved frequently, or to give users some control over Web files in their own directories. Any directory that contains files accessed by the server can also contain a htaccess file.

Per-directive configuration files are enabled only when

• the AccessFileName directive is present and
• AlowOverride is set to a value other than "none."

AccessFileName

When this directive is set, the server looks for one or more specified filenames (usually .htaccess) in every directory of the path to a requested document. For example, a request for /usr/local/web/index.html causes Stronghold to look for
/.htaccess, /usr/.htaccess, /usr/local/.htaccess, and
/usr/local/web/.htaccess, unless per-directory configuration files have been disabled with

AllowOverride None

AllowOverride

When the server finds a .htaccess file (as specified by Access Filename), it needs to know which of its directives can override the main configuration file.

AllowOverride can be set to one or more of the following:

The directives in "Perl Scripting" are valid in .htaccess files if AllowOverride is set to any value except "none."

Environment Variables

PassEnv

PassEnv specifies one or more environment variables that are passes from the shell environment to the CGI environment.

SetEnv

SetEnv explicitly sets a CGI environment variable. For example:

SetEnv LIBDir /www/Lib

SetEnvIf

The SetEnvIf directive defines environment variables based on attributes of the request. These attributes can be the values of HTTP request header fields or environment variables. For example:

SetEnvIf Request_URI "\.(gif)|(jpg)|(xbm)$" object_is_image
SetEnvIf Referer www\.mydomain\.com intra_site_referral

The first example sets the environment variable Request_URL if the requested file is an image file. The second example sets Referer if the referring page is somewhere on the www.mydomain.com site.

SetEnvIfNoCase

SetEnvIfNoCase Host C2\.Net site=c2

UnSetEnv

UnSetEnv excludes variables from being set or password. For example, if OassEnv and SetEnv are set for the root directory cannot use the given variables, use UnSetEnv to exempt the subdirectory from those variable settings.

BrowserMatch

The BrowserMatch directive defines environment variables based on the User-Agent request header. Stronghold reads multiple BrowserMatch entries in the order in which they appear in httpd.conf. Regex is a POSIX2 regular expression that denotes a User-Agent string match. If a User-Agent string matches more than one BreowserMatch argument, Stronghold merges the arguments. Regex is followed by one or more variable strings that can take the following forms:

BrowserMatch is included in the default configuration to disable KeepAlive support for Netscape 2 x browsers, which have KeepAlive problems:

Browsermatch Mozilla/2 nokeepalive

BrowserMatchNoCase

BrowsermatchNoCase is dientical to BrowserMatch, except that its argument are case-insensitive.

Performance Tuning

Stronghold's flexible design accommodates a wide variety of hardware configurations and traffic loads. Use the directives in this section to optimize Stronghold for your unique platform and site:

• Basic Performance Tuning
• Keepalive
• Process Control
• Resources
• Dynamic Shared Objects

Basic Performance Tuning

These directives control the basic functions that affect Stronghold's performance.

StrongholdAccelerator

Stronghold Accelerator indicates whether the server platform has an installed ecnryption accelerator. By default, it is set to "none."

For more information about cryptographic hardware contact C2Net

ServerType

The ServerType directive sets how the server is executed by the system. Type is one of the following:

• inetd
  The server runs from the system process inetd; the command to start the server is added to /etc/inetd.conf. This option is not recommended, primarily because it does not function with SSL.

• standalone
  The server runs as a daemon process. This is the most efficient setting, since the server starts once and services all subsequent connections. If Stronghold serves a busy site, "standalone" is the only viable option.

CoreDumpDirectory

This sets the directory to which Stronghold attempts to switch before dumping a core. The default is the <ServerRoot> directory. However, since this directory should not be writeable by the user the server runs as, core dumps normally do not get written. To obtain a core dump for debugging, temporarily set this directive to place it in a writeable location.

SendBufferSize

SendBufferSize sets the TCP buffer size. Use it to optimize Stronghold for high-bandwidth, high-latency file transfers such as trans- or intercontinental transfers.

TimeOut

The TimeOut directive sets the maximum time, in seconds, that the server will wait for the client to acknowledge receipt of the last server response. If it takes more than n seconds for a client to receive and acknowledge the response, the server breaks off the connection. On slow networks, increasing the TimeOut value may help.

Keepalive

Normally every HTTP request and response uses a separate connection. This can slow server response time, because the server must open and close a connection each time it receives a request or sends a response. To improve transaction speed, use Stronghold's keepalive feature to reserve an open connection for a series of requests and responses. These directives set the parameters of keepalive functionality.

KeepAlive

This directive enables and disables persistent connections.

KeepAliveTimeout

This sets the number of seconds Stronghold will wait for a subsequent request before closing the connection.

MaxKeepAliveRequests

This directive sets the maximum number of requests that Stronghold fulfills during any single keepalive connection. The default is 100.

If MaxKeepAliveRequests, MaxKeepAliveTimeout, and TimeOut are all set, then Stronghold terminates the keepalive connection when any of those conditions are fulfilled.

Process Control

Process control refers to control of the HTTPD parent process and the child processes it spawns. These directives limit the number and lifespan of server processes.

ListenBacklog

This sets the maximum length of the queue of pending requests. Generally, no tuning is needed. However, on some systems it is desirable to increase this when under a TCP SYN flood attack. See the backlog parameter to the listen(2) system call.

LockFile

The LockFile directive sets the path to the lockfile used when the server is compiled with either USE_FCNTL_SERIALIZED_ACCEPT or USE_FLOCK_SERIALIZED_ACCEPT. This directive can normally be left at its default value. It should be changed if the logs/ directory is NFS-mounted, since the lockfile must be stored on a local disk. The PID of the main server process is automatically appended to the filename.

See also SSLSessionLockFile on page 7-115.

MaxClients

The MaxClients directive sets the limit on the number of simultaneous requests that can be served. This is the maximum number of child server processes created on startup. It should never be set to a value less than 2.

A hard limit of 256 simultaneous requests is set in the <ServerRoot>/src/httpd.h.If necessary, edit this file and recompile the server with a different hard limit. See "Recompiling Stronghold" on page 8-6 for instructions on recompiling Stronghold.

MaxRequestsPerChild

The MaxRequestsPerChild directive sets the limit on the number of requests that each child process serves. After serving n requests, the child process dies. If MaxRequestsPerChild is 0, then children never expire.

Setting MaxRequestsPerChild to a non-zero limit has two beneficial effects:

• It limits the amount of memory that a process can consume by accidental memory leakage.
• By giving processes finite lifetimes, it helps reduce the number of processes when the server load falls.

MaxSpareServers

The MaxSpareServers directive sets the maximum number of idle child processes. An idle process is one which is not handling a request. If there are more than n MaxSpareServers idle, then the parent process kills the excess children.

This parameter should need tuning only on very busy sites. Setting this parameter to a number larger than necessary is almost always a bad idea.

MinSpareServers

The MinSpareServers directive sets the minimum number of idle child server processes. An idle process is one which is not handling a request. If there are fewer than n MinSpareServers idle, then the parent process creates new children at a maximum rate of one per second.

This parameter should need tuning only on very busy sites. Setting this parameter to a number larger than necessary is almost always a bad idea.

StartServers

The StartServers directive sets the number of child processes initially created on startup. As the number of processes is dynamically controlled depending on the load, there is usually little reason to adjust this parameter.

Resources

RLimitCPU

RLimitCPU sets the CPU resource limit for all server processes. It can have one or two values, and the values are either n or "max," where

• n is seconds per process
• "max" is the maximum resource limit allowed by the operating system

RLimitMEM

RLimitMEM sets the memory resource limit for all server processes. It can have one or two values, and the values are either n or "max," where

• n is bytes per process
• "max" is the maximum resource limits allowed by the operating system

RLimitNPROC

RLimitNPROC sets the maximum number of processes per user. For example, use this directive to control the number of simultaneous CGI processes allowed per individual user. It can have one or two values, and the values are either n or "max," where

• n is processes per user
• "max" is the maximum resource limit allowed by the operating system. Whether you give this directive one value or two, the first value is always the soft resource limit. If there are two values, the second is the hard resource limit.

Dynamic Shared Objects

LoadModule

LoadModule status_module src/modules/ mod_status loads the status module from the src/modules sub directory of <ServerRoot>.

LoadFile

Dynamic Module Linking

By default, all modules compiled into Stronghold are active, meaning that they all start with the server and can be used at any time thereafter. With dynamic modules, compiled-in modules can be activated or deactivated without Recompiling Stronghold, by modifying httpd.conf and restarting Stronghold. This makes it quick and easy to optimize the server by suspending unnecessary modules.

ClearModuleList

AddModule

When ClearModuleList is set AddModule sets the list of active modules. The values must be module names as they appear in the Configuration file, and they must already be compiled into Stronghold. For example,

AddModule mod_cgi.c mod_ssl.c mod_dir.c mod_userdir.c mod_alias.c

limits the active modules to CGI, SSl, directory indexing, user directories, and aliasing. Although other modules may be compiled into the server, only these five modules can be invoked under this configuration.

Whenever a module is added or removed from the AddModule list, Stronghold must restart to implement the changes. For instructions on restarting the server, see "Restarting Stronghold" on page 1-3

Proxy Service and Caching

Stronghold can act as a proxy server using mod_proxy. The proxy module is described i more detail in Chapter 4, "Proxy Service."

ProxyRequests

ProxyRequests enables normal caching proxy service. For example, add this directive to use Stronghold as a firewall that serves documents from remote hosts to users on your LAN.

ProxyRemote

This directive defines remote proxies to the Stronghold proxy server. Match is one of the following:

• the name of a URL scheme that the remote server supports
• a partial URL for which the remote server should be used
• "*" to indicate the server should be contacted for all requests.
• Hostname and port are the remote host and port to forward to.

ProxyRemote ftp http://ftpproxy.mydomain.com:8080
ProxyRemote http://goodguys.com/ http://mirrorguys.com:8000
ProxyRemote * http://cleversite.com

ProxyPass

This directive allows remote servers to be mapped into the space of the local server; the local server does not act as a proxy in the conventional sense, but appears to be a mirror of the remote server. Path is the name of a local virtual path; URL is a partial URL for the remote server. Suppose the local server has address http://wibble.org In that case,

ProxyPass /mirror/foo http://foo.com

causes a local request for the http://wibble.org/mirror/foo/bar to be internally converted into a proxy request to http://foo.com/bar

ProxyRequests and the cache directives are included in the default configuration file, commented out. To use their default values, simply uncomment them. They can be modified to suit any configuration. See ProxyPassReverse

ProxyPassReverse

This directive causes Stronghold to adjust the URL in the Location header in HTTP redirect responses. When Stronghold is used as a reverse proxy, this is essential to prevent servers behind the proxy from bypassing it with HTTP redirects.

• Path is the name of a local virtual path.
• URL is a partial URL for the remote server.

ProxyPass /mirror/foo http://foo.com
ProxyPassReverse /mirror/foo http://foo.com

In this example, ProxyPass causes a local request for the
http://wibble.org/mirror/foo/bar to be internally converted into a proxy request to http://foo.com/bar. If the server foo.com redirects http://foo.com/bar to http://foo.com/quux, the ProxyPassReverse directive causes Stronghold to adjust this to http://wibble.org/mirror/foo/quux before forwarding the HTTP redirect response to the client.

ProxyBlock

ProxyBlock garage.com host.co.uk rocky.wotsamattau.edu

NoProxy

The NoProxy directive specifies a space-separated list of domain, subnets, IP addresses, and/or hosts. A request to a host which matches one or more of these is always served directly, without forwarding to the configured ProxyRemote proxy servers. For example, it is useful for preventing a proxy on an intranet from proxying requests to internal hosts:

ProxyRemote * http://firewall.mycompany.com:81
NoProxy .mycompany.com 192.168.112.0/21

The arguments can take several different forms:

• domain
  A domain is a partially-qualified domain name representing a set of hosts which logically belong to the same domain or zone. To distinguish domains from hostnames, domains are always written with a leading period. For example:

  NoProxy .com .apache.org.

  
  This example designates all domain names ending in .com or .apache.org

  Domain name comparisons are case-insensitive. Since a domain comparison for proxy service does not involve a DNS lookup, it is more efficient than subnet comparison.

• subnet
  A subnet is a partially-qualified IP address, optionally followed by a slash and the netmask, specified as the number of significant bits in the subnet. It is used to represent a subnet of hosts which can be reached over a common network interface. In the absence of the explicit netmask, it is assumed that omitted (or zero-valued) trailing digits specify the mask. In this case, the netmask can only be multiples of 8 bits wide. For example,

  NoProxy 192.168

  
  and

  NoProxy 192.168.0.0

  
  both designate the subnet 192.168.0.0 with an implied netmask of 16 valid bits (sometimes used in the netmask form 255.255.0.0). Likewise,

  NoProxy 192.168.112.0/21

  
  designates the subnet 192.168.112.0/21 with a netmask of 21 valid bits (also used in the form 255.255.248.0).

  As a degenerate case, a subnet with 32 valid bits is the equivalent to an ordinary IP address, while a subnet with zero valid bits, such as 0.0.0.0/0, is the same as the constant "_Default_," matching any IP address.

• IP address
  For example:

  NoProxy 192.168.123.7

  
  Because an IP address need not be resolved into a hostname, it can result in more effective server performance than a hostname.

• hostname
  A hostname is a fully-qualified domain name which resolves into an IP address. For example:

  NoProxy prep.ai.mit.edu www.apache.org

  
  

ProxyDomain

ProxyRemote * http://firewall.mycompany.com:81
NoProxy .mycompany.com 192.168.112.0/21
ProxyDomain .mycompany.com

In this example, a request for the host www is redirected to www.mycompany.com

ProxyReceiveBufferSize

The ProxyReceiveBufferSize directive sets the buffer size for outgoing HTTP and FTP transactions, in bytes. N must be greater than 512 bytes, or it can be set to 0 to inherit the system's default buffer size.

ProxyVia

HTTP 1.1 requires that proxy servers use the Via HTTP header to record the protocols and proxy hosts used between the client and the server. The ProxyVia directive controls how Stronghold treats Via headers when performing proxy transactions. Its valid values are as follows:

AllowCONNECT

CONNECT is a generic protocol used to encapsulate SSL/TLS transactions during normal proxy service (enabled with ProxyRequests). Normally, Stronghold allows transactions using the CONNECT protocol only on ports 443 and 563. AllowCONNECT sets one or more other ports on which CONNECT is allowed.

CacheRoot

This directive enables disk caching for proxy requests. <Directory> is the directory in which cached files are stored.

CacheDirLength

For faster retrieval, Stronghold caches files by hashing their URLs, then using the beginning of each hash as a subdirectory path within the CacheRoot directory. The remainder of the hash forms the filename. CacheDirLength sets the number of characters in each subdirectory name. The default is 1.

CacheDirLevels

This sets the maximum number of levels of subdirectories within the CacheRoot directory.

CacheSize

This directive sets the size of the disk cache in megabytes.

CacheGcInterval

This directive sets the garbage collection interval, in hours. At each interval, Stronghold checks the cache for expired files and deletes them.

CacheMaxExpire

CacheMaxExpire sets the maximum expiration time for all cached files, in hours. This setting overrides any expiry time that may be set for individual cached files.

CacheLastModifiedFactor

When it reaches a garbage collection interval, Stronghold compares two numbers:

• the value for CacheMaxExpire
• the time since each file was last modified multiplied by the CacheLastModifiedFactor

CacheDefaultExpire

If Stronghold does not have information about when a cached file was last modified, it uses the value set by CacheDefaultExpire.

CacheForceCompletion

If a client cancels a proxy transaction before the transaction is complete, Stronghold finishes caching the requested file if n percent is already downloaded.

NoCache

This sets one or more server hosts whose responses are excluded from caching. Use this directive to prevent Stronghold from caching documents that it receives from local servers.

Logging

Stronghold uses a set of log files to record its activities, including transactions, errors, and SSL ciphers:

• General Logs
• SSLErrorFile

For more detailed information about logs, see Chapter 1 "Using Logs and Reports".

General Logs

These logs record data about non-SSL transactions.

TransferLog

This sets the path to the access log file. This is Stronghold's main log, where all normal, unsecured transactions are recorded. If this directive is not present, no log is written. If the filename does not begin with a slash (/), then it is assumed to be relative to the <ServerRoot>. If TransferLog is not accompanied by LogFormat, it follows the common log format. The default log has the following format:

LogFormat "%h %u %l %t \"%r\" %>s %b"

LogFormat

This sets a customized format for the transfer log file. It can also be used to associate a log format with a format nickname, which can be used with the CustomLog directive or other instances of LogFormat instead of a full format string.

The LogFormat values can also be used with the CustomLog directive, which establishes a separate, customized log file. String can include literal characters to copy into the log files, plus any of these variables, denoted by a percent sign

In variables with bracketed values, the percent sign (%) can be followed by one or more optional, comma-separated HTTP status codes as conditions of the log field. The status codes can be preceded by an exclamation point (!) to indicate "not." For example,

LogFormat "%400,501{User-agent}i"

logs the User-Agent header only for r 501 Not Implemented requests that return server status codes of 400 Bad Request or 501 Not Implemented, and

LogFormat "%!200,304,302{Referer}i"

logs the Referer header for all requests that return an irregular server status code.

Any virtual host can have its own TransferLog with its own LogFormat. If it doesn't have its own LogFormat, it inherits one from the main server. If it doesn't have its own TransferLog, it writes to the same description as the main host.

For a complete list of status codes and their meanings, see Appendix B Server Status Codes.

CustomLog

The CustomLog directive creates a log for any purpose. Filename is a path to a log file. String is a variable string that sets the format of each log entry, and it uses the same variables as LogFormat above.

If the option env=environment-variable is given, the log line will only be written if the named environment variable is set. If an exclamation mark is given before the environment variable name then the log line is written only if the environment variable is not set. Environment variables are typically set by SetEnvIf or rewrite rules.

ErrorLog

The ErrorLog directive sets the path to the file used to log errors that occur during regular, unsecured transactions. If the filename does not begin with a slash (/), then it is assumed to be relative to the <ServerRoot>.Using "syslog" instead of a filename enables logging via syslogd(8), if the system supports it. For a sample error log, see Chapter 1 "Error Logs".

LogLevel

LogLevel sets the verbosity of the messages recorded in the error logs created by the ErrorLog directive. The following levels are available, in order of decreasing significance:

Significance

CookieLog

HostnameLookups

When this directive is set to "on," Stronghold logs hostnames by performing reverse lookups. When it is set to "off" or omitted, Stronghold logs only the IP address. When it is set to "double," Stronghold performs a "double-reverse" lookup by performing a reverse DNS lookup, then a forward lookup on that result; at least one of the IP address from the result of the forward lookup must match the original IP number. It is set to "off" by default to reduce unnecessary and time-consuming DNS traffic.

PidFile

The PidFile directive specifies the file to which the server records the process ID of the server parent process. If the filename does not begin with a slash (/), then it is assumed to be relative to the <ServerRoot>. Stronghold's bin/reload-server and bin/stop-server scripts use PidFile to signal the parent process ID.

ScoreBoardFile

The ScoreBoardFile directive sets the path to the file used to store server status information. If the filename does not begin with a slash (/), then it is assumed to be relative to the <ServerRoot>. The file itself is used by child processes to write information used by the parent process to manage the children. It is also used by mod_status to construct server status reports, as described in "Server Status Reports" on page 1-10.

IdentityCheck

This directive enables RFC1431-compliant logging of the remote user name for each connection, where the client machine runs identd or something similar. This information is logged in the access log.

ExtendedStatus

The ExtendedStatus directive enables and disables server status reports when mod_status is compiled into the Stronghold binary. Although mod_status is compiled into Stronghold by default, status reports are turned off to conserve server resources. Set this directive to "on" to enable them.

AddModuleInfo

This allows the content of string to be shown as HTML-interpreted text in the Additional Information field for the named module in the server information report. For example:

AddModuleInfo mod_auth.c

• http://www.apache.org/docs/mod/mod_auth.html
• http://www.apache.org/docs/mod/mod_auth.html

CGI Error Logs

AgentLog

The AgentLog directive sets the name of the file to which the server will log the UserAgent header of incoming requests. File-pipe is one of the following:

• A filename relative to the <ServerRoot>
• "|command," that is, a pipe into a program that receives that agent log information on its standard input. Note that a new program will not be started for a virtual host if it inherits the AgentLog from the main server. For example, this is root if the server was started by root.

RefererLog

The refererLog directive sets the name of the file to which the server will log the Referer header of incoming requests. File_pipe is one of the following:

• A filename relative to the <ServerRoot>
• "|command." that is, a pipe to the program that receives the referer log information on its standard input.

This directive is provided for compatibility with NCSA 1.4.

RefererIgnore

The RefererIgnore directive is optional and sets a list of strings to ignore in Referer headers. If any of the strings in the list is contained in the Referer header then no referer information will be logged for the request. For example,

refererIgnore www.ncsa.uiuc.edu

SSL Logs

These logs record data about SSL transactions.

SSLLogFile

Stronghold stores information about each SSL-enabled connection--such as cipher and client-authentication data--in the SSLLogFile.

SSLErrorFile

Stronghold uses the SSLErrorFile to record errors that occur during SSL transactions.

SSL_CertificateLogDir

SSL_CertificateLogDir sets the path to the directory where Stronghold logs client certificates.

SSLLog

This directive, along with SSLLogLevel supersedes the following directives ScriptLog, ScriptLogLength and ScriptLogBuffer. See Compatibility Directives on page 7-115

If the filename does not begin with a slash ('/') then it is assumed to be relative to the <ServerRoot>. If filename begins with a bar ('|') then the following string is assumed to be a path to an executable program to which a reliable pipe can be established. The directive should occur only once per virtual server config.

Example:

SSLLog /usr/local/apache/logs/ssl_engine_log

SSLLogLevel

This directive, along with SSLLog supersedes the following directives ScriptLog, ScriptLogLength and ScriptLogBuffer. See Compatibility Directives on page 7-115

This directive sets the verbosity degree of the dedicated SSL protocol engine logfile. The level is one of the following (in ascending order where higher levels include lower levels):

• none
  no dedicated SSL logging is done, but messages of level "error" are still written to the general Apache error logfile.

• error
  log messages of error type only, i.e. messages which show fatal situations (processing is stopped). Those messages are also duplicated to the general Apache error logfile.

• warn
  log also warning messages, i.e. messages which show non-fatal problems (processing is continued).

• info
  log also informational messages, i.e. messages which show major processing steps.

• trace
  log also trace messages, i.e. messages which show minor processing steps.

• debug
  log also debugging messages, i.e. messages which show development and low-level I/O information.

SSLLogLevel warn

Directory Tree

Stronghold Web Server 3.0 supports one directory tree directive, which sets the default index file for directories. This directive is necessary for serving error files.

These directives control

• Alias
  aliases let you manipulate URLs and incorporate directories outside your DocumentRoot --including directories on other servers--by assigning pseudonyms to directories

• DirectoryIndex
  directory indexing sets the default file that Stronghold returns when it receives a request for a directory, and controls how it formats the pages it generates when no such file exists.

Aliases

Alias

The alias directive maps an actual path on your server to an alias. For example, if the hostname is www.random.com and you include the line

Alias /icons/ /path/icons/

then the URL http://www.random.com/icons/ points to the directory. This means that URLs and other references do not necessarily have to refer to documents under the root document directory.

AliasMatch

This directive is equivalent to Alias, but uses standard regular expressions instead of simple prefix matching. The regex is matched against the requested URL. If it matches, the server substitutes any parenthesized matches into the given string and uses it as a filename. For example, one could use the following to activate the /icons directory:

AliasMatch ^/icons(.*) /usr/local/apache/icons$1

ScriptAlias

ScriptAlias works just like Alias, except that any file in the specified directory is a CGI script by default. This means that your scripts do not necessarily have to reside in <ServerRoot>/cgi-bin, and that any file in a ScriptAlias directory is automatically executed.

ScriptAliasMatch

This directive is equivalent to ScriptAlias, but uses standard regular expressions instead of simple prefix matching. The regex is matched against the requested URL. If it matches, the server substitutes any parenthesized matches into the given path string and uses it as a filename. For example, one might use the following to activate the standard
/cgi-bin:

ScriptAliasMatch ^/cgi-bin(.*) /usr/local/apache/cgi-bin$1

Redirect

Redirect provides aliases to other resources, whether on your host machine or a remote server, Type is one of the following:

• "temp" for temporary redirections
• "perm" for resources that have been permanently relocated
• "gone" for resources that no longer exist.

redirect perm /secure/https://www.host.com/secure/

causes Stronghold to redirect all requests for http://www.host.com/, which simply connects the client to the same page using SSL. Stronghold will also direct any requests for http://www.host.com/secure/whatever

RedirectMatch

This directive is equivalent to Redirect, but uses standard regular expressions instead of simple prefix matching. The regex is matched against the requested URL. If it matches, the server substitutes any parenthesized matches into the given URL string and uses it as a filename. For example, one could use the following to redirect all GIF files to like-named JPEG files on another server:

RedirectMatch (.*)\.gif$http://www.anotherserver.com$1.jpg

RedirectTemp

This directive is equivalent to

redirect temp

RedirectPermanent

this directive is equivalent to

redirect perm

UserDir

The UserDir directive sets the real directory in a user's home directory to use when a request for a document for a user is received. Directory is either disabled, to disable this feature, or the name of a directory, following one of the following patterns. If not disabled, then a request for http://www.foo.com/~bob/one/two.html will be translated to:

UserDir public_html -> ~bob/public_html/one/two.html
UserDir /usr/web -> /usr/web/bob/one/two.html
UserDir /home/*/www -> /home/bob/www/one/two.html

Directory Indexing

These directives configure Stronghold's responses to requests for directories but not files. This behavior is controlled by two modules:

• mod_dir uses one directive, DirectoryIndex, to set the default file for directory requests. Requests for directories are fulfilled with this file, if it exists.
• If the default file does not exist, mod_autoindex fulfills a directory request by generating an HTML index of the files in the requested directory.

DirectoryIndex

This directive sets the filename of the default index file for any directory. When a client sends a request URL to a directory but not a specific file, Stronghold returns the DirectoryIndex file. You can list any number of filenames, in order of priority; Stronghold looks for each and return the first one it finds. By specifying the path to a file that contains an error message as the last item on the list, you can cause Stronghold to return that message if it finds none of the previous filenames.

For example, if this directive is set to

DirectoryIndex index.html /errors/404.html

in the global configuration, then a request for http://www.host.net/ actually returns http://www.host.net/index.html, if the index.html file exists. If it does not exist, the request returns http://www.host.net/errors/404.html. However, if it is set to

DirectoryIndex index.html

FancyIndexing

If Stronghold finds no index file for a requested directory, it generates an HTML-formatted file list for that directory on the fly. Normally, this is just an unordered list of linked filenames. To generate icons and extra information, including modification dates, file sizes, and descriptions, set FancyIndexing to "on." Fancy indexes are also sortable. Users can click a column heading to sort by that column. Clicking the column heading again toggles between ascending and descending order. To suppress the sortable index feature, set IndexOptions to "SurpressColumnSorting"

AddIcon

With FancyIndexing set, Stronghold generates detailed file lists with an icon next to each filename. AddIcon matches one Icon file to one or more filenames that might appear in such a list. This means that Stronghold can display different icons for different files or file types. Filename can be a full filename, a wildcard expression, or a suffix, such as .bin or .exe. There are also two special names you can use for filename: "^^DIRECTORY^^" for subdirectories within the directory being listed, and "^^BLANKICON^^" for adding icons to blank lines.

To allow for browsers that have graphics turned off or do not support graphics at all, you can specify an ALT tag for each icon. The syntax for this feature is:

AddIcon (EXE, /icons/executables.gif) .exe

Where EXE is the ALT value for the icon.

AddIconByType

Unlike AddIcon, which maps icons to filename patterns, AddIconByType maps an icon to one or more MIME types. MIME-type can be an exact MIME type, but it can also take wildcard expressions

As with AddIcon, an ALT tag can be added to iconfilename.

AddIconByEncoding

This directive matches an icon file to one or more MIME encoding types. Stronghold uses the AddEncoding directive to determine each file's encoding type based on its filename suffix, then uses this directive to place the specified icon next to the filename in the directory index.

DefaultIcon

If Stronghold finds no icon specified for a file in the previous directives, it uses the icon specified by DefaultIcon.

HeaderName

You can place text and images at the top of a directory index by specifying a filename using the Header name directive. Whenever Stronghold generates a directory index for a directory controlled by this directive, it inserts the HTML contained in filename at the top of the generated file.

ReadmeName

ReadmeName is just like headerName, except that Stronghold places the HTML contained in filename at the bottom of the generated directory index as a footer.

IndexOrderDefault

The IndexOrderDefault directive is used in combination with the FancyIndexing index option. By default, FancyIndexed directory listings are displayed in ascending order by filename; the IndexOrderDefault allows you to change this initial display order.

IndexOrderDefault takes two arguments. The first must be either Ascending or Descending, indicating the direction of the sort. The second argument must be one of the keywords Name, Date, Size, or Description, and identifies the primary key. The secondary key is always the ascending filename.

You can force a directory listing to only be displayed in a particular order by combining this directive with the "SuppressColumnSorting" index option; this will prevent the client from requesting the directory listing in a different order.

IndexIgnore

IndexIgnore specifies one or more regular expressions that Stronghold uses to filter out certain files when generating a directory index. For example, it's usually a good idea to exclude files that begin with a "." by entering:

INDEXIGNORE ^\.

Use this directive carefully, as it affects which files users can access in the absence of a DirectoryIndex file.

AddDescription

When FancyIndexing is set, generated directory include a Description column. AddDescription provides a description for one or more filenames or suffixes, such as

AddDescription"Chicago, 1968" /images/convention.gif AddDescription "MEPG Movie File" .mpeg .mpg

AddAlt

AddAlt specifies alternative descriptive text for one of more filenames or suffixes, which can include wildcard strings. If no AddDescription text exists for a file, the AddAlt text is used in the Description column of the directory index, assuming FancyIndexing is on.

AddAltByType

Similar to AddAlt, AddAltByType matches alternative descriptive text to one or more MIME types. Stronghold inserts this text into the Description column of the directory indexes for files of the given types, except those that already have an AddDescription or AddAlt value.

AddAltByEncoding

AddAltByEncoding matches alternative descriptive text to one or more encoding types. Stronghold inserts this text into the Description column of directory indexes for files of the given types, except those that already have an AddDescription value.

IndexOptions

IndexOptions is a comprehensive directory indexing directive that can take one or more of the following options:

URL Spell-Checking

When all other modules fail to fulfil a request, Stronghold passes it to mod_speling. This is a URL spell-checking module that compares the names of the requested directory or file to existing directories and files. The comparison is case-insensitive and allows up to one extraneous character, omitted character, or character transposition. If no matching document is found, the request fails with a status code of " 404 Not Found." If exactly one matching document is found, it is returned to the client with a redirection response. If more than one match is found, a list of matches is returned to the client with a status code of " 300 Multiple Choices."

CheckSpelling

This directive enables or disables the URL spell-checking module. When mod_speling is enabled, keep these points in mind:

• The directory scan which is necessary for the spelling correction can impact the server's performance when many spelling corrections are being performed at the same time.
• The document trees should not contain sensitive files which could be accidentally matched by a spelling correction.
• The module is unable to correct misspelled usernames (as in http://www.host.com/~moniac/ for http://www.host.com/~monica/). It can only correct filenames and directory names.

File Handling and Preprocessing

Files are handled on the basis of their filenames, which are in turn mapped to MIME types, encoding types, and handlers. Stronghold expects each filename to follow this syntax:

filename.type.language.encoding

For example,

• URLRewriting

Filetypes

Stronghold determines the MIME type of each requested file based on a mapping of MIME types to filename extensions.

MimeMagicFile

The mod_mime_magic module is enabled when the MimeMagicFile directive is present. By default, this directive is not included; add it to httpd.conf to enable mod_mime_magic. A default magic MIME file is located at conf/magic. Virtual hosts use the same file as the main server unless they are given their own MimeMagicFile directives.

TypesConfig

TypesConfig sets the path to the file that maps MIME types to filename suffixes. By default, it is set to mime.types in the <ServerRoot> directory. You can edit the mime.types file to add new or custom MIME types, or you can use the AddType directive.

AddType

With AddType, you can map MIME types to filename suffixes without editing the mime.types file.

ForceType

ForceType forces Stronghold to treat a file or files as the specified MIME type, regardless of their filenames.

AddEncoding

AddEncoding matches filename suffixes to encoding types. When Stronghold sends an encoded file to a client, it includes a Content-Encoding header that gives the encoding type based on the filename's suffix. The client can then determine the type of
pre-processing required to decode the file for the user.

AddLanguage

When a client requests a document, it should include the Accept-Language field in its request. The value is a two-letter abbreviation such as en, it, fr, or jp. AddLanguage maps these languages types to filename suffixes. For example, if you have files named readme.html.fr and readme.html.jp, Stronghold knows which one to send to a French client and which to send to a Japanese client when each sends a request for readme.html.

DefaultType

There will be times when the server is asked to provide a document whose type cannot be determined by its MIME type mappings. The server must inform the client of the content-type of the document, so in the event of an unknown type it uses the DefaultType. For example,

DefaultType image/gif

DefaultLanguage

The DefaultLanguage directive tells Apache that all files in the directive's scope (e.g., all files covered by the current <Directory> container) that don't have an explicit language extension (such as .fr or.de as configured by AddLanguage) should be considered to be in the specified MIME-lang language. This allows entire directories to be marked as containing Dutch content, for instance, without having to rename each file. Note that unlike using extensions to specify languages, DefaultLanguage can only specify a single language.

If no DefaultLanguage directive is in force, and a file does not have any language extensions as configured by AddLanguage, then that file will be considered to have no language attribute.

Metainformation

Metainformation refers to information about information. In the context of a Web server, metainformation takes the form of content digests or HTTP headers. A complete list of HTTP/1.1 headers appears in Appendix B Server Status Codes.

ContentDigest

When ContentDigest is set to "yes," Stronghold sends a Content-MD5 digest header with each response. Clients can use the header to check the integrity of the files they receive.

MetaFiles

MetaFiles enables and disables metafile processing on a per-directory basis.

MetaDir

This directive specified the name of the directory in which Stronghold can find meta information files. The directory is usually a "hidden" subdirectory of the directory that contains the file being access Set to "." to instruct the server to look in the directory that contains the requested file.

MetaSuffix

Specifies the filename suffix for the meta information file. For example, the default values for the two directives will cause a request to DOCUMENT_ROOT/somedir/index.html to look in DOCUMRNT_ROOT/somedir/.Web/index.htm;.meta and will use its contents to generate additional HTTP header information.

ExpiresActive

This directive enables and disables generation of the Expires HTTP header for an object. If it is set to "off," Stronghold generates no Expires header. If it is set to "on," Stronghold uses the criteria set to ExpiresByType and ExpiresDefault to gentrate Expires headers.

ExpiresByType

When ExpiresActive is set to "on," ExpiresByType sets the content of the Expires header by MIME type. CODE sets the time on which the enquiry period is based, and must be one of the following:

• "M" indicates that the document expires n seconds after its last modification time.
• "A" indicates that the document expires n seconds after the client requests it.

EpiresByType image/jpeg A2592000
ExpiresByType text/html M604800

In the first instance, all JPEG files expire after one month in the client's cache. Note that if the client's cache is short-lived or the client downloads the file again, the expiry period is reset. In the second instance, all HTML files expire one week after they were last modified, regardless.

ExpiresDefault

When ExpiresActive is set to "on," ExpiresDefault sets the default content of the Expires header for all documents. ExpiresByDefault overrides ExpiresDefault for files that match the given MIME type. CODE sets the time on which the expiry period is based, and must be one of the following:

• "M" indicates that the document expires n seconds after its last modification time.
• "A" indicates that the document expires n seconds after the client requests it.

Header

This directive can replace, merge, or remove HTTP response headers. The action it performs is determined by the first argument, which can have one of the following values:

The second value, header, is the name of the HTTP header, with or without the final colon. Value is the value of the given header.

The header directives are processed in the following order:

• server
• virtual host
• <Directory> containers and .htaccess files
• <Location> containers
• <Files> containers

header append Author "John P. Doe" Header unset Author

In this example, the Author header is not set. However, if the two are reversed, the Author header is set to "John P. Doe."

The header directives are processed just before the response is sent by their handlers. This means that some headers that are added just before the response is sent-- including the Date and Server headers--cannot be unset or overridden.

ServerTokens

This directive controls whether the Server header which is returned to clients includes a description of the generic OS-type of the server as well as information about compiled-in modules. The valid values are as follows

This setting applies to the entire server, and cannot be enabled or disabled on a host-by-host basis.

Handlers

AddHandlers

This directive matches handlers to filename suffix and is often used in conjunction with Action. Handler-name can be the name of an existing handler or one that you create using the Stronghold API. For example, you can use Stronghold's as-is module by uncommenting this line in http.conf.

AddHandler send-as-is asis

RemoveHandler

The RemoveHandler directive removes any handler associations for files with the given extensions. This allows .htaccess files in subdirectories to undo any associations inherited from parent directories or the server config files. An example of its use might be:

/foo/.htaccess:
AddHandler server-parsed .html
/foo/bar/.htaccess:
RemoveHandler .html

SetHandler

SetHandler specifies a handler to be used for all files in a directory or location. There is one. These are the built-in values for handler:

Handler can also be a third-party or custom handler that you add with AddHandler.

Action

Action maps handlers or media types to the CGI scripts that process them. For example, if you do not want to use Stronghold's internal imagemap feature, you could include

Addhandler imap-file .map Action imap-fule /cgi-bin/imap.cgi

Script

The Script directive defines a request method (such as GET, PUT, or POST) and a default CGI script for that method. When a client requests and object that carries this directive, and not other handling is defined for that object, Stronghold passes the PATH_INFO and PATH_TRANSLTED environment variables. For example, you can use this directive with the PUT method to allow Navigator Gold users to publish their Web files on your server.

URL Rewriting

RewriteEngine

This directive enables or disables the rewrite module for an object, a host, or the server. If you configure mod_rewrite for an object and later change your mind, set this directive to "off" rather than commenting out the rewrite directives.

RewriteLog

RewriteLogLevel

This directive sets the verbosity level of the rewrite log file, from 0 to 9. The value 0 is completely silent; use it to disable the log. The value 9 is the most verbose, but keep in mind that any value higher than 2 slows the Stronghold server substantially.

RewriteLock

This directive sets the filename for a synchronization lockfile which mod_rewrite needs to communicate with RewriteMap programs. Set this lockfile to a local path (not on a NFS-mounted device) when you want to use a rewriting program. It is not required for SAMP using all other types of rewriting maps.

RewriteOptions

This directive sets special options for the rewrite configuration. Currently, there is only one option. "Inherit" forces an object to inherit the rewrite configuration of its parent. In the context of a .htaccess file, this means that the directory inherits the configuration in its parent's .htaccess file.

RewriteBase

This directive sets a base URL that mod_rewrite prepends to the result of a rewrite operation

RewriteMap

This directive defines a separate file that contains a rewriting map. Mapname is a name used to denote the map file in the rule substitution strings of other directives. A format indicator is separated from the filename by a colon and must be one of the following

RewriteCond

RewriteCond defines a rule condition and always precedes a RewriteRule directive. The rule given RewriteRule applies only if the conditions given in RewriteCond are met. The rewrite module evaluates the test-string and matches it against condition-pattern. If they match, it applies the rule given in RewriteRule.

Test-string contains one or more of the following server variables:

HTTP_USER_AGENT
HTTP_REFERER
HTTP_FORWARDED
HTTP_HOST
HTTP_PROXY_CONNECTION
HTTP_ACCEPT
REMOTE_ADDR
REMOTE_HOST
REMOTE_USER
REMOTE_IDENT
REQUEST_METHOD
SCRIPT_FILENAME
PATH_INFO
QUERY_STRING
AUTH_TYPE
DOCUMENT_ROOT
SERVER_ADMIN
SERVER_NAME
SERVER_PORT
SERVER_PROTOCOL
SERVER_SOFTWARE
SERVER_VERSION
TIME_YEAR
TIME_MON
TIME_DAY
TIME_HOUR
TIME_MIN
TIME_SEC
TIME_WDAY
API_VERSION
THE_REQUEST
REQUEST_URI
REQUEST_FILENAME
IS_SUBREQ

Any of these flags can also be prepended by and exclamation mark (!).
Condition-pattern can also be appended by a comma-separated, bracketed list of one of the following flags:

For example:

RewriteCond $(REMOTE_HOST) ^host1.* [or]
RewriteCond
${REMOTE_HOST) ^host2.* [or]
$(REMOTE_HOST) ^host3.*

RewriteRule

RewriteRule defines the actual rules used to rewrite requested URLs that match conditions defined by RewriteCond. It can be used more than once, and multiple instances are evaluated in the order in which they appear.

Pattern is a POSIX regular expression that mod_rewrite applies to the current URL, whether it is the originally requested URL or a URL that has already been transformed by previous instances of RewriteRule. It may be prepended by an exclamation mark (!) to indicate a non-matching pattern, but a non-matching pattern cannot contain grouped wildcards. Substitute is the string that mod_rewrite substitutes for any URL that matches the pattern. it can consist of:

• plain text
• pattern-group back-references ($N)
• server variables (%{VARIABLE})
• rewrite-map calls (${mapname:key|default}) to files defined by RewriteMap

Content Delivery

Content delivery refers to the way Stronghold manipulates and delivers your site's content, the media that end users experience. This section lists directives that control client request security and several forms of content delivery:

• Content Negotiation
• Session Tracking
• Imagemaps
• Server-Side Includes
• PHP/FI 3.0 Embedded Scripting

Client Request Security

By flooding a server with useless requests, a client can create a denial-of-service attack. These directives help prevent this type of attack by limiting the amount of data that the server accepts in any single client request.

LimitRequestBody

The LimitRequestBody directive sets the maximum size of the message body of a client request, in bytes. A request that includes a message body larger than n bytes is discarded, and Stronghold responds with status code 413 Request Entity Too Large. N must be an integer between 0 (meaning unlimited) and 2147483647 (2GB).

LimitRequestFields

The LimitRequestFields directive sets the maximum number of request header fields allowed in any single request. If a request includes more than n headers, the request is discarded and Stronghold responds with status code 400 Bad Request. N must be an integer between 0 (meaning unlimited) and 32767. If this directive is not present, the default is 100 bytes.

LimitRequestFieldSize

The LimitRequestFieldSize directive sets the maximum size for all request headers, in bytes. If a request includes a header field larger than n bytes, the request is discarded and Stronghold responds with status code 400 Bad Request. "n" must be an integer between 0 (meaning unlimited) and the value of the compile-time constant DEFAULT_LIMIT_REQUEST_FIELDSIZE. The default value of this constant is 8190.

LimitRequestLine

The LimitRequestLine directive sets the maximum size of the first line of any request, in bytes. The first line consists of an HTTP request method, a URI, and the HTTP version. For example:

GET /index.html HTTP/1.1

If this line is larger than n bytes, the request is discarded and Stronghold responds with status code 414 Request-URI Too Long. n must be an integer between 0 (meaning unlimited) and value of the compile-time constant DEFAULT_LIMIT_REQUEST_LINE. The default value of this constant is 8190.

Content Negotiation

In any document request, most clients have the ability to specify what kinds of files they can accept. When a server such as Stronghold uses this information to provide the most appropriate format for the client, this is called content-negotiation. With this feature, you can build a flexible, intelligent site. However, content negotiation does entail considerable content management work, since separate versions of the same material must be organized and maintained. "Content Negotiation" on page 9-6 provides a more details discussion of how content negotiation works.

CachNegotiatedDocs

Normally Stronghold does not cache content-negotiated documents. Including this directive allows it to cache them when acting as a proxy server.

LanguagePriority

If a client does not send an Accept-language header in its request, Stronghold uses this directive to determine which order it should use in trying different language versions of the same file. For example, if this directive is set to:

LanguagePriority en fr jp it

then Stronghold will first offer an English version of the file. If the client rejects this version, the server will try French, and so on.

Session Tracking

The mod_usertrack modules uses Netscape cookies to track sessions. The directives in this section enable tracking and set cookie expiration times. For more information about session tracking, see "Tracking Sessions" on page 1-17

CookieTracking

CookieTracking enables or disables session tracking for an object or host, or for the whole server.

CookieExpires

By default, cookies are valid only for the current session. The CookieExpires directive sets a different expiration period. Expiry-period is either an integer representing a number of seconds for which a cookie is valid, or a quoted string consisting of integers and one or more of the following units:

• years
• months
• weeks
• days
• hours
• minutes
• seconds

CookieExpires "6 months 2 weeks 7 hours"

Imagemaps

Stronghold handles imagemaps internally, without the aid of CGI programs. For details information about the imagemap module, see "Server-Side Imagemaps" on page 9-2

ImapMenu

If a user clicks a point on an imagemap that does not match any valid coordinates in the imagemap file, Stronghold can generate a menu of the links contained in the imagemap. This menu has four formatting options:

ImapDefault

ImapDefault specifies the action Stronghold takes if:

• the point clicked by the user matches no valid coordinates and
• ImapMenu is set to "none" and
• there is not default directive in the imagemap file itself.

ImapBase

ImapBase sets the base URL for al relative paths in imagemap files. A base directive in an imagemap file overrides ImapBase.

The value can be a URL, or one of the following options:

• "map": The URL, of the imagemap file is the base URL.
• "referer": The URl of the referring document is the base URL.

Server-Side Includes

Server-side includes (SSIs) are simple, HTML-embedded commands that the server parses before it delivers the HTML file. SSIs are explained in detail in "Server-Side Includes" on page 9-7

XBitHack

This directive is used with file permissions to indicate which files have server-side includes. Stronghold uses this directive to determine which files to parse before delivery. The values are as follows:

PHP/FI 3.0 Embedded Scripting

The PHP module performs HTML-embedded scripting for dynamic content. you can place PHP configuration directives in httpd.conf and in .htaccess files. If you use PHP, be sure to use the AddType directive to include PHP files. Chapter 3 "Tutorial: Access control" explains PHP in detail.

phpShowInfo

When this directive is turned on, access information footers are added to each PHP-parsed file.

phpLastModified

Since PHP pages are dynamic, they are processed and sent to the browser each time you access them. However, if your source pages do not change, you may want to avoid the server overhead of page regeneration and reloading. If phpLastModified is turned on, Stronghold sends the Last-Modified header to the browser so that the page is only reloaded when it changes.

phpLogging

Context: object
Module: mod_php
AllowOverride: FileInfo

When this directive is turned on, Stronghold logs PHP activity.

phpDebug

This directive toggles the automatic fileinfo debugging screen on or off. The default is off.

phpUploadTmpDir

This directive sets the temporary directory for user-upload files.

phpDbmLogDir

This directive sets the directory for DBM log files that record (H) activity, assuming phpLogging is turned on.

phpSQLLogHost

This directive sets the hostname where PHP can find the SQL logging database.

phpSQLLogDB

This directive sets the name of the SQL logging database.

phpMsqlLoghost

This directive sets the hostname where PHP can find the mSQL logging database.

phpMsqlLogDB

This directive sets the name of the mSQL logging database.

phpAccessDir

This directive sets the directory for PHP access control files.

phpmaxDataSpace

This directive sets the maximum size, in kilobytes, of a sub-pool in the PHP module.

phpIncludePath

This is a colon-separated list of absolute paths to directories where PHP can find files when implementing its include() function.

phpAutoPrependFile

The file specified by phpAutoPrependFile is parsed before the requested file using PHP's include function. phpIncludePath applies. keep in mind that an auto-prepended file makes it difficult for you t used the header function in the requested file.

phpAutoAppendFile

Similar to phpAutoPrependFile, this directive specifies the name of a file to parse after the requested PHP file has been parsed.

phpAdaDefDB

This is the AdBase database

phpAdaUser

This is the default Adabas database user.

phpAdaPW

This is the default Adabas database password.

phpEngine

This directive turns PHP parsing on or off. The default is on and this directive is only useful if you want to set to "FileInfo" and still disallow PHP parsing.

phpXBithack

When php XBitHack is set to "on," the PHP module parses all files with the user-execute bit set, even if they do not have the .php filename extension.

Client Authentication and Access Control

Stronghold Web Server 3.0 comes with a variety of client authentication and access control options. SSL certificates provide the most reliable means of accomplishing both, but other options are also useful for low-security applications or in tandem with SSL. These directives configure

• Authentication Mode
• Basic Authentication
• Berkeley Database Authentication
• Database Manager Authentication
• Digest Authentication
• Host-Based Access Control
• Anonymous Logins

Authentication Mode

This directive sets the authentication mode. The other authentication directives that you use depend on how this directive is set.

AuthType

This directive activates basic, digest, or certificate authentication for a directory. In order to work, it must be accompanied by AuthName and Require, plus AuthUserFile if the value is "basic." Basic authentication uses only a user ID and password, and digest authentication encrypts both the user ID and password for added security. Certificate authentication uses SSL client certificates.

Basic Authentication

Basic authentication uses text files to authenticate users with simple logins and passwords. Users can be grouped for access control purposes.

AuthName

This directive sets the name of the authorization realm for a directory. This realm is given to the client so that the user knows which certificate or username and password to send. It must be accompanied by AuthType and Require directives, and either AuthUserFile or AuthGroupFile.

Require

This directive selects which authenticated users can access an object. The allowed values are

If Require appears in a <Limit> container, then it restricts access to the named methods. If Require appears in a <LimitExcept> then it restricts access to all methods except those named. Otherwise it restricts access for all methods. Require must be accompanied by AuthName and AuthType directives and directives such as AuthUserFile and AuthGroupFile (to define users and groups) in order to work correctly. For example:

AuthType Basic
AuthName somedomain
AuthUserFile /web/users
AuthGroupFile /web/groups
require group admin

AuthGroupFile

AuthGroupFile specifies the filename that contains the list of authentication groups and the users they include.

AuthUserFile

AuthUserFile specifies the filename that contains the list of authenticated users and their crypt()-encrypted passwords.

AuthAuthoritive

Setting the AuthAuthoritive directive to "off," allows authentication and authorization to be passes to lower level modules If there is no user ID or rule matching the supplied user ID. If there is a user ID and/or rule specified, the usual password and access checks are applied and a failure gives 401 Unauthorized reply.

If a userID appears in the database of more than one module, or if a valid require directive applies to more than one module, then the first module verifies the credentials and no access is passed on, regardless of the AuthAuthoritive setting. A common use for this is in conjunction with one of the database modules, such as mod_auth_db, mod_auth_dbm, and mod_auth_anon. These modules supply the bulk of the user credential checking, but a few (administrator) related accesses fall through to a lower level with a well-protected AuthUserFile. By default, AuthAuthoriatative is set to "on," and an unknown user ID or rule results in a 40 Unauthorized reply. Setting it to "off," keeps the system secure and forces NSCA-compliant behavior.

Be sure to consider the implications of allowing a user to permit fall-through in and .htaccess file and verify that this is really what you want. Generally, it is easier to just secure a single.htpassword file than it is to secure a database. Make sure that the AuthUserFile is stored outside the DocumentRoot, do not put it in the directory that it protects. Otherwise, clients will be able to download the AuthUserFile.

Berkeley Database Authentication

These directives control user authentication and access control with Berkeley database files. The Berkeley database library is distributed at http//:www.sleepycat.com/

AuthDBGroupFile

The AuthDBGroupFile directive sets the name of a DB file containing the list of user groups for user authentication. Filename is the absolute path to the file.

The group file is keyed on the username. The value for a user is a comma-separated list of the groups to which the user belongs. The value cannot contain spaces or colons.

AuthDBUserFile

The AuthBDUserFile directive sets the name of the DB file containing the list of user and passwords for user authentication. Filename is the absolute path to the user file.
The user file is keyed on username.The value for a user is a password encrypted with Crypt(), optionally followed by a colon and arbitrary data. The colon and data that follow it will be ignored. by the server.

AuthDBAthoritative

If more than one authentication method is configured for the same object, including DB authentication, then AuthSBAthoritative sets whether DB is the authoritative authentication method. By default, Stronghold executes authentication methods in the reverse order of the <ServerRoot>/scr/Configuration module list

Use this directive to override this behavior. For Example, if AuthDBAuthoritative is set to "no" and authentication fails, then Stronghold attempts authentication using the method implemented by the next highest authentication module in the Configuration list. If it is set to "yes" and authentication fails, Stronghold ends the authentication process and returns a status code of 403 (forbidden).

Database Manager Authentication

These directives control user authentication and access control using a database manager (DBM).

AuthDBMGroupFile

The AuthDBMGroupFile directive sets the name of a DBM file containing the list of user groups for user authentication. Filename is the absolute path to the group file.

The group file is keyed on the username. The value for a user is a comma-separated list of the groups to which the user belongs. The value cannot include spaces or colons.

AuthDBMuserFile

The AuthDBMuserFile directive sets the name of a DBM file containing the list of users and passwords for user authentication. Filename is the absolute path to the user file.

The user file is keyed on the username. The value for a user is a password encrypted with crypt(), optionally followed by a colon and arbitrary data. The colon and the data following it will be ignored by the server.

AuthDBMAuthoritative

If more than one authentication method is configured for the same object, including DBM authentication, then AuthDBMAuthoritative sets whether DBM is the authoritative authentication method. By default, Stronghold executes authentication methods in the recers order of the ServerRood/scr/Configuration module list. Use this directive to override this behavior.

For example, if AuthDBMAuthoritative is set to "no" and authentication fails, then Stronghold attempts authentication using the method implemented by the next highest authentication module in the Configuration list. If it is set to "yes" and authentication fails, Stronghold ends the authentication process and returns a status code of 403 (forbidden).

Digest Authentication

These directives perform MD5 digest authentication. When AuthType is set to "digest". Stronghold uses the AuthDigestFile for authentication. Digest authentication provides a more secure password system, but only works with supporting browsers.

AuthDigestFile

When AuthType is set to Digest, AuthDigestFile sets the text file containing the list of user ID/password checksums for digest authentication. Filename is the absolute path to that file. The digest file uses a special format and can be created using the <ServerRoot>/bin/ht/digest utility.

SSL Certificate Authentication and Access Control

When AuthType is set to "cert," Stronghold performs SSL certificate authentication based on the parameters specified by these directives. Client authentication is discussed in detail in Chapter 2, "Authentication and Encryption.".

SSLCACertificatePath

This directive sets the directory where you keep the Certificates of Certification Authorities (CAs) whose clients you deal with. These are used to verify the client certificate on Client Authentication.

The files in this directory have to be PEM-encoded and are accessed through hash filenames. So usually you can't just place the Certificate files there: you also have to create symbolic links named hash-value.N. And you should always make sure this directory contains the appropriate symbolic links.

Use the Makefile which comes with mod_ssl to accomplish this task.

Example:

SSLCACertificatePath /usr/local/apache/conf/ssl.crt/

SSLCACertificatFile

This directive sets the all-in-one file where you can assemble the Certificates of Certification Authorities (CA) whose clients you deal with. These are used for Client Authentication. Such a file is simply the concatenation of the various PEM-encoded Certificate files, in order of preference. This can be used alternatively and/or additionally to SSLCACertificatePath.

Example:

SSLCACertificateFile /usr/local/apache/conf/ssl.crt/ca-bundle-client.crt

SSLVerifyClient

This directive sets the Certificate verification level for the Client Authentication. Notice that this directive can be used both in per-server and per-directory context. In per-server context it applies to the client authentication process used in the standard SSL handshake when a connection is established. In per-directory context it forces a SSL renegotation with the reconfigured client verification level after the HTTP request was read but before the HTTP response is sent.

The following levels are available for level:

• none: no client Certificate is required at all
• optional: the client may present a valid Certificate
• require: the client has to present a valid Certificate
• optional_no_ca: the client may present a valid Certificate but it need not to be (successfully) verifiable.

Example:

SSLVerifyClient require

SSLVerifyDepth

Syntax: SSLVerifyDepth number
Context: server config, virtual host, directory, .htaccess
Module: mod_ssl
Default: SSLVerifyDepth 1
<>AllowOverride: AuthConfig

This directive sets how deeply mod_ssl should verify before deciding that the clients don't have a valid certificate. Notice that this directive can be used both in per-server and per-directory context. In per-server context it applies to the client authentication process used in the standard SSL handshake when a connection is established. In per-directory context it forces a SSL renegotation with the reconfigured client verification depth after the HTTP request was read but before the HTTP response is sent.

The depth actually is the maximum number of intermediate certificate issuers, i.e. the number of CA certificates which are max allowed to be followed while verifying the client certificate. A depth of 0 means that self-signed client certificates are accepted only, the default depth of 1 means the client certificate can be self-signed or has to be signed by a CA which is directly known to the server (i.e. the CA's certificate is under SSLCACertificatePath), etc.

Example:

SSLVerifyDepth 10

SSLRequireSSL

This directive forbids access unless HTTP over SSL (i.e. HTTPS) is enabled for the current connection. This is very handy inside the SSL-enabled virtual host or directories for defending against configuration errors that expose stuff that should be protected. When this directive is present all requests are denied which are not using SSL.

Example:

SSLRequireSSL

SSLRequire

This directive specifies a general access requirement which has to be fulfilled in order to allow access. It's a very powerful directive because the requirement specification is an arbitrarily complex boolean expression containing any number of access checks.

The expression must match the following syntax (given as a BNF grammar notation):

expr ::= "true" | "false"
| "!" expr
| expr "&&" expr
| expr "||" expr
| "(" expr ")"
| comp
comp ::= word "==" word | word "eq" word
| word "!=" word | word "ne" word
| word "<" word | word "lt" word
| word "<=" word | word "le" word
| word ">" word | word "gt" word
| word ">=" word | word "ge" wordly decided that
| word "in" "{" wordlist "}"
| word "=~" regex
| word "!~" regex
wordlist ::= word
| wordlist "," word
word ::= digit
| cstring
| variable
| function
digit ::= [0-9]+
cstring ::= "..."
variable ::= "%{" varname "}"
function ::= funcname "(" funcargs ")"

While for varname any variable from Table 3 can be used. Finally for funcname the following functions are available:

• file( filename)
  This function takes one string argument and expands to the contents of the file. This is especially useful for matching this contents against a regular expression, etc.

Example:

SSLRequire ( %{SSL_CIPHER} !~ m/^(EXP|NULL)-/ \
and %{SSL_CLIENT_S_DN_O} eq "Snake Oil, Ltd." \
and %{SSL_CLIENT_S_DN_OU} in {"Staff", "CA", "Dev"} \
and %{TIME_WDAY} >= 1 and %{TIME_WDAY} <= 5 \
and %{TIME_HOUR} >= 8 and %{TIME_HOUR} <= 20 ) \
or %{REMOTE_ADDR} =~ m/^192\.76\.162\.[0-9]+$/

Standard CGI/1.0 and Apache variables:

Table 3: Available Variables for SSLRequire

SSL_Group

SSL_Group AdminGroup "ou EQ Administration"

<VirtualHost 140.233.117.80:443>
<Location />
SSL_Require AdminGroup
</Location>
</VirtualHost>

SSLFakeBasicAuth

SSLFakeBasicAuth is not recommended.

Host-Based Access Control

In many cases, you may want to allow only certain hosts to access your hosts, directories, or files. The mod_access modules allow you to control access based on IP address and hostnames, as well as environment variables. For example:

BrowserMatch ^KnockKnock/2.0 let_me_in
<Directory /docroot>
order deny,allow
deny from all
allow from env=let_me_in
</Directory>

In this example, all browsers with the User-Agent string "KnockKnock/2.0" are allowed access, and all others are denied.

Host-based access control is not as reliable as certificate authentication, because hackers can "spoof" hosts, pretending to send requests from one of the hosts you allow. However, we do recommend you use these directives to control access to server status and configuration information, like this:

<Location /Stronghold-status>
order deny, allow
deny from all
allow from Yourhost.com
<Location>

<Location /Stronghold-info>
order deny, allow
deny from all
allow from yourhost.com
<Location>

With this configuration, only users on your host can access server information.

order

Order, used in conjuction with allow and deny, provides host-based access control The value is a coma-separated list that indicates which directive takes priority. The one that does not have priority usually takes the value "all." for example,

order allow,deny

allows access from a few hosts and deny access from all other hosts. If you enter

order deny,allow

then you can deny access from a few hosts and allow access from all others. The order you choose depends on the nature of your site. If the value is "mutual-failure," then access is limited to hosts that appear in the allow list and not in the deny list.

satisfy

This directive sets the access policy if both allow and Require are used. The value can be either "all" or "any."

• If the value is "all," then authentication succeeds only if both allow and Require succeed.
• If the value is "any," then authentication succeeds if either allow or Require succeed.