Installation

This chapter describes how to set up your new Stronghold Web Server:

Stronghold System Requirements
Installing Stronghold Web Server

If you are upgrading an existing Apache or Stronghold server, install this version of the Stronghold software into a new directory as described in this chapter, then continue to either:

If you are upgrading:
If you have an existing Apache or Stronghold server on the same host, you must stop the old server or install Stronghold on ports that your server does not use.

To stop Stronghold, use the ServerRoot/bin/stop-server script or the ServerRoot/stop script, depending upon which version of Stronghold you are upgrading from.
To stop Apache, use the apachectl stop script.

Getting Started Checklist

Check your system to see if it has the recommended resources based on the requirements listed in Stronghold System Requirements.
On cross-platform systems, if you will be running Tomcat, install the JDK. See Installing on Cross-Platform Systems for instructions on downloading and installing it.
Install Stronghold for your platform by following the steps in Installing Stronghold Web Server.
Test PHP, XML, and Java configuration by running the Stronghold test pages. Follow instructions in Verifying the Stronghold Installation to run the tests.
Sign-up for your digital certificate, if one will be used. Your purchase of Stronghold 4.0 contains a coupon for a 12-month Geotrust Digital server ID. Follow the instructions on the coupon to sign-up for your ID.
Make changes to the configuration as needed by your site, including pointing the server at your document root.
Sign-up for support and register your server with Red Hat. Follow the instructions on the Registration card contained in the Stronghold box.

Stronghold System Requirements

Stronghold Web Server is available for most varieties of the UNIX operating system. However, you need a server platform that meets these system requirements:

At least 100MB of hard disk space available. You can determine the amount of hard disk space available by running the df command:
```
   df
```
At least 16MB of RAM available for even a light-traffic site. You can determine the amount of RAM available on a Red Hat Linux Advanced Server system by running the sar command. For example, to determine the amount of RAM available at 5 second intervals six times in a row, run:
```
   sar -r 5 6
```
Note that running this command on Red Hat Linux system requires that you have the sysstat package installed.

Those are the minimum requirements for running Stronghold itself. In addition, you also need:

Adequate disk space for HTML, CGI, and log files:
As your log files accumulate data over time, they occupy more disk space. The largest log files are the access logs, which occupy about 80 bytes per request, or 1MB per 10,000 requests. For example, if your site receives 200,000 hits per day, you accumulate 20MB of log entries per day. You should plan to rotate your logs regularly to control the file size of the current log, and to allow archiving of older log files to conserve disk space.
Adequate RAM to support your anticipated server load:
For moderate traffic on a Linux platform, allow at least 32MB of memory for the server. On a Solaris system, allow at least 64MB. If you plan to run a high traffic site, you need significantly more memory than the minimum; if you plan to run a light-traffic site, less memory will suffice.
Platform support for virtual hosts:
Platform support for virtual hosts is recommended, but it is not required.

Installing Stronghold Web Server

Stronghold Web Server is distributed as a single, self-contained installer file. There are two general types:

A version for Red Hat Linux Advanced Server, which is described in Installing on Red Hat Linux Advanced Server 2.1 Systems.
Other versions for all other supported platforms, which are described in Installing on Cross-Platform Systems.

Installing on Red Hat Linux Advanced Server 2.1 Systems

To install Stronghold on a Red Hat Linux Advanced Server 2.1 system:

Move to the directory where the installer program is located.
Log in as root.
Start the script from the command line:
```
   ./install
```
If you receive an error, such as Permission denied, then you must change the installer’s file permissions before continuing:
```
   chmod u+x install
```
When prompted, press [Enter] to install Stronghold.
The installer installs all of the Stronghold software, then asks if you want to enable Red Hat Content Accelerator (TUX) and Tomcat.
After you make your choices, the installer automatically starts Stronghold for you.

Continue reading at Verifying the Stronghold Installation.

Installing on Cross-Platform Systems

If you will want to run Tomcat:
The Tomcat Servlet/JSP container requires a Java Developer’s Kit (JDK), version 1.2 or above. If such a JDK is not installed, download and install one from either Sun’s Java site (http://java.sun.com) or from the IBM Java site (http://www-106.ibm.com/developerworks/java/) before continuing with the Stronghold installation.

To install the Stronghold software on systems other than Red Hat Linux Advanced Server:

Move to the directory where the installer program is located.
su to the user that you want to install the server as. This should be the same user that will start the server (usually root).
Start the script from the command line:
```
   ./install
```
If you receive an error, such as Permission denied, then you must change the installer’s file permissions before continuing:
```
   chmod u+x sh-40-
```
The installer asks you to confirm that you want to proceed with the installation process. Select Next by pressing [space].
The installer asks you to name the directory into which the Stronghold software should be installed.
Type in that directory path and press [Enter]. If the directory you enter does not exist, the program asks you to confirm that you want to create the new directory.

The directory path you enter is referred to as ServerRoot in the Stronghold documentation. Wherever you see a reference to ServerRoot, substitute the actual path that you entered here.

The installer asks you to select which optional Stronghold software should be installed.
Use the [space] bar to select or de-select packages and the arrow keys to move through the list. When you have made your selections, install the software by pressing [Enter]. You can install both PHP 3 and PHP 4. By default, PHP 4 runs; to run PHP 3 instead, you need to modify the configuration file (httpd.conf). To learn how to run both PHP 3 and PHP 4 at the same time, refer to the documentation available at: http://www.php.net/

The program installs the Stronghold Web Server and its components, and a status bar displays the installer’s progress. When the installation is complete, the program prompts you to press [Return] to continue with the configuration phase of the installation.

Configuring Stronghold

After the Stronghold software has been installed, you are prompted to configure the Stronghold server:

Enter the fully-qualified domain name of your main server host.
The installer guesses the hostname and presents this as the default; edit if incorrect.
Enter the email address of the server administrator.
The default is webmaster at the hostname you entered in the previous step.
Enter the number of the port you want to use for regular, unsecured HTTP requests.
Browsers automatically direct their requests to port 80 unless the user specifies a different port when they type the URL. To install Stronghold as an SSL-only server, enter 0 (that is, zero). If you are installing the server as root, you can choose any unused port number. If you are installing as a user other than root, you may only choose an unused port number of 1024 or above.
If the port you choose is already in use, the installer prompts you to choose a different one.
Enter the port you want to use for secure, encrypted HTTP requests.
Browsers automatically direct HTTPS requests to port 443 unless the user specifies a different port when they type the URL. If you are installing the server as root, you can choose any unused port number. If you are installing as a user other than root, you may only choose an unused port number of 1024 or above.
If the port you choose is already in use, the script prompts you to choose a different one.
The program asks you to input the root directory for the Java Developer’s Kit (JDK). You may accept the default or enter a new path; after you make your choice, press [Return].
Enter the port on which the Tomcat WARP Connector should listen. You should not need to change the default.
Enter the port on which the Tomcat WARP Connector should listen for the shutdown command. You should not need to change the default.
The program asks if you have a previous release of Stronghold.
- If you are migrating...
  If you have a server certificate from a previous release of Stronghold, the installation program alerts you to the migration information that you can find later in this manual, then continues the installation with the step that follows.
- If this is your first installation...
  If this is your first installation of Stronghold, the installation program generates a new keypair. The keypair is required to encrypt and decrypt secure communications with your customers. The key will be stored in the file: ServerRoot/conf/ssl/private/ServerName.key and the certificate will be stored in: ServerRoot/conf/ssl/certs/ServerName.cert
Enter a key size in bits, preferably 1024 bits.
When choosing key sizes:
Key sizes must either be 512 or 1024 for compatibility with certain browsers. We recommend 1024 bits. Keys larger that 1024 bits are incompatible with some versions of Netscape Navigator and Microsoft Internet Explorer, and with other browsers that use RSA’s BSAFE cryptography toolkit.
The program requires some random data from which to create a unique key pair. When prompted, enter random keystrokes until the progress bar reaches 100%. The program generates more random data based on the intervals between your keystrokes.
The program asks whether you want to request a signed certificate from a Certification Authority (CA). A signed certificate is an electronic document that verifies you are who you say you are. You must have a signed certificate in order to authenticate your site.
To generate a certificate, select Yes and continue reading at Requesting a Signed Certificate or Creating a Temporary Certificate.
If you already have a certificate from a previous Stronghold Web Server or Apache installation, select No and continue reading at Manually Upgrading to Stronghold 4.0 (or the appropriate subsection for other versions).

Requesting a Signed Certificate

On the Choose Certification Authority screen, enter your preferred choice. A Certification Authority is a trusted third party that independently verifies your identity and sells you a signed certificate.
Enter the two-letter code for your country. Some country codes may not be what you expect; for example, you should use GB in the United Kingdom. For a complete list, Country Codes.
Enter the full name of your state or province, the name of your city, town or other locality, the name of your organization, and then enter the name of your unit within the organization.

Enter the fully-qualified domain name of your site.

If your preferred CA requires you to supply a challenge password or an optional company name, enter them when prompted, otherwise press [Return].

The program prints the certificate signing request (CSR), which looks something like this:

   -----BEGIN NEW CERTIFICATE REQUEST----- 
   MIIBEzCBzgIBADB7MQswCQYDVQQGEwJVUzETMBEGA1UECBMKQ2FsaWZvcm5pYTEQ
   MA4GA1UEBxMHT2FrbGFuZDEbMBkGA1UEChMSQzJOZXQgU29mdHdhcmUgSW5jMRAw
   DgYDVQQLEwdUZXN0aW5nMRYwFAYDVQQDEw1nYWJiZXIuYzIubmV0MEwwDQYJKoZI
   hvcNAQEBBQADOwAwOAIxAJukoQhq4LanG2k+/LnRTGJAcgv9LJPsdfCsjqRs8ygo
   yaw4ucOEdx+WdnM0x36NcQIDAQABMA0GCSqGSIb3DQEBBAUAAzEABRLR6IkG70oN
   G1MnvuMDeWou4kIvc98ysjssCNKsDKsHAXBSEbfsIQs5JRNagVBW 
   -----END NEW CERTIFICATE REQUEST-----

Copy and paste this certificate request into the ordering form of your preferred CA, and follow any other specific instructions they may have.

Continue reading at Verifying the Stronghold Installation.

Creating a Temporary Certificate

Enter the two-letter code for your country.
Some country codes may not be what you expect; for example, you should use GB in the United Kingdom. For a complete list, see Country Codes.
Enter the full name of your state or province, the name of your city, town or other locality, the name of your organization, and then enter the name of your unit within the organization.

Enter the fully-qualified domain name of your site.

If your preferred CA requires you to supply a challenge password or an optional company name, enter them when prompted, otherwise press [Return].

The program prints the certificate signing request (CSR), which looks something like this:

   -----BEGIN NEW CERTIFICATE REQUEST----- 
   MIIBEzCBzgIBADB7MQswCQYDVQQGEwJVUzETMBEGA1UECBMKQ2FsaWZvcm5pYTEQ
   MA4GA1UEBxMHT2FrbGFuZDEbMBkGA1UEChMSQzJOZXQgU29mdHdhcmUgSW5jMRAw
   DgYDVQQLEwdUZXN0aW5nMRYwFAYDVQQDEw1nYWJiZXIuYzIubmV0MEwwDQYJKoZI
   hvcNAQEBBQADOwAwOAIxAJukoQhq4LanG2k+/LnRTGJAcgv9LJPsdfCsjqRs8ygo
   yaw4ucOEdx+WdnM0x36NcQIDAQABMA0GCSqGSIb3DQEBBAUAAzEABRLR6IkG70oN
   G1MnvuMDeWou4kIvc98ysjssCNKsDKsHAXBSEbfsIQs5JRNagVBW 
   -----END NEW CERTIFICATE REQUEST-----

Copy and paste this certificate request into the ordering form of your preferred CA, and follow any other specific instructions they may have.

Continue reading at Verifying the Stronghold Installation.

Verifying the Stronghold Installation

After installing Stronghold 4.0, there are some browser-based tools available for you to test certain components. To access these tools, open a browser and enter the URL: http://fully_qualified_hostname:http_port/stronghold

On the left navigation bar, the Examples section has links that test Stronghold components:

XML (AxKit): Tests your AxKit configuration.
PHP: Tests your PHP configuration.
Java: Tests your Java configuration.

The Status section has links to server status information:

Server status: Displays information about the server’s operation and the requests it has received.
Server status (XML): Enables you to save the server status to a file.
Module info: Displays the modules compiled into the server, the server version, and the core server configuration.

If you are migrating from a previous installation, continue reading at Manually Upgrading to Stronghold 4.0.