[Top] [Prev] [Next] [Last]
Download PDF:   US   UK
Download Postscript:   US   UK
Stronghold Web Server 2.4.1 Administration Guide
Chapter 1

Basic Administration

This chapter discusses basic server administration tasks, including how to



Starting and Stopping Stronghold

Stronghold Web Server comes with three scripts designed to automate the starting, restarting, and shutting down of your server. All three are located in the 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 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:

Flag Description
-C directive process directive after reading the configuration file
-c directive process directive before reading the configuration file
-D parameter start with an arbitrary parameter corresponding to an <IfDefine> container in httpd.conf; see "Containers" on page 6-3 for details
-d directory start with an alternative ServerRoot directory
-f filename start with an alternative server configuration file
-h display the list of valid configuration directives
-l display the list of currently compiled modules
-S display information about how the virtual host configurations were parsed
-t test the syntax of the configuration file, print the results, and exit without starting
-V display the current compile settings
-v display the current version number
-X start in single-process mode where the parent process does not spawn any children; for debugging purposes only

It's 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, clients must access the SSL/TLS part of Stronghold by using a URL that specifies the HTTPS protocol instead of HTTP, such as https://www.random.com/private.html.

Normally, the server does not start until you enter your pass phrase. In order to restart the server automatically-when the machine reboots unattended, for example-you need to store your unencrypted private key on disk. By default, Stronghold keeps the key encrypted for higher security. 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 script decrypts your key and then re-encrypts it with a new pass phrase:

# bin/change_pass hostname
NOTE: The change_pass script encrypts the key after changing the pass phrase. If you were storing the key unencrypted, run decrypt_key again after you run change_pass.



Restarting Stronghold

The reload-server script lets you restart the Stronghold Web Server 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 run reload-server. Note that this also means you must guard httpd.conf 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 does 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

Always use stop-server, and read the script carefully before you create 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 license block file (sh2license) and a number of subdirectories that hold server files. It is organized as follows:

Subdirectory Description
bin scripts and executables, including SSLeay and security utilities; executables that were previously in ServerRoot/utils/, ServerRoot/support/, and ServerRoot/ssl/bin/ are now located here
cache files cached when Stronghold acts as a caching proxy server
cgi-bin CGI programs and related files, including Stronghold's search engine program
cgi-src source for the programs in cgi-bin/
conf configuration files for the server, the index engine, the search engine
htdocs the default root document directory and the base for all relative URLs except those referring to user directories
icons a standard set of icons for use in directory indexes
logs Stronghold's log files, including transfer logs, error logs, and SSL/TLS logs
manual Stronghold's documentation files, in HTML, PDF, and Postscript
src server source files, including modules
ssl SSL/TLS source files, keys, certificates, and libraries
swish the SWISH indexing engine and the site index file created during installation



Using Logs and Reports

Logs provide the primary feedback from your server, collecting data about server 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

As of Stronghold 2.4, logs that are piped to other processes are more reliable. 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:

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

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 %u %l %t \"%r\" %>s %b

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" on page 1-8.



Error Logs

Stronghold keeps two error logs:

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:

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


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"


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.

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
%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; see "Client Request Headers" on page A-5
%{header}o The contents of the server response header specified by header; see "Server Response Headers" on page A-8
%{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

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

Figure 1-1: Server Status Report

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:

Code Description
_ waiting for a connection
S starting up
R reading a request
W writing a response
K keepalive (waiting)
D performing a DNS lookup
L logging a transaction

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

Column Description
Srv Server process number
PID Process ID
Acc Number of accesses for this connection / this child / this slot
M Mode of operation, indicated with one of the codes listed above
SSL The version of SSL or TLS used in this transaction, if any; either "SSLv2," "SSLv3," or "TLSv1"
CPU CPU usage in seconds
SS Seconds since the beginning of the most recent request
Conn Kilobytes transferred in this transaction
Child Megabytes transferred by this child
Slot Total megabytes transferred by this slot
Host Client host originating the request
VHost Requested virtual host
Request The most recent request
Client Cert SSL/TLS client certificate, if applicable

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:

<Limit GET POST>
 order deny,allow
 deny from all
 allow from .your.domain
 </Limit>

To access the server status report



Server Information Reports

Server information reports provide comprehensive server configuration information, including

Figure 1-2: Server Information Report

The report is accessible at http://main.host.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:

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



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 about 1 MB per 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.

NOTE: Logs configured with the CustomLog directive must be rotated manually.


To rotate a log file manually

  1. Move the old file:

    # mv logfile logfile.old
  2. Restart the server:

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


To rotate a log file using rotatelogs

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

  2. Replace the directive's filename value with a string of the following form:

    "|rotatelogs ServerRoot/logs/filename n"

    The filename can be the same as the filename that was previously configured for this log. N is the number of seconds between log rotations, such as 86400 to rotate every 24 hours or 604800 to rotate once a week.

  3. Save the modified configuration file.

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



Tracking Sessions

Since HTTP implements single, self-contained transactions, it provides no built-in way to track a whole session, 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:



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 inside 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:

  1. A client submits a request that does not include a cookie.

  2. Stronghold generates a session ID and sends it in the Set-Cookie header of its response.

  3. The client returns the cookie in the Cookie header of each subsequent request.

  4. Dynamic contents programs may read the session ID in the HTTP_COOKIE variable.

The Set-Cookie header uses this syntax:

Set-Cookie name=value; expires=date; path=pathname; domain=domain-name; secure

Attribute Description
name This is the only required attribute, and it sets the unique identifier for this session.
expires Without the expires attribute, a cookie is only used for the current session (until the browser quits). To set an expiration date and instruct the client to keep the cookie, use the CookieExpires directive.
path Without the path attribute, a cookie is only used for the URL for which it was issued. If path is set, then the cookie is valid for that URL and all its subdirectories. If path is set to "/," then the cookie is valid for the entire domain.
domain The domain attribute gives a domain range for which the cookie is valid. It does not need to be set; Stronghold automatically uses the name of the host that originated the cookie.
secure When this attribute is set, the cookie is only valid for secure transactions.


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 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 a 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 places a session identification token in the URL, instead of in the response header. The client then uses the GET request method to communicate its 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 follows a link, its 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.




[Top] [Prev] [Next] [Last]
© 1998 C2Net International
Feedback: stronghold-docs@c2.net 		C2Net Logo