Chapter 1: Basic Administration

This chapter discusses basic server administration tasks, such as:

• Starting and Stopping Stronghold
• The Server Directory Tree
• Using Logs and Reports

Starting and Stopping Stronghold

Stronghold Web Server 3.0 comes with three scripts designed to automate the starting, restarting, and shutting down of your server. All three are located in <ServerRoot>/bin/ directory. This section shows you how to run these scripts from the command line. If you decide to customize the scripts or write your own, read the existing scripts carefully before doing so.

Starting Stronghold

The <ServerRoot>/bin/ directory contains the start-server script, which sets the appropriate configuration options and starts the server:

# bin/start-server

Always use the start-server, and read the script carefully before you decide to build your own. If you do decide to build your own script or to start the server manually, you should know the command-line flags for httpd:

It is possible to make the server automatically start when the host boots, but the method for doing this varies from one operating system to another. Consult your operating system's documentation to find out how to do this.

Remember that for secure transactions, browsers must access the SSL/TLS part of Stronghold by using a URL that specifies the HTTPS protocol instead of HTTP, such as

https://www.yourserver.com/yourpage.html

Normally, the server does not start until you enter your pass phrase. In order to restart the server automatically--i.e. have the machine able to reboot unattended--you need to store your unencrypted private key on disk. By default, Stronghold keeps the key encrypted for higher security although this is confgurable in the installation process. In order to remove the encryption, use decrypt_key, also in the <ServerRoot>/bin/ directory:

# bin/decrypt_key <hostname>

If you want to change the pass phrase for your encrypted key, use change_pass. This decrypts your key (if it is encrypted) and then re-encrypts it with a new pass phrase:

# bin/change_pass <hostname>

Restarting Stronghold

The reload-server script lets you restart Stronghold Web Server in one step:

# bin/reload-server

Because Stronghold Web Server caches your pass phrase, you do not need to enter it again when you reload-server. Note that this means you must guard your httpd.conf file carefully, to prevent unauthorized users from changing the configuration and restarting the server.

If you change your pass phrase, your cached pass phrase becomes invalid and reload-server will not work. When you change your pass phrase, you must restart by running the stop-server and start-server scripts in sequence.

Shutting Stronghold Down

To shut down the server, simply run the stop-server script:

# bin/stop-server

We recommend the use of stop-server and you should read the script carefully before creating your own specialized shutdown script.

The Server Directory Tree

When you install Stronghold Web Server, you specify a <ServerRoot> directory such as
/usr/local/www. <ServerRoot> contains the licence block file (sh3licence) and a number of subdirectories that hold server files. The directory status is organized as follows:

Using Logs and Reports

Logs provide the primary feedback from your server, collecting data about activity, who is accessing the site, which documents are being requested, how the server is performing, and which error codes are being invoked. Reports display server statistics.

By default, Stronghold Web Server compiles with the modules that implement:

• Access Logs
• Error Logs
• Cipher Logs
• Custom Logs
• Server Status Reports
• Server Information Reports
• agent logs
• referer logs

Since Stronghold 2.4, logs that are piped to other processes are more reliable than earlier versions were. If such a logging process dies or becomes "stuck," Stronghold respawns it without having to restart the parent process.

Access Logs

The access log records the transfer of information between the server and clients, including all client requests and server responses. Stronghold keeps two access logs;

• <ServerRoot>/logs/access_log records all normal, HTTP transactions.

The location of this log is set with a Transferlog directive in the global configuration section of httd.conf

• <ServerRoot>/logs/ssl/access_log records all secure, HTTPS transactions.

The location of this log is set with a TransferLog directive in the
<VirtualHost *:secure-port> container of httpd.conf

By default, access logs follow the common log format, which contains these fields:

• remote hostname or IP
• basic authentication username (if applicable)
• identd (RFC1413) username (if applicable and enabled)
• date and time
• request
• returned status code
  For a full list of status codes and their meanings, see Appendix B Server Status Codes.
• bytes sent

When the value for one of these fields is omitted because it does not apply, a hyphen (-) appears as a placeholder. For example:

mserver42.n-link.com - - [29/Oct/1996:18:17:21 -0800] "GET / HTTP/1.0" 200 2291

207.176.149.181 - - [29/Oct/1996:18:17:21 -0800] "GET /~ic/img/skullt.gif HTTP/1.0" 200 -

proxy.ozemail.net - - [29/Oct/1996:18:17:23 -0800] "GET /~pre111/api5.html HTTP/1.0" 200 244

proxy.ozemail.net - - [29/Oct/1996:18:17:23 -0800] "GET /~pre111/api6.html HTTP/1.0" 304 -

In this example, none of the transactions involved authentication, so the second and third fields are empty. In the last entry, the server sent a status code of 304 Not Modified, meaning "use local copy," and the body of the message was empty. Therefore, the byte field is also empty.

The access log, can be configured to contain a combination of fields other than the default. The log configuration directive is LogFormat, which uses a string of variables to set the type and order of the fields. The default log has the following format:

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

To configure the log, you can change the order of the field variables, remove unwanted variables, or add different ones. For a complete list of log format variables, see Custom Logs.

Error Logs

Stronghold keeps two error logs:

• <ServerRoot>/logs/error_log records errors that occur during normal, HTTP transactions. Its location is set with the ErrorLog directive.
• <ServerRoot>/logs/ssl/error_log records errors that occur during secure, HTTPS transactions. Its location is set with the SSLErrorFile directive.

The location of the error log is set during installation, but you can change it at any time by editing the ErrorLog directive in httpd.conf. This directive can also be set to "syslog" to pipe the error logs through syslogd(8), if the system supports it.

Stronghold's error log records two types of errors in two different forms:

• requests that cause the server to return an error-related status code:

[date] [error-level] [client IP] error-message

The error-level denotes the error's degree of severity. Only errors at or above the level specified by the LogLevel directive are recorded. The error-message does not include the corresponding status code, which is recorded separately in the access log. Error-related status codes are listed in "Server Errors" on page -7.

• CGI errors

location: error-message

Check the error log often to make sure no serious errors are occurring. If you like, you can monitor errors as they occur by entering the following at the command line, where error_log is the path to the log file:

# tail -f error_log

The "tail" command displays the final few lines of the log file and updates its display when changes occur.

Cipher Logs

The default location of the cipher log is <ServerRoot>/logs/ssl/cipher_log It is set with the SSLLogFile directive. A typical cipher log entry looks like this:

[11/Nov/1997:13:55:42 -0800] SSLv3 RC4-MD5 reused 0
"ok" "/O=C2Net/CN=Sonya L. Jo/Email=sony@c2.net"

• date, time, and time zone offset (from GMT).
• SSL/TLS version number for this transaction, either "SSLv2", "SSLv3", or "TLSv1"
• cipher used to encrypt this transaction.
• "new" or "reused," depending on whether the SSL session was newly negotiated between the browser and server or resumed from the session cache (at the browsers request).
• verification status code: "0" if verification succeeded.
• verification status: "ok" if certificate verification succeeded, or an error message if verification failed.
• contents of the Organization, Common Name, and E-mail fields of the client certificate presented for this transaction, if any.

Custom Logs

The CustomLog directive can be used to create multiple logs in custom formats. The value for CustomLog is a path followed by a string of variables or the name of a log format defined by a LogFormat directive. Each variable specifies the content of a log field.

The valid format variables are as follows. Note that no escaping is performed on the strings from %r, %i, and %c

The sequences \t and \n can also be used in custom log formats. These will be replaced in the log file respectively.

The percent sign (%) can be followed by one or more comma-separated HTTP status codes as conditions of the log field. For example:

CustomLog logs/customlog %400,501{User-Agent}i

This example logs the contents of the User-Agent header when a 400 (Bad Request) or 501 (Not Implemented) error occurs. The status code can be preceded by a "!" to exclude certain conditions from logging. For example:

CustomLog logs/customlog %!200,304,302{Referer}i

This example logs the referring URL for all requests that do not return a normal status code such as 200 OK, 302 Moved Temporarily, or 304 Not Modified.

Server Status Reports

Stronghold includes the mod_status module for on-the-fly HTML status reports that provide instant access to server activity statistics. Although mod_status is compiled into Stronghold by default, status reports are turned off to conserve server resources. To enable status reports, set the ExtendedStatus directive to "on."

A status report includes:

• the current date and time
• the date and time when the server was last started or restarted
• the server uptime
• the total number of accesses
• the total traffic volume
• the CPU usage
• the average number of requests per second, average volume per second, and average volume per request
• the number of requests currently being processed
• the current number of idle children
• a snapshot of the ScoreBoardFile

The snapshot of the ScoreBoardFile has two parts: a quick summary in ASCII and a detailed report in tabular form. Each character in the quick summary represents one child process. Children represented by a period (.) are unused but available as determined by the MaxSpareServers directive. Children in use are each represented by a code:

The same codes are reflected in the table, which gives the following details about each child:

For security purposes, restrict access to the server status report so that only users on the local network can see it. To do this, locate the following container in httpd.conf

<Location /stronghold-status>
SetHandler server-status
</Location>

Add the following inside the container:

order deny,allow
deny from all
allow from .your.domain

• Access http://your.server.name/stronghold-status/ with a Web browser.
• For an automatically refreshing status report, access the page as
  http://your.server.name/stronghold-status?refresh=n where n is the number of seconds in a refresh cycle.
• For a machine-readable version of the status file, access
  http://your.server.name/stronghold-status?auto

Server Information Reports

Server information reports provide comprehensive server configuration information including:

• a list of the modules currently compiled into the server
• the server version
• the core server configuration
• the available configuration for each module
• the current configuration for each module
• additional information about modules, if configured with AddModuleInfo

The report is accessible at http://your.server.name.com/stronghold-info/ To keep the server information report confidential, add allow and deny directives to the <Location/server-info> section of httpd.conf It's especially important to consult this report during server configuration in order to verify that the directives you use are supported by the modules that are currently compiled into the server.

Optional Logs

Two optional logs are available:

• Agent logs record the client used for each request in order to track which browsers visitors are using. They are supported by mod_log_agent and configured with the AgentLog directive.
• Referer logs record the links users follow to reach a site. This is useful to determine which sites link to your site and how many users are following these links to your site. Referer logs are supported by mod_log_referer and configured with the RefererLog directive.

Keep in mind that these logs can also be implemented using the CustomLog directive described in Custom Logs on page 1-9

Rotating the Logs

Since log files grow larger and larger as they accumulate more information, you'll eventually need to rotate the logs so that no single log file becomes too large. The access log, for example, occupies approximately 1 MB for each 10,000 requests. After several hundred thousand requests, the access log can become unwieldy and difficult to manage. Logs can be rotated manually or by using the automatic rotatelogs utility.

• Move the old file:

# mv <logfile path> <logfile-archive path>

• Restart the server:

# bin/reload-server

Each time a log file is manually moved or deleted, the server must be restarted. If not, the log file may become corrupted.

RotateLogs provides a more elegant method to cycle the log files periodically, to keep them manageable and does not require Stronghold to be restarted.

• Locate the log file's directive in httpd.conf Rotatelogs works with the
  TransferLog, ErrorLog, CookieLog, SSLLogFile, SSLErrorFile, ScriptLog, AgentLog, and RefererLog directives. It does not work with
  CustomLog.
• Replace the directive's filename value with a string of the following form:
  "|rotatelogs <logfile path> n"

• Save the modified configuration file.
• Restart the server:

# reload-server

Every n seconds, rotatelogs creates a new log file named filename.nnnn, where "nnnn" is the system time when the log starts. When log rotation is handled by rotatelogs, the server does not need to restart each time logs are rotated, as rotatelogs is given responsibility for filing log messages in the appropriate log file.

Tracking Sessions

Since HTTP implements single, self-contained transactions, it provides no built-in way to track a users session through their use of the website which consists of more than one transaction. Exchanges of requests and responses occur individually, and each exchange appears to be unrelated to the last. However, today's complex, interactive web applications require session tracking in order to implement features such as site customization, preference tracking, and so on.

For example, many online commerce sites implement a "shopping basket" that keeps track of the items each user chooses, compiling a list of all the items chosen by each user during the course of his or her entire session. Without session tracking, a shopper would only be able to purchase one item at a time through a single self-contained HTTP transaction, To keep track of requests that originate with the same client, servers set session identifiers that accompany each request and response. Requests with the same session ID belong to the same session.

There are two ways to perform session tracking:

• Cookies, which pass the session ID in the HTTP header
• The PATH_INFO variable, which encodes the session ID in the URL

Session Tracking with Cookies

Cookies, supported by the mod_usertrack module, are session IDs that are exchanged as HTTP metainformation. When the CookieTracking directive is set to "on," Stronghold automatically generates a session ID whenever it receives a request that does not already include a cookie. Depending on whether it appears outside a container, CookieTracking can apply to the whole server, a single virtual host, or only an object such as a directory or file. A session that uses cookies works like this:

• A client submits a request that does not include a cookie.
• Stronghold generates a session ID and sends it in the Set-Cookie header
  of its response.
• The client returns the cookie in the Cookie header of each subsequent request.
• Dynamic content programs may read the session ID in the HTTP_COOKIE variable.

The Set-Cookie header uses this syntax:

SetCookieName=[value];[expires=date;][path=pathname]
[domain=domainname;][secure]

Stronghold sets only the name field and the domain field, unless httpd.conf contains the CookieExpires directive. Without this directive, cookies are deleted when the client quits and Stronghold issues a new one at the beginning of the next session. When CookieExpires is set, Stronghold sends the expires field and the client server saves the cookie until it expires.

Taking advantage of cookies to produce dynamic, customized content requires external programs that control content based on session IDs. Whenever a cookie is set for the current session, each client request includes the Cookie HTTP header. For example:

Cookie: name=gw427516826238200437

By reading the HTTP_COOKIE environment variable, a program can track related requests and produce dynamic content based on multiple requests over the course of the same session.

The CustomLog directive sets the path and format of any log. It can be used to log cookies to a file. For example:

Customlog logs/clickstream "%[cookie]i %r %t"

In this example, each entry in the clickstream log file shows the contents of the Cookie header, the first line of the request, and the time. If you like, you can create a more detailed cookie log, or combine cookie logging with another log.

Session Tracking with PATH_INFO

The PATH_INFO variable can be used to place a session identification token on the URL, instead of the response header. The client then uses the GET request method to communicate it's token to the server, instead of the Cookie header described in the previous section. This method accommodates older browsers that do not support cookies, as well as users who do not accept cookies.

For each initial request, a program must generate a new token, then create an HTML page with the token embedded in the URL of every link. When the user URL tells the program to generate another page with the same token embedded in its links. The token is passed from page to page throughout the session.