Once you've installed Stronghold Web Server, you can configure it to suit your unique site. This chapter provides a quick reference to all configuration directives for the core server, its precompiled modules, and its optional modules. The directives control different aspects of server behavior, including

• general configuration
  
  
• performance tuning
  
  
• proxy service and caching
  
  
• logging
  
  
• the directory tree
  
  
• file handling and preprocessing
  
  
• content delivery
  
  
• client authentication and access control
  
  
• server authentication
  
  
• encryption
  
  
• Sioux-compatible directives
  
  

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

• syntax
  
  
• context
  
  
• module
  
  

  This is the module that facilitates the directive's functionality.

• default value (where applicable)
  
  
• AllowOverride value (where applicable)
  
  

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

• brief description
  
  

For each directive, the Context field gives one of three possible contexts, each denoting a level in the configuration hierarchy:

Context	Description
server	Server directives apply to the site in general and must appear outside containers.
host	Host directives can appear within <VirtualHost> containers or in the general server configuration.
object	Object directives can appear within <Directory>, <Location>, <File>, or <Limit> containers, as well as .htaccess files. They can also appear in <VirtualHost> containers or in the general server configuration.

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.

Each directive listing also specifies the module controlled by that directive. 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.

The following directives are new in version 2.4.1 of Stronghold Web Server:

• ProxyVia and AllowCONNECT on page 7-35
  
  
• ExtendedStatus on page 7-45
  
  
• LimitRequestBody, LimitRequestFields, LimitRequestFieldSize, and LimitRequestLine on page 7-78
  
  

Stronghold Web Server's general directives control the most fundamental aspects of the server and its virtual hosts. The server cannot function without these directives:

• server setup directives
  
  
• virtual hosts
  
  
• SSL setup
  
  
• .htaccess configuration
  
  
• environment variables
  
  
• FastCGI
  
  

Most server setup directives are set by the INSTALL.sh script when you install Stronghold Web Server, but you can change them at any time. They are not associated with any modules, but only with Stronghold's server core.

• Syntax: StrongholdLicenseFile licensefile|NONCOMMERCIAL
  
• Context: server
  
• Module: core
  

  This sets the license file for your Stronghold Web Server. 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*****
  TEIAAQCKAAAAAGar2a7Pc0iD2oyGDN9a5mrYkZ0NrG7Zcy7UFbFoP4xLzvcVAN4K
  0Mrww4z0A2o+gfVADbDz9IdePDKOA21C2E8SiPu1qwVI1pwvbA6xuVRWDo05BT/I
  rNGExtSx+LMh3N1q2icj4eD53kNQVoLvaoQ5CcYvWGexrKiSDQvE3agLU2VyaWFs
  OiAzMTQxNTkyNjUzNTg5NzkzMjMKQ29tcGFueTogQzJOZXQgRXVybSchmunkZApF
  eHBpcmVzOiBOZXZlcgpQcm9kdWN0OiBTSDIKVHlwZfogRXZhbHVhdGlvbgpJREVB
  OiBZZXMKRmFrZTogCkJyb2tlbiBMaW5lCkJyb2tlbjogMQ==
  *****END LICENSE BLOCK*****
  
  

  The license block must be present in order to run the server. If you are using a noncommercial version of Stronghold, set this directive to "NONCOMMERCIAL." If you are using an evaluation copy of Stronghold, your license block expires when the evaluation period ends.

• Syntax: DocumentRoot directory
  
• Context: host
  
• Module: core
  
• Default: DocumentRoot /usr/local/etc/httpd/htdocs
  

  This directive sets the directory from which Stronghold Web Server serves files. Unless matched by a directive like Alias, the server appends the path from the requested URL to the document root to make the path to the document. For example, if

  DocumentRoot /usr/web
  
  

  is specified, then an access to http://www.my.host.com/index.html refers to /usr/web/index.html.

• Syntax: ErrorDocument errorcode filename|"errormessage"|URL
  
• Context: object
  
• Module: core
  
• AllowOverride: FileInfo
  

  ErrorDocument controls Stronghold Web Server's behavior 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
    
    

    Stronghold sometimes offers additional information regarding the problem or error. This can be embedded into the message using percentage signs (%).

  • the URL of an error message file or CGI program
    
    

    URLs begin with a slash (/) for local URLs, or a full URL which the client can resolve. Examples:

    ErrorDocument 500 /cgi-bin/tester
    ErrorDocument 404 /cgi-bin/bad_urls.pl
    ErrorDocument 403 "Sorry can't allow you access today"
    
    

  For a complete list of error codes and their meanings, see "Server Errors" on page B-6.

• Syntax: Listen [IP:]port
  
• Context: server
  
• Module: core
  

  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.

  For virtual hosts, use the Port directive.

• Syntax: Port n
  
• Context: host
  
• Module: core
  
• Default: Port 80
  

  The Port directive assigns a port number to a host. Each <VirtualHost> container must include this directive. N is an integer from 0 to 65535; some port numbers (especially below 1024) are reserved for particular protocols. See /etc/services for a list of some defined ports; the standard port for the HTTP protocol is 80. For SSL, the standard port is 443.

• Syntax: User userid
  
• Context: server
  
• Module: core
  
• Default: nobody
  

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

  • username: Refers to the given user by name.
    
    
  • # user-number: Refers to a user by his or her number.
    
    

  The user should have no privileges that result in him or her being able to access files that are not intended to be visible to the outside world; similarly, the user should not be able to execute code that is not meant for HTTPD requests. It is recommended that you set up a new user and group specifically for running the server. Some administrators use user "nobody," but this is not always possible or desirable.

  If you start the server as 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 you do start the server as root, then it is normal for the parent process to remain running as root.

  NOTE:

  Do not set User (or Group) to root unless you know exactly what you are doing and what the dangers are.

  
  

• Syntax: Group UNIX-group
  
• Context: server
  
• Module: core
  
• Default: Group nobody
  

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

  • A group name: Refers to the given group by name.
    
    
  • # groupnumber: Refers to a group by its number.
    
    

  We recommend that you set up a new group specifically for running the server.

  NOTE:

  If you start the server as a non-root user, it will fail to change to the specified group and will instead continue to run as the group of the original user.

  
  

• Syntax: Options option1 [option2 . . . ]
  
• Context: object
  
• Module: core
  
• AllowOverride: Options
  

  The Options directive controls which server features are available in a particular directory. Options can be set to one or more of the following:

  Option	Description
  None	No options.
  All	All options except for MultiViews. This value is not recommended.
  ExecCGI	Execution of CGI scripts is permitted.
  FollowSymLinks	The server follows symbolic links in this directory.
  Includes	Server-side includes are permitted.
  IncludesNOEXEC	Server-side includes are permitted, but the #exec command and #include of CGI scripts are disabled. We highly recommend this option as a security measure.
  Indexes	If a URL that maps to a directory is requested, and the there is no DirectoryIndex (for example, index.html) in that directory, then the server will return a formatted listing of the directory.
  MultiViews	Content-negotiated MultiViews are allowed. For details about using content negotiation, see "Content Negotiation" on page 9-4.
  SymLinksIfOwnerMatch	The server will only follow symbolic links for which the target file or directory is owned by the same user ID as the link.

  Any option can be prepended by a plus or minus sign (+ or -). For example, if you want a virtual host to have a set of options that differs from that of the main host, you do not need to create a new list of options. Simply add or detract 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 Indexes FollowSymLinks
  </Directory>
  <Directory /web/docs/spec>
  Options Includes
  </Directory>
  
  

  In this example, only "Includes" is set for the /web/docs/spec directory.

• Syntax: ServerAdmin email-address
  
• Context: host
  
• Module: core
  

  The ServerAdmin directive sets the email address that the server includes in any error messages it returns to the client.

  It may be worth setting up a dedicated address for this, for example,

  ServerAdmin www-admin@foo.bar.com
  
  

  as users do not always mention that they are talking about the server.

• Syntax: ServerRoot path
  
• Context: server
  
• Module: core
  
• Default: ServerRoot /usr/local/etc/httpd
  

  The ServerRoot directive sets the directory in which the server binary is installed. Typically, it contains the subdirectories conf/ and logs/. Relative paths for other configuration files are taken as relative to this directory.

• Syntax: Include filename
  
• Context: object
  
• Module: core
  

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

• Syntax: ServerSignature off|on|email
  
• Context: object
  
• Module: core
  
• Default: ServerSignature Off
  

  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 host directives control basic, host-specific attributes of virtual hosts. For more information about virtual host configuration, see "Configuring Virtual Hosts" on page 6-9.

• Syntax: ServerName hostname
  
• Context: host
  
• Module: core
  

  The ServerName directive sets the hostname of the server. This directive is only used when creating redirection URLs. If it is not specified, then the server attempts to deduce it from its own IP address. However, this may not always work, or may not return the preferred hostname. For example,

  ServerName www.foo.com
  
  

  would be used if the canonical name of the actual machine were monster.foo.com.

  NOTE:

  The main server and all virtual hosts must each have the ServerName directive.

  
  

• Syntax: NameVirtualHost IP[:port]
  
• Context: server
  
• Module: core
  

  The NameVirtualHost directive is required for all name-based virtual hosts. 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, it is recommended that you always use an IP address, as follows:

  NameVirtualHost 111.22.33.44
  
  

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

  NameVirtualHost 111.22.33.44:8080
  
  

  NOTE:

  The main server and any "_default_" servers will never be served for a request to a NameVirtualHost IP Address (unless for some reason you specify NameVirtualHost but don't define any virtual hosts for that address).

  
  

  For more information about name-based virtual host configuration, see "Name-Based Virtual Hosts" on page 6-13.

• Syntax: ServerAlias host1 [host2 . . . ]
  
• Context: host
  
• Module: core
  

  The ServerAlias directive sets the alternate names for a host, for use with Host-header virtual hosts. Host can be a full hostname or a wildcard string.

• Syntax: UseCanonicalName on|off
  
• Context: object
  
• Module: core
  
• AllowOverride: AuthConfig
  

  In many situations, the server must construct self-referential URLs. A self-referential URL refers back to the server itself. When UseCanonicalName is set to "on," Stronghold uses the ServerName and Port directives to construct a canonical name for the server. This name is used in all self-referential URLs, and for the values of SERVER_NAME and SERVER_PORT in CGIs.

  When UseCanonicalName is set to "off," Stronghold forms self-referential URLs using the hostname and port supplied by the client, if any. Otherwise, it uses the canonical name. These values are the same that are used to implement name-based virtual hosts, and are available with the same clients. The CGI variables SERVER_NAME and SERVER_PORT are constructed from the client-supplied values as well.

  For example, imagine you run an intranet server that users connect to using short names such as www instead of fully-qualified domain names. If those users type a URL consisting of a short name and a directory without a trailing slash, such as http://www/splat, then Stronghold redirects them to http://www.domain.com/splat/. If authentication is enabled, this requires the user to authenticate twice-once for www and once again for www.domain.com. But if UseCanonicalName is set to "off", then Stronghold redirects to http://www/splat/ and the request fails.

  NOTE:

  Warning: If CGIs make assumptions about the values of SERVER_NAME, they may be broken by this feature. The client is free to give any value as a hostname. This should not be a problem if the CGI is only using SERVER_NAME to construct self-referential URLs.

  
  

• Syntax: ServerPath path
  
• Context: host
  
• Module: core
  

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

These directives are necessary 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-105 for the required server authentication directives.

• Syntax: SSLFlag on|off
  
• Context: host
  
• Module: mod_ssl
  

  SSLFlag, set to "on," enables SSL functionality for the server or for a host. You can also use this directive to temporarily deactivate SSL.

• Syntax: SSLProtocol protocol1 [protocol2. . . ]
  
• Context: host
  
• Module: mod_ssl
  

  SSLProtocol sets one or more security protocols used by the server or by a host. Valid values for protocol are

  • TLSv1
    
    
  • SSLv2
    
    
  • SSLv3
    
    
  • all
    
    

  As a shortcut for enabling all protocols except one, the minus sign (-) can be used with the "all" value. For example,

  SSLProtocol all -sslv2
  
  

  enables TLS version 1 and SSL version 3, but not SSL version 2.

  NOTE:

  If SSLProtocol is omitted, all protocols are enabled by default.

  
  

• Syntax: SSLRoot path
  
• Context: host
  
• Module: mod_ssl
  
• Default: SSLRoot /usr/local/ssl
  

  SSLRoot is the root directory for SSL files. SSL file directives (except logging directives) can be relative to SSLRoot.

  NOTE:

  All other paths and filenames relating to SSL must be either absolute or relative to SSLRoot.

  
  

• Syntax: SSLSessionLockFile filename
  
• Context: server
  
• Module: mod_ssl
  

  SSLSessionLockFile sets the location of the SSL session cache locking file. If it is not set, filename defaults to logs/session.lock. Normally, the default is fine and you do not need to add or change this directive. The directory where the lock file resides should not be world-writeable.

  NOTE:

  The lock file must be stored locally. If your logs/ directory is on an NFS-mounted file system, set SSLSessionLockFile to point to a local file.

  
  

Although the httpd.conf file can control all aspects of the server, some directives can also reside in per-directory configuration files, usually called .htaccess files. This configuration can be useful if you need to move directories frequently, or if you want 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-directory configuration files are enabled only when

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

This feature can be enabled globally or on a per-virtual-host basis. In this chapter, the directives that are valid in per-directory configuration files are listed with an "AllowOverride" field. This field gives the value for AllowOverride that enables the use of a particular directive in per-directory configuration files. Directives that are listed with no "AllowOverride" field are never valid in per-directory configuration files.

• Syntax: AccessFileName filename1 [filename2. . . ]
  
• Context: host
  
• Module: core
  
• Default: AccessFileName .htaccess
  

  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

  <Directory />
  AllowOverride None
  </Directory>
  

• Syntax: AllowOverride override override . . .
  
• Context: <Directory> and <Location> only
  
• Module: core
  
• Default: AllowOverride All
  

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

  AllowOverride can be set to "None," in which case the server ignores the file, "All" in which case the server will allow all the directives, or one or more of the following:

  Option	Description
  AuthConfig	Allow use of the access authorization directives: AuthDBMGroupFile, AuthDBMUserFile, AuthGroupFile, AuthName, AuthType, AuthUserFile, and require.
  FileInfo	Allow use of document-type directives: AddEncoding, AddLanguage, AddType, DefaultType, and LanguagePriority, and all PHP directives. PHP directives are listed in "PHP/FI 2.0 Embedded Scripting" on page 7-84.
  Indexes	Allow use of the directives controlling directory indexing: AddDescription, AddIcon, AddIconByEncoding, AddIconByType, DefaultIcon, DirectoryIndex, FancyIndexing, HeaderName, IndexIgnore, IndexOptions, and ReadmeName.
  Limit	Allow use of the host-based access directives: allow, deny, and order.
  Options	Allow use of the directives controlling specific directory features: Options and XBitHack.

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.

• Syntax: PassEnv variable1 [variable2 . . . ]
  
• Context: object
  
• Module: mod_env
  

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

• Syntax: SetEnv variable value
  
• Context: object
  
• Module: mod_env
  

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

  SetEnv LIBDIR /www/lib
  
  

• Syntax: SetEnvIf attribute regex envar[=value] [. . . ]
  
• Context: server
  
• Module: mod_setenvif
  

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

  HTTP Header	Description
  REMOTE_HOST	the hostname of the client making the request, if available
  REMOTE_ADDR	the IP address of the client making the request
  REMOTE_USER	the authenticated username, if available
  REQUEST_METHOD	the name of the method being used, such as GET or POST
  Request_URI	the portion of the URL following the scheme and host

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

  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 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.

• Syntax: SetEnvIfNoCase attribute regex envar[=value] [. . . ]
  
• Context: server
  
• Module: mod_setenvif
  

  SetEnvIfNoCase is semantically identical to the SetEnvIf directive, except that the regular expression matching is case-insensitive. For 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.

• Syntax: UnSetEnv variable
  
• Context: object
  
• Module: mod_env
  

  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.

• Syntax: BrowserMatch regex var1 [var2 . . . ]
  
• Context: server
  
• Module: mod_browser
  

  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 httpd.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:

  Variable String	Description
  variable	The name of an environment variable to be used with a matching client request. The default value for a named variable is 1.
  !variable	The name of an environment variable to be excluded from any matching client request.
  variable=value	Defines the value of an environment variable for any matching client request.

  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
  
  

• Syntax: BrowserMatchNoCase regex var1 [var2 . . . ]
  
• Context: server
  
• Module: mod_browser
  

  BrowserMatchNoCase is identical to BrowserMatch above, except that its arguments are case-insensitive.

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 modules
  
  

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

• Syntax: StrongholdAccelerator none|nFast
  
• Context: server
  
• Module: mod_ssl
  

  StrongholdAccelerator indicates whether the server platform has an installed nFast ecnryption accelerator. By default, it is set to "none." Set this directive to "nFast" to implement hardware encryption acceleration with nCipher's nFast technology.

  For more information about nFast, see http://www.ncipher.com.

• Syntax: ServerType type
  
• Context: server
  
• Module: core
  
• Default: ServerType standalone
  

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

  • "inetd": The server will be run 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 will run as a daemon process; the command to start the server is added to the system startup scripts. (/etc/rc.local or /etc/rc3.d/. . . .)
    
    

  "Standalone" is the most efficient setting, since the server starts once and services all subsequent connections. If you run Stronghold to serve a busy site, "standalone" is your only viable option.

• Syntax: CoreDumpDirectory directory
  
• Context: server
  
• Module: core
  
• Default: ServerRoot
  

  This controls the directory to which Stronghold attempts to switch before dumping core. The default is the ServerRoot directory. However, since this directory should not be writable by the user the server runs as, core dumps don't normally get written. If you want a core dump for debugging, use this directive to place it in a different location.

• Syntax: SendBufferSize n
  
• Context: server
  
• Module: core
  

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

• Syntax: TimeOut n
  
• Context: server
  
• Module: core
  
• Default: TimeOut 1200
  

  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 be helpful.

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, you can use Stronghold's keepalive feature to reserve an open connection for a series of requests and responses. These directives set the parameters of Stronghold's keepalive functionality.

• Syntax: KeepAlive on|off
  
• Context: server
  
• Module: core
  
• Default: KeepAlive off
  

  This directive enables and disables persistent connections.

• Syntax: MaxKeepAliveRequests n
  
• Context: server
  
• Module: core
  
• Default: MaxKeepAliveRequests 100
  

  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.

• Syntax: KeepAliveTimeout seconds
  
• Context: server
  
• Module: core
  
• Default: KeepAliveTimeout 15
  

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

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

• Syntax: ListenBacklog n
  
• Context: server
  
• Module: core
  
• Default: ListenBacklog 511
  

  This sets the maximum length of the queue of pending requests. Generally, no tuning is needed or desired. 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.

• Syntax: LockFile filename
  
• Context: server
  
• Module: core
  
• Default: LockFile logs/accept.lock
  

  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 should 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.

  NOTE:

  Avoid putting this file in a world-writable directory such as /var/tmp because someone could create a denial-of-service attack by creating a lockfile with the same name as the one the server tries to create. The server cannot start under such an attack.

  
  

  See also SSLSessionLockFile on page 7-13.

• Syntax: MaxClients n
  
• Context: server
  
• Module: core
  
• Default: MaxClients 150
  

  The MaxClients directive sets the limit on the number of simultaneous requests that can be supported; not more than this number of child server processes will be created.

  NOTE:

  MaxClients should never be less than 2.

  
  

  Stronghold Web Server has a hard limit of 256 simultaneous requests. This is set in the httpd.h file. You can edit this file and recompile the server with a different hard limit, if necessary. See "Recompiling Stronghold" on page 8-9 for instructions on recompiling Stronghold.

• Syntax: MaxRequestsPerChild n
  
• Context: server
  
• Module: core
  
• Default: MaxRequestsPerChild 0
  

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

  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.
    
    

• Syntax: MaxSpareServers n
  
• Context: server
  
• Module: core
  
• Default: MaxSpareServers 10
  

  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 will kill 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.

• Syntax: MinSpareServers n
  
• Context: server
  
• Module: core
  
• Default: MinSpareServers 5
  

  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 1 per second.

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

• Syntax: StartServers n
  
• Context: server
  
• Module: core
  
• Default: StartServers 5
  

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

These directives determine how Stronghold uses system resources. If you set the maximum resource limit for any of these directive to a value higher than that already permitted by the operating system, Stronghold must start as root.

• Syntax: RLimitCPU n|max [n|max]
  
• Context: host
  
• Module: core
  

  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 limits 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.

• Syntax: RLimitMEM n|max [n|max]
  
• Context: host
  
• Module: core
  

  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
    
    

  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.

• Syntax: RLimitNPROC n|max [n|max]
  
• Module: core
  

  RLimitNPROC sets the maximum number of processes per user. For example, you can use this directive to control the number of simultaneous CGI processes allowed for individual users. 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 limits 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.

  NOTE:

  If your CGI processes run under the same user ID as Stronghold, this directive sets the maximum number of processes Stronghold itself is allowed to create. If the limit is too low, the error log will manifest the problem with "Cannot fork" messages.

  
  

The dynamic shared object module, mod_so, allows the server to load shared object code, including shared object modules, at startup. These directives designate shared object code to be loaded at startup. For more information about using mod_so, see "Dynamic Shared Object Support" on page 8-6.

• Syntax: LoadModule module filename
  
• Context: server
  
• Module: mod_so
  

  The LoadModule directive links the object file or library filename and adds the module structure named module to the list of active modules. Module is the name of the external variable of type module in the file. For example,

  LoadModule status_module src/modules/mod_status.so
  
  

  loads the status module from the src/modules subdirectory of ServerRoot.

• Syntax: LoadFile filename1 [filename2. . . ]
  
• Context: server
  
• Module: mod_so
  

  The LoadFile directive links one or more object files or libraries when the server starts or restarts. It can be used to load auxiliary code which may be required for a module to work. Filename is either an absolute path or relative to ServerRoot.

By default, all modules compiled into Stronghold are active, meaning that they all start with the server and can be invoked at any time. However, you can also use Stronghold's dynamic module system by applying the directives in this section. With dynamic modules, you can change the list of active modules without recompiling the server, simply by modifying httpd.conf and restarting Stronghold.

• Syntax: ClearModuleList
  
• Context: server
  
• Module: core
  

  By applying this directive to the server configuration, you "clear" the list of active modules and enable dynamic module linking. You must use this directive in order to use its counterpart, AddModule.

• Syntax: AddModule module1 [module2 . . . ]
  
• Context: server
  
• Module: core
  

  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 you add or remove a module from the AddModule list, you must restart Stronghold to implement your changes. For instructions on restarting the server, see "Restarting Stronghold" on page 1-3.

Stronghold can act as a proxy server using mod_proxy. The proxy module is described in more detail in Chapter 4.

• Syntax: ProxyRequests On|Off
  
• Context: host
  
• Module: mod_proxy
  

  ProxyRequests enables Stronghold's normal caching proxy service. Add this directive if you are using Stronghold as a firewall that serves documents from remote hosts to users on your LAN.

• Syntax: ProxyRemote match http://hostname:port
  
• Context: host
  
• Module: mod_proxy
  

  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.
    
    

  Remote-server is a partial URL for the remote server.

  For example:

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

• Syntax: ProxyPass path URL
  
• Context: host
  
• Module: mod_proxy
  

  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.

  NOTE:

  If URL specifies HTTPS and no port number is given, ProxyPass assumes port 443.

  
  

• Syntax: ProxyPassReverse path URL
  
• Context: host
  
• Module: mod_proxy
  

  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.
    
    

  For example, suppose the local server has the address http://wibble.org/ and includes the following configuration:

  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.

  Note that this directive can also by used in conjunction with mod_rewrite because it does not depend on a corresponding ProxyPass directive.

• Syntax: ProxyBlock word1|host1|domain1 [word2|host2|domain2] . . .
  
• Context: host
  
• Module: mod_proxy
  

  The ProxyBlock directive specifies a list of words, hosts, or domains, separated by spaces. The proxy server blocks requests that match words, hosts, or domains in the list. The proxy module also attempts to determine IP addresses of list items, then caches them for the match test. For example:

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

  Note that "wotsamattau" would also be sufficient to match "wotsamattau.edu." Note also that

  ProxyBlock *
  
  

  blocks connections to all sites.

• Syntax: NoProxy domain|subnet|IP|hostname [domain|subnet|IP|hostname. . . ]
  
• Context: host
  
• Module: mod_proxy
  

  This directive is useful for proxy servers within intranets. 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:

  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 list 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, and domains are always assumed to be anchored in the root of the DNS tree. For example, the two domains .MyDomain.com and .mydomain.com. (note the trailing period) are considered equal. Since a domain comparison does not involve a DNS lookup, it is more efficient than subnet comparison.

  • subnet
    
    

    A subnet is a partially-qualified IP address in numeric ("dotted quad") form, 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 number, 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
    
    

    An IP number represents a fully-qualified IP address in numeric ("dotted quad") form. Usually, this address represents a host, but there need not necessarily be a DNS domain name connected with the address. For example:

    NoProxy 192.168.123.7
    
    

    Because an IP number need not be resolved by the DNS system, it can result in more effective server performance.

  • hostname
    
    

    A hostname is a fully-qualified DNS domain name which can resolve into one or more IP numbers. It represents a logical host and must be resolvable to at least one IP number, or often to a list of hosts with different IP numbers. For example:

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

    In many situations, it is more effective to specify an IP number in place of a hostname, to avoid a DNS. Name resolution can take a good deal of time when the connection to the name server uses a slow link.

    Hostname comparisons are case-insensitive, and hostnames are always assumed to be anchored in the root of the DNS tree.

• Syntax: ProxyDomain domain
  
• Context: host
  
• Module: mod_proxy
  

  This directive is useful for proxy servers within intranets. The ProxyDomain directive specifies the default domain which the proxy server belongs to. A request for a host without a domain name is redirected to that same host, with the specified domain appended. For example:

  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.

• Syntax: ProxyReceiveBufferSize n
  
• Context: host
  
• Module: mod_proxy
  

  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. For example:

  ProxyReceiveBufferSize 2048
  
  

• Syntax: ProxyVia on|off|full|block
  
• Context: host
  
• Module: mod_proxy
  

  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:

  Value	Description
  on	A Via header for the current proxy host is added to each request and response.
  off	No special processing is performed. If a client request or a remote server response contains a Via header, it is passed through unchanged.
  full	Each generated Via header includes additional server version information in the form of a Via comment field.
  block	Via header lines are stripped from each proxy request and response. No new Via header is generated (not recommended).

• Syntax: AllowCONNECT port1 [port2. . . ]
  
• Context: host
  
• Module: mod_proxy
  

  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.

• Syntax: CacheRoot directory
  
• Context: host
  
• Module: mod_proxy
  

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

  NOTE:

  If you include this directive, you must also include the others listed in this section, with the exception of the optional ProxyRequests directive.

  
  

• Syntax: CacheDirLength n
  
• Context: host
  
• Module: mod_proxy
  

  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.

• Syntax: CacheDirLevels n
  
• Context: host
  
• Module: mod_proxy
  

  This sets the maximum number of levels of subdirectories within the CacheRoot directory. Any remaining characters in the hash used to create a series of subdirectory names down to this level are used to name the cached file.

• Syntax: CacheSize megabytes
  
• Context: host
  
• Module: mod_proxy
  

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

• Syntax: CacheGcInterval hours
  
• Context: host
  
• Module: mod_proxy
  

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

• Syntax: CacheMaxExpire hours
  
• Context: host
  
• Module: mod_proxy
  

  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.

• Syntax: CacheLastModifiedFactor multiplier
  
• Context: host
  
• Module: mod_proxy
  

  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
    
    

  The lesser of these two numbers is the value used to determine whether it is time to delete a given file from the cache. Multiplier is a floating point multiplier.

• Syntax: CacheDefaultExpire hours
  
• Context: host
  
• Module: mod_proxy
  

  If Stronghold does not have information about when a cached file was last modified, it uses the value set by CacheDefaultExpire. Hours is an expiration period in hours.

• Syntax: CacheForceCompletion n
  
• Context: host
  
• Module: mod_proxy
  

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

• Syntax: NoCache hostname1 [hostname2 . . . ]
  
• Context: host
  
• Module: mod_proxy
  

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

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

• general logs
  
  
• SSL logs
  
  
• CGI error logs
  
  
• special logs
  
  

For more detailed information about logs, see "Using Logs and Reports" on page 1-5.

These logs record data about non-SSL transactions.

• Syntax: TransferLog filename
  
• Context: server
  
• Module: mod_log_config
  

  This sets the path to the access log file. This is Stronghold's main log, where all non-SSL transactions are recorded. If this directive is not present, no log is written (allowing for other logging modules or directives). 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 access log has the following format:

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

  For a sample transfer log, see "Access Logs" on page 1-5.

• Syntax: LogFormat "string" [nickname]
  
• Context: host
  
• Module: mod_log_config
  

  This sets a customized format for the transfer log file. You can also use the LogFormat values shown below with the CustomLog directive, which establishes a separate, customized log file. This directive can 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.

  String can include literal characters to copy into the log files, plus any of these variables, denoted by a percent sign:

  Variable	Description
  %a	Remote IP address
  %b	Bytes sent in the body of the response
  %f	The name of the requested file
  %h	Remote hostname, or "-" if the remote IP address does not resolve to a hostname
  %l	Remote log name (from identd, if supplied)
  %p	The port that received the request
  %P	The process ID of the child process that handled the request
  %r	The first line of the request
  %s	The server status code returned in the response. For requests that got internally redirected, this is status of the original request. Use "%>s" for the final status.
  %t	The time, in the common log format time format
  %T	The time elapsed between receipt of the client request and transmission of the server response
  %u	The remote user, if supplied by mod_auth. The value may be invalid if the server status code is 401.
  %U	The requested URL
  %v	The hostname to which the request was directed
  %{cipher}c	The cipher used, if this is a secure transaction
  %{errcode}c	X509 verify error code
  %{errstr}c	X509 verify error string
  %{format}t	The time the request arrived. If format is omitted, the time is given in common log format time. Format must conform to strftime(3) format.
  %{header}i	The contents of the client request header specified by header
  %{header}o	The contents of the server response header specified by header
  %{issuerdn}c	The issuer of the client certificate
  %{note}n	The contents of a note from another module, specified by note
  %{subjectdn}c	The subject, or owner, of the client certificate used in a secure transaction
  %{variable}e	The value of the environment variable

  In variables with bracketed values, the percent sign (%) can be followed by one or more 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 requests that return server status codes of 400 or 501 (Bad Request, 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 descriptor as the main host.

  That means that you can do things such as

  <VirtualHost host1.com>
  LogFormat "string1"
  . . .
  </VirtualHost>
  <VirtualHost host2.com>
  LogFormat "string2"
  . . .
  </VirtualHost>
  
  

  to have different virtual servers write into the same log file, but have some indication which host they came from, though in some cases a "%v" variable may be a better way to handle this.

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

• Syntax: CustomLog filename "string"
  
• Context: host
  
• Module: mod_log_config
  

  With the CustomLog directive, you can create multiple logs 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.

• Syntax: ErrorLog filename|syslog
  
• Context: host
  
• Module: core
  
• Default: ErrorLog logs/error_log
  

  The ErrorLog directive sets the path to the file used to log all general and CGI errors. 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 "Error Logs" on page 1-6.

  NOTE:

  Be sure to check this file occasionally to make sure that your site is running smoothly.

  
  

• Syntax: LogLevel level
  
• Context: host
  
• Module: core
  
• Default: LogLevel error
  

  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:

  Level	Description	Example
  emerg	emergencies-system is unusable	"Child cannot open lock file. Exiting"
  alert	action must be taken immediately	"getpwuid: couldn't determine user name from uid"
  crit	critical conditions	"socket: Failed to get a socket, exiting child"
  error	error conditions	"Premature end of script headers"
  warn	warning conditions	"child process 1234 did not exit, sending another SIGHUP"
  notice	normal but significant conditions	"httpd: caught SIGBUS, attempting to dump core in. . . "
  info	informational messages	"Server seems busy, (you may need to increase StartServers, or Min/MaxSpareServers). . . "
  debug	debug-level messages	"Opening config file. . . "

  When a particular level is specified, messages from all other levels of higher significance will be reported as well. For example, when

  LogLevel info
  
  

  is specified, then messages with log levels of "notice" and "warn" are also posted.

  NOTE:

  A level of "crit" or below is recommended.

  
  

• Syntax: CookieLog filename
  
• Context: object
  
• Module: mod_log_config
  

  This directive sets the filename of the session tracking log.

• Syntax: HostnameLookups on|off|double
  
• Context: server
  
• Module: core
  
• Default: HostnameLookups off
  

  When this directive is set to "on," Stronghold logs hostnames by performing reverse lookups. When it is set to "off" or omittied, Stronghold logs only the IP numbers. 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 numbers from the result of the forward lookup must match the original IP number. It is set to "off" by default to reduce unnecessary DNS traffic.

  NOTE:

  Regardless of how this directive is set, double-reverse DNS lookups are performed for all requests that are subject to host-based access control.

  
  

• Syntax: PidFile filename
  
• Context: server
  
• Module: core
  
• Default: PidFile logs/httpd.pid
  

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

• Syntax: ScoreBoardFile filename
  
• Context: server
  
• Module: core
  

  The ScoreBoardFile directive sets the path to the file used to store internal server process 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 only by the server, as a place where child processes can write information used by the parent process to manage the children.

  NOTE:

  Operating systems with memory mapping functions do not use this directive.

  
  

• Syntax: IdentityCheck on|off
  
• Context: object
  
• Module: core
  
• Default: IdentityCheck off
  

  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.

  NOTE:

  The information should not be trusted in any way except for rudimentary usage tracking.

  
  

• Syntax: ExtendedStatus on|off
  
• Context: server
  
• Module: mod_status
  
• Default: ExtendedStatus off
  

  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.

• Syntax: AddModuleInfo module string
  
• Context: host
  
• Module: mod_browser
  

  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 'See <A HREF="http://www.apache.org/docs/mod/mod_auth.html">http://www.apache.org/docs/mod/mod_auth.html</A>'
  
  

  See also "Server Information Reports" on page 1-13.

These logs record data about SSL transactions.

• Syntax: SSLLogFile filename
  
• Context: host
  
• Module: mod_ssl
  

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

• Syntax: SSLErrorFile filename
  
• Context: host
  
• Module: mod_ssl
  

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

• Syntax: SSL_CertificateLogDir path
  
• Context: object
  
• Module: mod_ssl
  

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

• Syntax: ScriptLog filename
  
• Context: server
  
• Module: mod_cgi
  

  This directive specifies the CGI error log file. If it is absent, CGI does not log errors. Filename can be an absolute path, or a path relative to ServerRoot.

• Syntax: ScriptLogLength bytes
  
• Context: server
  
• Module: mod_cgi
  

  ScriptLogLength limits the size of the CGI error log in bytes. When the log file reaches this size, CGI error logging stops. When this occurs, you must move the old log file. CGI then creates a new one and continues logging errors.

• Syntax: ScriptLogBuffer bytes
  
• Context: server
  
• Module: mod_cgi
  

  This directive limits the size of individual error log entries in bytes, to prevent the log file from becoming bloated when it receives large entity bodies.

Although the modules that generate these logs are compiled into Stronghold by default, we recommend that you use the CustomLog directive instead.

• Syntax: AgentLog file-pipe
  
• Context: host
  
• Module: mod_log_agent
  

  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 to a program that receives the 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.
    
    

  NOTE:

  If a program is used, then it will be run under the user who started the server, not the user the server runs as. For example, this is root if the server was started by root.

  
  

  This directive is provided for compatibility with NCSA 1.4.

• Syntax: RefererLog file-pipe
  
• Context: host
  
• Module: mod_log_referer
  

  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. A new program will not be started for a virtual host if it inherits the RefererLog from the main server.
    
    

  NOTE:

  If a program is used, then it will be run under the user who started the server, not the user the server runs as. For example, this is root if the server was started by root.

  
  

  This directive is provided for compatibility with NCSA 1.4.

• Syntax: RefererIgnore string1 [string2 . . . ]
  
• Context: host
  
• Module: mod_log_referer
  

  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
  
  

  prevents the module from logging references from www.ncsa.uiuc.edu.

These directives control

• aliases
  
  

  Aliases let you manipulate URLs and incorporate directories outside your DocumentRoot-including directories on other servers-by assigning pseudonyms to directories.

• directory indexing
  
  

  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.

• Syntax: Alias /path/ /actual/path/
  
• Context: host
  
• Module: mod_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 /ServerRoot/icons directory. This means that URLs and other references do not necessarily have to refer to documents under the root document directory.

• Syntax: AliasMatch regex path
  
• Context: server, host
  
• Module: mod_alias
  

  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
  
  

• Syntax: ScriptAlias /path/ /actual/path/
  
• Context: server
  
• Module: mod_alias
  

  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.

• Syntax: ScriptAliasMatch regex path
  
• Context: server, host
  
• Module: mod_alias
  

  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
  
  

• Syntax: Redirect type /path/ URI
  
• Context: server
  
• Module: mod_alias
  

  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
    
    

  For example,

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

  causes Stronghold to redirect all requests for http://www.host.com/secure/ to https://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 to https://www.host.com/whatever.

  NOTE:

  If URI points to a directory on your server, avoid "loops" by making sure that URI does not point back to path.

  
  

• Syntax: RedirectMatch [status regex URL
  
• Context: server, host
  
• Module: mod_alias
  

  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
  
  

• Syntax: RedirectTemp URL-path URL
  
• Context: object
  
• Module: mod_alias
  

  This directive is equivalent to

  Redirect temp
  
  

  and sends the status code 302 to the client to indicate that the resource specified by URL-path has temporarily moved to URL.

• Syntax: RedirectPermanent URL-path URL
  
• Context: object
  
• Module: mod_alias
  

  This directive is equivalent to

  Redirect perm
  
  

  and sends the status code 301 to the client to indicate that the resource specified by URL-path has permanently moved to URL.

• Syntax: UserDir directory
  
• Context: host
  
• Module: mod_userdir
  

  You may want to allow users to control their own Web files, and possibly .htaccess files, in their own home directories. UserDir is a powerful aliasing directive that sets the name of the subdirectory that contains user Web files and can take wildcard expressions. Directory can take three forms:

  • a directory name
    
    

    If the value is a simple directory name, such as public_html, then Stronghold maps this directory name to a subdirectory within each user's home directory, such as /home/sameer/public_html.

  • an absolute path
    
    

    If the value is an absolute path, such as /www, then Stronghold maps it to a user subdirectory within the specified directory, such as /www/sameer.

  • a path with wildcards
    
    

    You can use wildcards to specify a path ending in a subdirectory within a user's Web directory. For example, if the value is /www/*/htdocs, then Stronghold maps it to /www/sameer/htdocs, /www/erin/htdocs, and so on.

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.
  
  

• Syntax: DirectoryIndex filename1 [filename2 . . . ] /path/to/error/page
  
• Context: object
  
• Module: mod_dir
  
• AllowOverride: Indexes
  

  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
  
  

  and index.html does not exist, then the request is passed to mod_autoindex, which is controlled with the remaining directives in this section.

• Syntax: FancyIndexing on|off
  
• Context: object
  
• Module: mod_autoindex
  
• AllowOverride: Indexes
  

  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 "SuppressColumnSorting."

• Syntax: AddIcon iconfilename filename1 [filename2 . . . ]
  
• Context: object
  
• Module: mod_autoindex
  
• AllowOverride: Indexes
  

  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 an 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.

• Syntax: AddIconByEncoding iconfilename MIME-type1 [MIME-type2 . . . ]
  
• Context: object
  
• Module: mod_autoindex
  
• AllowOverride: Indexes
  

  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.

• Syntax: AddIconByEncoding iconfilename encoding-type1 [encoding-type2 . . . ]
  
• Context: object
  
• Module: mod_autoindex
  
• AllowOverride: Indexes
  

  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.

• Syntax: DefaultIcon iconfilename
  
• Context: object
  
• Module: mod_autoindex
  
• AllowOverride: Indexes
  

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

• Syntax: HeaderName filename
  
• Context: object
  
• Module: mod_autoindex
  
• AllowOverride: Indexes
  

  You can place text and images at the top of a directory index by specifying a filename using the HeaderName 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.

• Syntax: ReadmeName filename
  
• Context: object
  
• Module: mod_autoindex
  
• AllowOverride: Indexes
  

  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.

• Syntax: IndexIgnore arg1 [arg2 . . . ]
  
• Context: object
  
• Module: mod_autoindex
  
• AllowOverride: Indexes
  

  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.

• Syntax: AddDescription "description" filename1 [filename2 . . . ]
  
• Context: object
  
• Module: mod_autoindex
  
• AllowOverride: Indexes
  

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

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

• Syntax: AddAlt "description" filename1 [filename2 . . . ]
  
• Context: object
  
• Module: mod_autoindex
  
• AllowOverride: Indexes
  

  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.

• Syntax: AddAltByType "description" MIME-type1
  [MIME-type2 . . . ]
  
• Context: object
  
• Module: mod_autoindex
  
• AllowOverride: Indexes
  

  Similar to AddAlt, AddAltByType matches alternative descriptive text to one or more MIME 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 or AddAlt value.

• Syntax: AddAltByEncoding "description" encoding-type1 [encoding-type2 . . . ]
  
• Context: object
  
• Module: mod_autoindex
  
• AllowOverride: Indexes
  

  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.

• Syntax: IndexOptions option1 [option2 . . . ]
  
• Context: object
  
• Module: mod_autoindex
  
• AllowOverride: Indexes
  

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

  Option	Description
  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 a list of linked filenames. To generate icons and extra information such as modification dates and file sizes along with the file list, include this directive.
  IconHeight=pixels	When combined with the IconWidth option, this causes Stronghold to include the height attribute in icon <IMG> tags.
  IconsAreLinks	If this option is included, each icon in the directory index will be linked to the file listed beside it.
  IconWidth=pixels	When combined with the IconHeight option, this causes Stronghold to include the width attribute in icon <IMG> tags.
  NameWidth=characters|*	This sets the width of the "Filename" column, in characters, or "*" to set the column width to the width of the longest filename.
  ScanHTMLTitles	For each HTML file, Stronghold can obtain the contents of the <TITLE> field, if any, and include it in the directory index. Keep in mind that this requires extra processing.
  SuppressColumnSorting	This option suppresses column sorting.
  SuppressDescription	This option suppresses the Description column.
  SuppressHTMLPreamble	Normally, directory indexes are generated with a standard HTML preamble. When this option is set and a file specified by HeaderName exists, then Stronghold omits the preamble. In this case, the header file must include an HTML header.
  SuppressLastModified	This option suppresses the Last Modified column.
  SuppressSize	This option suppresses the Size column.

When all other modules fail to fulfill 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."

• Syntax: CheckSpelling on|off
  
• Context: object
  
• Module: mod_speling
  
• Default: CheckSpelling off
  

  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.
    
    

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,

index.html.en.gz

denotes an HTML file in English, with gzip encoding. This naming scheme allows Stronghold to interpret filenames and carry out the file handling directives in this section:

• filetypes
  
  
• metainformation
  
  
• handlers
  
  
• URL rewriting
  
  

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

• Syntax: MimeMagicFile magicfilename
  
• Context: server, host
  
• Module: mod_mime_magic
  

  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.

• Syntax: TypesConfig filename
  
• Context: server
  
• Module: mod_mime
  

  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.

• Syntax: AddType MIME-type file-suffix
  
• Context: object
  
• Module: mod_mime
  
• AllowOverride: FileInfo
  

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

• Syntax: ForceType type
  
• Context: object
  
• Module: mod_mime
  

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

• Syntax: AddEncoding encoding-type file-suffix
  
• Context: object
  
• Module: mod_mime
  
• AllowOverride: FileInfo
  

  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.

• Syntax: AddLanguage language-type filename-suffix
  
• Context: object
  
• Module: mod_mime
  
• AllowOverride: FileInfo
  

  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 language 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.

• Syntax: DefaultType mime-type
  
• Context: object
  
• Module: core
  
• Default: DefaultType text/html
  

  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
  
  

  would be appropriate for a directory that contained many GIF images with filenames missing the .gif suffix.

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 A.

• Syntax: ContentDigest yes|no
  
• Context: server
  
• Module: core
  

  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.

• Syntax: MetaFiles on|off
  
• Context: .htaccess
  
• Module: mod_cern_meta
  
• Default: MetaFiles off
  

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

• Syntax: MetaDir directory-name
  
• Context: .htaccess
  
• Module: mod_cern_meta
  

  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 accessed. Set to "." to instruct the server to look in the directory that contains the requested file.

• Syntax: MetaSuffix suffix
  
• Context: .htaccess
  
• Module: mod_cern_meta
  

  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 DOCUMENT_ROOT/somedir/.web/index.html.meta and will use its contents to generate additional HTTP header information.

• Syntax: ExpireActive on|off
  
• Context: object
  
• Module: mod_expires
  
• AllowOverride: Indexes
  

  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 by ExpiresByType and ExpiresDefault to generate Expires headers.

• Syntax: ExpiresByType mime-type CODE
  
• Context: object
  
• Module: mod_expires
  
• AllowOverride: Indexes
  

  When ExpiresActive is set to "on," ExpiresByType sets the content of the Expires header by 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.
    
    

  For example:

  ExpiresByType 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.

• Syntax: ExpiresDefault CODE
  
• Context: object
  
• Module: mod_expires
  
• AllowOverride: Indexes
  

  When ExpiresActive is set to "on," ExpiresDefault sets the default content of the Expires header for all documents. ExpiresByType 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.
    
    

• Syntax: Header [set|append|add|unset] header value
  
• Context: object
  
• Module: mod_headers
  

  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:

  Value	Description
  set	Set the response header header to value, replacing any previous header with the same name.
  append	Append the response header to any existing header of the same name. When a new value is merged onto an existing header, it is separated from the existing header with a comma. This is the HTTP standard for giving a header multiple values.
  add	Add the response header to the existing set of headers, even if this header already exists. This value can result in two (or more) headers having the same name. This can lead to unforeseen consequences, and in general "append" should be used instead.
  unset	Remove the response header of this name if it exists. If there are multiple headers of the same name, only the first one set will be removed. For "unset," no value should be given.

  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:

  1. server
     
     
  2. virtual host
     
     
  3. <Directory> containers and .htaccess files
     
     
  4. <Location> containers
     
     
  5. <Files> containers
     
     

  Order is important. For example, these two headers have different effects if they are reversed:

  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. These means that some headers that are added just before the response is sent-including the Date and Server headers-cannot be unset or overridden.

• Syntax: ServerTokens min[imal]|os|full
  
• Context: server
  
• Module: core
  
• Default: ServerTokens Full
  

  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:

  Value	Resulting Server Header
  min[imal]	Server: Stronghold/2.4.1 Apache/1.3.2
  os	Server: Stronghold/2.4.1 Apache/1.3.2 (Unix)
  full (or not specified)	Server: Stronghold/2.4.1 Apache/1.3.2 (Unix) PHP/3.0 MyMod/1.2

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

• Syntax: AddHandler handler-name filename-suffix
  
• Context: object
  
• Module: mod_mime
  
• AllowOverride: FileInfo
  

  This directive matches handlers to filename suffixes 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 httpd.conf:

  AddHandler send-as-is asis
  
  

  With this handle enabled, Stronghold sends any file ending in .asis without adding an HTTP header. Your .asis files must include their own HTTP headers, followed by two carriage returns. This means that you can attach custom headers to your files without creating special CGI scripts to manage them.

  You can also use this directive to create special handlers specifically for the Action directive, as described below.

• Syntax: SetHandler handler
  
• Context: object
  
• Module: mod_mime
  
• AllowOverride: FileInfo
  

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

  Handler	Description
  cgi-script	All files are treated as CGI scripts and processed by mod_cgi.
  imap-file	All files are treated as imagemap files and processed by mod_imap.
  send-as-is	Stronghold send all files without appending HTTP headers.
  server-info	All files are sent with server configuration information.
  server-status	All files are sent with server status information.
  server-parsed	All files are treated as server-parsed HTML, for server-side includes by mod_ssi.
  type-map	All files are treated as type maps for content negotiation by mod_negotiation.

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

• Syntax: Action handler|media-type script
  
• Context: object
  
• Module: mod_action
  
• AllowOverride: FileInfo
  

  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-file /cgi-bin/imap.cgi
  
  

  which causes Stronghold to send all files ending in .map directly to the imap.cgi script. Thus, if Stronghold receives a request for http://www.host.com/nav.map, it behaves as if it received a request for http://www.host.com/cgi-bin/imap.cgi/nav.map instead. Action can be used with AddType in the same way.

• Syntax: Script method script
  
• Context: object
  
• Module: mod_action
  

  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 an object that carries this directive, and no other handling is defined for that object, Stronghold passes the requested URL and the actual path to the script using the PATH_INFO and PATH_TRANSLATED 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.

Stronghold includes mod_rewrite, a module that rewrites requested URLs that match a set of conditions. The rewritten request can be a URI, a URL, or a filepath with or without QUERY_STRING information. This powerful module can be used for an enormous variety of purposes, limited only by your imagination. It is documented in great detail at http://www.engelschall.com/sw/mod_rewrite/doc/mod_rewrite/toc.html.

• Syntax: RewriteEngine on|off
  
• Context: object
  
• Module: mod_rewrite
  
• AllowOverride: FileInfo
  

  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.

• Syntax: RewriteLog filename
  
• Context: server
  
• Module: mod_rewrite
  

  This directive sets the filename of the log that records all rewrite actions. Make sure the directory that contains this file is not writeable by anyone other than the user that starts the server, preferably root.

• Syntax: RewriteLogLevel n
  
• Context: server
  
• Module: mod_rewrite
  

  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.

• Syntax: RewriteLock filename
  
• Context: host
  
• Module: mod_rewrite
  

  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 map-program. It is not required for SAMP using all other types of rewriting maps.

• Syntax: RewriteOptions inherit
  
• Context: object
  
• Module: mod_rewrite
  
• AllowOverride: FileInfo
  

  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.

• Syntax: RewriteBase URL
  
• Context: .htaccess only
  
• Module: mod_rewrite
  
• AllowOverride: FileInfo
  

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

• Syntax: RewriteMap mapname txt|dbm|prg:filename
  
• Context: object
  
• Module: mod_rewrite
  

  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:

  Format Indicator	Description
  rnd	randomized plain text. It contains values separated by pipes (|) meaning "or." The values constitute a set of alternatives from which the returned value is chosen randomly. This is designed for load balancing in a reverse proxy configuration where the values are server names. For example: static www1|www2|www3|www4 dynamic www5|www6
  int	internal function. The source is an internal server function. Currently, you cannot create your own, but the following functions are built-in: toupper Converts the key to all upper case tolower Converts the key to all lower case
  txt	an ASCII file. The file can contain blank lines, comment lines beginning with a hash (#) character, and key-value pair lines like this: key substitute The key uniquely denotes the line, and substitute is the substitution pattern to use when the key is called.
  dbm	a binary NDBM file, which you can create with an NDBM tool or the src/util/dbmmanage utility
  prg	a UNIX executable, either an object-code program or a script that begins with this magic cookie line: #!/path/to/interpreter

• Syntax: RewriteCond test-string condition-pattern
  
• Context: object
  
• Module: mod_rewrite
  
• AllowOverride: FileInfo
  

  RewriteCond defines a rule condition and always precedes a RewriteRule directive. The rule given in 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_COOKIE
  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
  
  

  Condition-pattern is a standard, extended regular expression that mod_rewrite applies to an instance of the test-string. It can be preceded by an exclamation mark (!) to indicate a non-matching pattern, or substituted with one of the following flags:

  Flag	Description
  -d	Indicates that the test-string is a path to a directory
  -f	Indicates that the test-string is a path to a file
  -s	Indicates that the test-string is a path to a file with a size greater than 0
  -l	Indicates that the test-string is a path to a symbolic link
  -F	Indicates that the test-string should be a path to a valid file that is accessible via the current access controls for the path, and instructs mod_rewrite to use an internal subrequest to check this. This may decrease Stronghold's performance.
  -U	Indicates that the test-string should be a valid URL that is accessible via the current access controls for its path, and instructs mod_rewrite to use an internal subrequest to check this. This may decrease Stronghold's performance.

  Any of these flags can also be prepended by an exclamation mark (!).

  Condition-pattern can also be appended by a comma-separated, bracketed list of one of the following rule flags:

  Rule Flag	Description
  nocase	Makes test-string and condition-pattern case-insensitive
  NC	Same as "nocase"
  ornext	Used with multiple RewriteCond directives to combine them with OR instead of the implicit AND.
  OR	Same as "ornext"

  For example:

  RewriteCond ${REMOTE_HOST} ^host1.* [OR]
  RewriteCond ${REMOTE_HOST} ^host2.* [OR]
  RewriteCond ${REMOTE_HOST} ^host3.*
  
  

• Syntax: RewriteRule pattern substitute
  
• Context: object
  
• Module: mod_rewrite
  
• AllowOverride: FileInfo
  

  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
    
    

  You can set special options for substitute by appending a comma-separated, bracketed list of these flags:

  Flag	Description
  redirect[=status-code]	Sends a status code between 300 and 400, specified by status-code. The default is 302.
  R[=status-code]	Same as "redirect"
  forbidden	Forces Stronghold to return a status code of 403 (Forbidden). This flag is useful for conditionally blocking URLs.
  F	Same as "forbidden"
  gone	Forces Stronghold to return a status code of 410 (Gone)
  G	Same as "gone"
  proxy	Forces the substitution part through the proxy module. The substitution string must be a valid URI. This is useful as a sophisticated alternative to the ProxyPass directive.
  P	Same as "proxy"
  last	Forces the rewrite process to end here
  L	Same as "last"
  next	Reruns the rewrite process, starting with the first instance of RewriteRule and using the outcome of the current rewrite process as new input
  N	Same as "next"
  chain	Chains the current rule with the next rule, provided that the current rule matches
  C	Same as "chain"
  type=mime-type	Forces Stronghold to return the file as the specified MIME type
  T=mime-type	Same as "type"
  nosubreq	Indicates that the current rule applies only if the current request is not an internal subrequest
  NS	Same as "nosubreq"
  passthrough	Passes the substitution to the next handler, which should immediately follow the current RewriteRule
  PT	Same as "passthrough"
  skip=n	Skips the next n rules in a sequence if the current rule matches
  S=n	Same as "skip"
  env=VARIABLE:VALUE	Sets the environment variable VARIABLE to the value VALUE
  E=VARIABLE:VALUE	Same as "env"

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
  
  
• embedded PHP scripting
  
  

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.

• Syntax: LimitRequestBody n
  
• Context: server
  
• Module: core
  

  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).

• Syntax: LimitRequestFields n
  
• Context: server
  
• Module: core
  

  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.

• Syntax: LimitRequestFieldSize n
  
• Context: server
  
• Module: core
  

  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.

• Syntax: LimitRequestLine n
  
• Context: server
  
• Module: core
  

  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.

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 considerably content management work, since separate versions of the same material must be organized and maintained.

"Content Negotiation" on page 9-4 provides a more detailed discussion of how content negotiation works.

• Syntax: CacheNegotiatedDocs
  
• Context: server
  
• Module: mod_negotiation
  

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

• Syntax: LanguagePriority language-type1 [language-type2 . . . ]
  
• Context: object
  
• Module: mod_negotiation
  
• AllowOverride: FileInfo
  

  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.

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

• Syntax: CookieTracking on|off
  
• Context: object
  
• Module: mod_usertrack
  
• AllowOverride: FileInfo
  

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

• Syntax: CookieExpires expiry-period
  
• Context: host
  
• Module: mod_usertrack
  

  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 the 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
    
    
  • hours
    
    
  • minutes
    
    
  • seconds
    
    

  For example:

  CookieExpires "6 months 2 weeks 7 hours"
  

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

• Syntax: ImapMenu option
  
• Context: object
  
• Module: mod_imap
  
• AllowOverride: Indexes
  

  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:

  Option	Description
  none	No menu is generated, and Stronghold takes the action specified by ImapDefault instead.
  formatted	Stronghold generates a formatted menu that includes a list of available links.
  semiformatted	Stronghold generates a menu that includes a list of available links and comments from the imagemap file, separated by simple line breaks.
  unformatted	Stronghold generates a menu that consists of the unformatted text of the imagemap file.

• Syntax: ImapDefault action|URL
  
• Context: object
  
• Module: mod_imap
  
• AllowOverride: Indexes
  

  ImapDefault specifies the action Stronghold takes if

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

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

  Option	Description
  error	Stronghold returns a 500 (Server Error) status code.
  nocontent	Stronghold returns a 204 (No Content) status code, and the client takes no action.
  map	Stronghold uses the imagemap file to generate a menu.
  referer	Stronghold instructs the client to return to the referring document, or to the root document for the site if no Referer header was included with the request.

• Syntax: ImapBase option|URL
  
• Context: object
  
• Module: mod_imap
  
• AllowOverride: Indexes
  

  ImapBase sets the base URL for all 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 (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-6.

• Syntax: XBitHack off|on|full
  
• Context: object
  
• Module: mod_include
  
• AllowOverride: Options
  
• Default: XBitHack off
  

  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:

  Value	Description
  off	No special parsing of executable files.
  on	Files with the user-execute bit set are treated as server-parsed HTML.
  full	Files with the user-execute bit set are treated as server-parsed HTML. If a file has the group-execute bit set, then the last-modified date is included in the HTTP header, if such data exists.

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 11 explains PHP in detail.

• Syntax: phpShowInfo on|off
  
• Context: object
  
• Module: mod_php
  
• AllowOverride: FileInfo
  

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

• Syntax: phpLastModified on|off
  
• Context: object
  
• Module: mod_php
  
• AllowOverride: FileInfo
  

  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.

  NOTE:

  If you are using page logging, multiple accesses will not be logged.

  
  

• Syntax: phpLogging on|off
  
• Context: object
  
• Module: mod_php
  
• AllowOverride: FileInfo
  

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

• Syntax: phpDebug on|off
  
• Context: object
  
• Module: mod_php
  
• AllowOverride: FileInfo
  

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

• Syntax: phpUploadTmpDir directory
  
• Context: object
  
• Module: mod_php
  
• AllowOverride: FileInfo
  

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

• Syntax: phpDbmLogDir directory
  
• Context: object
  
• Module: mod_php
  
• AllowOverride: FileInfo
  

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

• Syntax: phpSQLLogHost hostname
  
• Context: object
  
• Module: mod_php
  
• AllowOverride: FileInfo
  

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

• Syntax: phpSQLLogDB database
  
• Context: object
  
• Module: mod_php
  
• AllowOverride: FileInfo
  

  This directive sets the name of the SQL logging database.

• Syntax: phpMsqlLogHost hostname
  
• Context: object
  
• Module: mod_php
  
• AllowOverride: FileInfo
  

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

• Syntax: phpMsqlLogDB database
  
• Context: object
  
• Module: mod_php
  
• AllowOverride: FileInfo
  

  This directive sets the name of the mSQL logging database.

• Syntax: phpAccessDir directory
  
• Context: object
  
• Module: mod_php
  
• AllowOverride: FileInfo
  

  This directive sets the directory for PHP access control files.

• Syntax: phpMaxDataSpace kilobytes
  
• Context: object
  
• Module: mod_php
  
• AllowOverride: FileInfo
  

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

• Syntax: phpIncludePath path1[:path2:path3. . . ]
  
• Context: object
  
• Module: mod_php
  
• AllowOverride: FileInfo
  

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

• Syntax: phpAutoPrependFile filename
  
• Context: object
  
• Module: mod_php
  
• AllowOverride: FileInfo
  

  The file specified by phpAutoPrependFile is parsed before the requested file using PHP's Include(filename) function. phpIncludePath applies. Keep in mind that an auto-prepended file makes it difficult you to use the Header("header_string") function in the requested file.

• Syntax: phpAutoAppendFile filename
  
• Context: object
  
• Module: mod_php
  
• AllowOverride: FileInfo
  

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

• Syntax: phpAdaDefDB database
  
• Context: object
  
• Module: mod_php
  
• AllowOverride: FileInfo
  

  This is the Adabas database.

• Syntax: phpAdaUser username
  
• Context: object
  
• Module: mod_php
  
• AllowOverride: FileInfo
  

  This is the default Adabas database user.

• Syntax: phpAdaPW password
  
• Context: object
  
• Module: mod_php
  
• AllowOverride: FileInfo
  

  This is the default Adabas database password.

• Syntax: phpEngine on|off
  
• Context: object
  
• Module: mod_php
  

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

• Syntax: phpXBitHack on|off
  
• Context: object
  
• Module: mod_php
  
• AllowOverride: FileInfo
  

  When phpXBitHack 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.

Stronghold Web Server 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 DB authentication
  
  
• DBM authentication
  
  
• digest authentication
  
  
• SSL certificate authentication and access control
  
  
• host-based access control
  
  
• anonymous logins
  
  

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

• Syntax: AuthType Basic|Digest|Cert
  
• Context: object
  
• Module: core
  

  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 uses text files to authenticate users with simple logins and passwords. Users can be grouped for access control purposes.

• Syntax: AuthName auth-domain
  
• Context: object
  
• Module: core
  

  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.

• Syntax: Require entity-name entity1 [entity2 . . . ]
  
• Context: object
  
• Module: core
  
• AllowOverride: AuthConfig
  

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

  Value	Description
  Require user userid userid . . .	Only the named users can access the directory.
  Require group group-name group-name . . .	Only users in the named groups can access the directory.
  Require valid-user	All valid users can access the directory.

  If Require appears in a <Limit> container, then it restricts access to the named methods; 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
  
  

• Syntax: AuthGroupFile filename
  
• Context: object
  
• Module: mod_auth
  
• AllowOverride: FileInfo
  

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

• Syntax: AuthUserFile filename
  
• Context: object
  
• Module: mod_auth
  
• AllowOverride: FileInfo
  

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

• Syntax: AuthAuthoritative on|off
  
• Context: object
  
• Module: mod_auth
  
• AllowOverride: AuthConfig
  

  Setting the AuthAuthoritative directive to "off" allows authentication and authorization to be passed to lower level modules (as defined in the Configuration and modules.c files) 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 a 401 Unauthorized reply.

  If a user ID 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 AuthAuthoritative 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, AuthAuthoritative is set to "on" and an unknown userID or rule results in a 401 Unauthorized reply. Setting it to "off" keeps the system secure and forces NSCA-compliant behaviour.

  Be sure to consider the implications of allowing a user to permit fall-through in an .htaccess file and verify that this is really what you want. Generally, it is easier to just secure a single .htpasswd 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.

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

• Syntax: AuthDBGroupFile filename
  
• Context: object
  
• Module: mod_auth_db
  
• AllowOverride: AuthConfig
  

  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.

  NOTE:

  Make sure that the AuthDBGroupFile is stored outside the document tree of the Web server, and do not put it in the directory that it protects. Otherwise, clients will be able to download the AuthDBGroupFile.

  
  

• Syntax: AuthDBUserFile filename
  
• Context: object
  
• Module: mod_auth_db
  
• AllowOverride: AuthConfig
  

  The AuthDBUserFile directive sets the name of a DB 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.

  NOTE:

  Make sure that the AuthDBUserFile is stored outside the document tree of the Web server, and do not put it in the directory that it protects. Otherwise, clients will be able to download the AuthDBUserFile.

  
  

• Syntax: AuthDBAuthoritative yes|no
  
• Context: object
  
• Module: mod_auth_db
  

  If more than one authentication method is configured for the same object, including DB authentication, then AuthDBAuthoritative sets whether DB is the authoritative authentication method. By default, Stronghold executes authentication methods in the reverse order of the ServerRoot/src/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).

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

• Syntax: AuthDBMGroupFile filename
  
• Context: object
  
• Module: mod_auth_dbm
  
• AllowOverride: AuthConfig
  

  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.

  NOTE:

  Make sure that the AuthDBMGroupFile is stored outside the document tree of the Web server, and do not put it in the directory that it protects. Otherwise, clients will be able to download the AuthDBMGroupFile.

  
  

• Syntax: AuthDBMUserFile filename
  
• Context: object
  
• Module: mod_auth_dbm
  
• AllowOverride: AuthConfig
  

  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.

  NOTE:

  Make sure that the AuthDBMUserFile is stored outside the document tree of the Web server, and do not put it in the directory that it protects. Otherwise, clients will be able to download the AuthDBMUserFile.

  
  

• Syntax: AuthDBMAuthoritative yes|no
  
• Context: object
  
• Module: mod_auth_db
  

  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 reverse order of the ServerRoot/src/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).

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.

• Syntax: AuthDigestFile filename
  
• Context: object
  
• Module: mod_digest
  
• AllowOverride: AuthConfig
  

  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/htdigest utility.

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 "Client Authentication" on page 2-14.

• Syntax: SSLCACertificatePath path
  
• Context: host
  
• Module: mod_ssl
  

  This directive sets the path to the directory where trusted CA root certificates are kept. Store the CA root certificates for client certification here. If you want to prioritize the CAs you accept, use SSLCACertificateFile instead.

• Syntax: SSLCACertificateFile filename
  
• Context: host
  
• Module: mod_ssl
  

  This directive sets the trusted CA root certificate file. Unlike SSLCACertificatePath, it specifies a certificate file rather than a certificate directory. The file contains one or more PEM-encoded CA certificates, in order of preference. This is equivalent to SSLClientCAFile.

• Syntax: SSLVerifyClient 0|1|2
  
• Context: host
  
• Module: mod_ssl
  

  This directive sets the X.509 Client Authentication option:

  0 = No
  1 = X.509 certificate optional
  2 = X.509 certificate required
  
  

• Syntax: SSLVerifyDepth n
  
• Context: host
  
• Module: mod_ssl
  

  Certification Authorities are certified by other CAs, forming a chain of certificates that the server can follow for progressively decisive verification. SSLVerifyDepth sets the number of CAs the server will follow in this chain when verifying client certificates.

• Syntax: RequireSSL on|off
  
• Context: object
  
• Module: mod_ssl
  

  This directive sets whether SSL is required for access to an object. When it is set to "on," Stronghold returns a status code of 403 (Forbidden) when clients request the object using HTTP, effectively blocking non-SSL access. The object remains accessible through HTTPS.

• Syntax: SSL_Require any|none|groupname|"field-operator-match"
  
• Context: object
  
• Module: mod_ssl
  

  SSL_Require is a powerful directive for screening client certificates. When this directive is set, Stronghold only accepts client certificates that match the SSL_Require criteria. The means of expressing the criteria are complicated in order to provide great flexibility. For example, all of these values are valid:

  SSL_Require any
  SSL_Require none
  SSL_Require "size GTE 1024"
  SSL_Require "ou EQ \"Product Development\""
  
  

  If the value of SSL_Require is a field-operator-match string or a groupname instead of "any" or "none," you can connect multiple strings using AND, OR, and NOT. You can also use multiple SSL_Require directives on separate lines. Stronghold treats these as if they were connected by the AND operator; all must be true in order for Stronghold to accept the certificate.

  Field corresponds to a data field in the certificate, and it can be one of the following:

  Field	Description
  c	The country of the certificate's subject, or owner
  sp	The state or province of the certificate's subject (deprecated; use "st" instead)
  st	The state or province of the certificate's subject
  l	The locality of the subject, such as a city, town, or rural region
  o	The organization to which the subject belongs
  ou	The organizational unit to which the subject belongs
  cn	The common name of the subject
  email	The email address of the subject
  i	A prefix denoting the issuer of the certificate, such as your private CA. For example, you can prepend it to the "ou" value to indicate the Issuer Organizational Unit, like this: SSL_Require IOU EQ "Certificate Services"
  valstt	The validity start date for this certificate
  valend	The validity end date for this certificate
  alg	The algorithm used to generate the public key for this certificate
  size	The size (in bytes) of the public key embedded in the certificate
  exp	The public key in this certificate
  sign	The algorithm used to sign this certificate

  Operator can be one of the following:

  Operator	Description
  IN	The value of field must be contained in the match string, which can be a list.
  INFILE	The value of field must be contained in a file specified by match.
  CERTINFILE	This operator takes no field, and the client certificate must be contained in a file specified by match.
  EQ	The value of field must be equal to the value of match.
  =	Same as "EQ."
  NEQ	The value of field must be unequal to the value of match.
  !=	Same as "NEQ."
  LT	The value of field must be less than the value of match.
  <	Same as "LT."
  GT	The value of field must be greater than the value of match.
  >	Same as "GT."
  LTE	The value of field must be less than or equal to the value of match.
  <=	Same as "LTE."
  GTE	The value of field must be greater than or equal to the value of match.
  >=	Same as "GTE."
  MATCH	The value of field must match the regular expression contained in match.
  NOMATCH	The value of field must not match the regular expression contained in match.

  Depending on the field and the operator, match can be a word, a list, a filename, or a regular expression.