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

How you start and stop Stronghold varies by platform. Stronghold Web Server 4.0 for Red Hat Linux Advanced Server systems uses Linux system utilities; Stronghold Web Server for cross-platform systems comes with three scripts designed to automate the starting, reloading, and shutting down of your server. These scripts 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

To start Stronghold:

On Red Hat Linux Advanced Server systems:
```
   service httpd start
```
On cross-platform systems:
```
   # bin/start-server
```

On cross-platform systems always use start-server, or read the script carefully before you decide to build your own script. If you do decide to build your own script or to start the server manually, you should know the commandline 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 container in httpd.conf.
`-d directory`	Start with an alternative `ServerRoot` directory
`-f filename`	Start with an alternative server configuration file
`-h`	Display basic usage information
`-L`	Display the list of valid configuration directives
`-l`	Display the list of modules compiled into httpd. Note that this does not include external dynamically loaded 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 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.

In order to have the server start automatically—that is, to have the machine able to reboot unattended—your server’s private key must be stored unencrypted on the disk. 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

Stronghold re-reads the configuration file when it reloads.

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

Reloading Stronghold

To reload Stronghold:

On Red Hat Linux Advanced Server systems:
```
   service httpd reload
```
On cross-platform systems:
```
   # reload-server
```

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

Stopping Stronghold

To stop Stronghold:

On Red Hat Linux Advanced Server systems:
```
   service httpd stop
```
On cross-platform systems:
```
   # bin/stop-server
```

On cross-platform systems always use stop-server, or read the script carefully before you decide to build your own specialized shutdown script.

Logs

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 returned. Reports display server statistics.

Various components of the Stronghold Web Server collect data into log files. On Red Hat Linux Advanced Server systems, these log files are found in /var/log/httpd, /var/log/tomcat, and /var/log/tux; on cross-platform systems the log files are all in var/log.

Log Rotation

Log Rotation on Red Hat Linux Advanced Server

Log rotation occurs by default on Red Hat Linux Advanced Server; it is handled by the system’s logrotate utility and configured using files in /etc/logrotate.d. Refer to the Red Hat Linux Advanced Server documentation for more information.

Log Rotation on Cross-platform Systems

Because log files grow larger and larger as they accumulate more information, you will 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.

To Rotate a Log File Manually
Move the old file:
   # mv logfile_path logfile-archive path
Reload Stronghold:
   # reload-server
Stronghold re-reads the configuration file when it reloads.
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

RotateLogs provides an automated 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 the httpd.conf file. RotateLogs works with the TransferLog, ErrorLog, CookieLog, CustomLog, SSLErrorFile, ScriptLog, AgentLog, and RefererLog directives.
Replace the directive’s filename value with a string of the following form:
   |rotatelogs logfile_path n" 
The logfile_path can be the same as the filename that was previously configured for this log. The n value is the number of seconds between log rotations, such as 86400 to rotate every 24 hours or 604800 to rotate once a week.
Save the modified configuration file.
Reload Stronghold:
   # reload-server
Stronghold re-reads the configuration file when it restarts.
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.

Access Logs

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

access_log records all normal HTTP transactions.
The location of this log is set with a CustomLog directive in the global configuration section of the httpd.conf file.
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 the httpd.conf file.

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

error_log records errors that occur during normal, HTTP transactions. Its location is set with the ErrorLog directive.
ssl_error_log records errors that occur during secure, HTTPS transactions. Its location is set with the ErrorLog 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 the httpd.conf file. 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.
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.

Protocol Logs

The default location of the SSL protocol engine log is ServerRoot/logs/ssl/ssl_engine_log. This is set with the SSLLog directive. The SSLLogLevel directive sets the level of information captured in this log, which can be none, error, warn, info, trace, or debug. For a complete description of the levels, see the SSLLogLevel directive in the Apache Desktop Reference.

A typical ssl_engine_log entry with level info looks like this:

   [19/Mar/2002 14:17:44 13456] [info]  Server: Stronghold/4.0 
   Apache/1.3.22, Interface: mod_ssl/2.8.5, Library: OpenSSL/0.9.6c

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 the %r, %i, and %c variables.

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

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.
`%I`	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 the recipient of the client request and transmission of the server response.
`%u`	The remote user, if supplied by mod_auth. The value may be invalid of the server status code is 401.
`%U`	The requested URL.
`%v`	The hostname to which served the request.
`%V`	The hostname of the request, taking into account the settings of the UseCanonicalName.
`%(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 strtime format.
`%(header)i`	The contents of the client request header specified by header.
`%(header)o`	The contents of the client request header specified by header.
`%(issuerdn)c`	The issuer of the client certificate, if being used.
`%(note)n`	The contents of a note from another module, specified by note.
`%(subjectdn)e`	The subject, or owner, of the client certificate used in a secure transaction.
`%(variable)e`	The value of the environment variable.
`%(variable)x`	The value of the environment variable especially those provided by mod_ssl.

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.

Reports

Stronghold includes the mod_status module for on-the-fly HTML status reports that provide instant access to server activity statistics.

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 that are represented by a period (.) are unused; children in use are each represented by a code:

Code Description

_ Waiting for a connection.
. Open slot with no current process.
S Starting up.
R Reading a request.
W Writing a response.
K Keepalive (waiting).
D Performing a DNS lookup.
L Logging a transaction.
G Finishing gracefully.

Code	Description
`_`	Waiting for a connection.
`.`	Open slot with no current process.
`S`	Starting up.
`R`	Reading a request.
`W`	Writing a response.
`K`	Keepalive (waiting).
`D`	Performing a DNS lookup.
`L`	Logging a transaction.
`G`	Finishing gracefully.

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

Code	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, the default with Stronghold 4.0 is to restrict access to the server status report so that only users on the local network can view it.

To Access the Server Status Report

Access http://fully_qualified_hostname:httpport/stronghold/server-status with a Web browser.
For an automatically refreshing status report, access the page as http://fully_qualified_hostname:httpport/stronghold/server-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://fully_qualified_hostname:httpport/stronghold/server-status?auto

This is useful when automatically run with a program such as log_server_status, which logs the data from the server status reports.

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 (by default, to local users only) at http://fully_qualified_hostname:httpport/stronghold/server-info