[Top] [Prev] [Next] [Last]
PS PDF
Chapter 1

The Configuration Manager

Stronghold's Configuration Manager is a Web-based interface to the server configuration file. Normally, you change the server configuration by manually editing the configuration file. Chapter 2 shows you how to do this. As an alternative, you can use the Configuration Manager's convenient graphical interface.

This chapter shows you how to



Starting and Stopping the Configuration Manager

By default, the installation scripts start the Configuration Manager when they start your new Stronghold server. If the Configuration Manager is not running, you can start it by running the start-adm script from the ServerRoot directory:

# ./start-adm

To stop the Configuration Manager, run stop-adm:

# ./stop-adm

The Configuration Manager reads the server configuration file when it starts.

NOTE: If you edit the configuration file manually, you must stop and start the Configuration Manager in order to allow it to read your changes.



Accessing the Configuration Manager

There are two ways to access the Configuration Manager:



Configuring Stronghold Web Server

This section explains how to

The front page of the Configuration Manager includes a link to the main configuration menu, plus four shortcuts:

Figure 1-1: The Configuration Manager

As you traverse the menus of configuration categories, you find lists of configuration options. Each option is explained in a brief paragraph and includes a text box, check box, pull-down menu, or other form element that makes it simple to enter your preferences:

Figure 1-2: Configuration Options

Each option is followed by a short description that explains how the option affects your server's behavior. Each option corresponds to a configuration command called a directive, which appears in the configuration file when you finalize your changes. Chapter 3 contains the complete list of all valid directives.


To change the server configuration

  1. Use the online form to change the value of a configuration directive.

  2. Click the Set button.

    Each configuration option or set of options is accompanied by a Set button. Each time you change an option, you must click its Set button in order to enter the new setting. This saves the setting until you are ready to write all your changes to the configuration file.

  3. Continue changing configuration directive values and setting them until you are finished.

    If you make a mistake, simply correct it and click the Set button again.

  4. Return to the main configuration menu at https://www.hostname.com:444/cgi-bin/config.py.

  5. Click the Write Configuration File button

    This finalizes your changes. Once you do this, your changes cannot be undone. It's a good idea to back up the configuration file before clicking this button.

  6. Go to the Server Start/Stop page.

    You can reach this page from the front page of the Configuration Manager or by entering its URL: https://hostname:444/cgi-bin/config.py?view=AdminManager.

  7. Click Reload.

    This step causes Stronghold to reread the configuration file and implement your changes.



The Main Configuration Menu

When you access the main configuration menu, you find five configuration categories:

Category Description
Global server configuration The configuration that controls your main host,the server's global options., and the default behavior of virtual hosts. See "Global Server Configuration" on page 1-6.
Virtual host configuration Configurations that control the individual hosts supported by your server. See "Virtual Host Configuration" on page 1-7.
Per-directory configuration Individual configurations for directories denoted by absolute paths. See "Per-Directory Configuration" on page 1-10.
Stronghold modules The configuration that sets which modules are compiled into your server binary. See "Module Configuration" on page 1-11.

At the bottom of the main menu page is the Write Configuration File button. Whenever you finish modifying the configuration for your main server, virtual hosts, or directories, you must click this button and restart Stronghold in order to implement your changes. If you change your mind before you click this button, you can undo your changes by restarting the Configuration Manager as described in "Starting and Stopping the Configuration Manager" on page 1-1.



Global Server Configuration

The global server configuration control the default behavior of all hosts on your server. Your main host always behaves according to this configuration. Your virtual hosts also follow the global configuration, except when they have their own configurations. The values of the directives in virtual host configurations override the values of the directives in the global configuration.


To edit the global server configuration

  1. From the front page or the main menu, click Global Server Configuration.

    The Global Server Configuration page appears, listing 14 configuration categories:

    • server performance tuning

    • server identity

    • cryptography configuration

    • files and directories

    • file types, actions, and encodings

    • directory aliasing and URL redirection

    • access control

    • log file management

    • directory indexing

    • CGIs and server-side includes

    • miscellaneous items

    • valid directives

    Click this category to go directly to a linked list of all valid per-directory configuration options.

    • optional features

    • location-based configuration

  2. Follow a category link to reach the configuration directives for that category.

  3. Edit the configuration options.

  4. Return to the main menu.

  5. Finalize your changes by clicking Write Configuration File.



Virtual Host Configuration

Virtual hosts are additional domains that reside on the same host as your main server. You may also have default virtual hosts whose configurations apply when no other matching configuration is present, or wildcard virtual hosts whose configurations apply to all other virtual hosts. Since each host can have its own configuration, you must set the configuration for each virtual host separately.

From the main menu, you can


To add a new virtual host

  1. Make sure you have set up system support for the new virtual host.

    The means for setting up system support for virtual hosts varies with your operating system and local Domain Name Service (DNS) facilities. For specific instructions, consult your operating system documentation. You can also find more information about different types of virtual hosts in "Configuring Virtual Hosts" on page 2-10.

  2. Go to the main configuration menu at https://www.hostname.com:444/cgi-bin/config.py.

  3. Under "New Virtual Server," enter the hostname of the new virtual host.

  4. Enter the port number for non-SSL transactions for this virtual host.

    Unless you are implementing port-based virtual hosts, this is usually port 80.

  5. Click Create New Virtual Host.

    The main configuration menu reappears with the new virtual host and port number added to the list of existing virtual hosts. This host is now ready for configuration.

  6. If the virtual host will also be performing SSL transactions, enter its name again.

  7. Enter the port number for SSL transactions for this virtual host.

    Unless you are implementing port-based virtual hosts, this is usually port 443.

  8. Click Create New Virtual Host.

    The main configuration menu reappears with the new virtual host and port number added to the list of existing virtual hosts. This host is now ready for configuration.

Secure transactions and unsecured transactions take place on separate ports and must be configured separately. Therefore, each virtual host has two configurations: one for its unsecured port and one for its SSL-secured port. If you do not enter a virtual host configuration for both ports, the host inherits the global configuration when operating on the unconfigured port.


To configure a virtual host

  1. On the main configuration menu, click the virtual host link for the port you want to configure.

    For example, click virtual.host.com port:80 to set the unsecured configuration for that host, or click virtual.host.com port:443 to set its SSL-secured configuration.

    When the virtual host configuration page appears, it shows you 14 different configuration categories:

    • server identity

    • cryptography configuration

    • files and directories

    • file types, actions, and encodings

    • directory aliasing and URL redirection

    • access control

    • log file management

    • directory indexing

    • CGIs and server-side includes

    • miscellaneous items

    • valid directives

    Click this category to go directly to a linked list of all valid per-directory configuration options.

    • optional features

    • location-based configuration

    • directory-specific configuration

  2. Edit the virtual host configuration.

  3. Return to the main menu.

  4. Finalize your changes by clicking Write Configuration File.



Per-Directory Configuration

Per-directory configurations affect individual directories and their subdirectories. The most common use for these configurations is access control. For example, if you have a set of files that should be accessible only to a certain group of users or hosts, you are likely to place them all in one directory, or in subdirectories of one directory.

From the main menu, you can


To delete a per-directory configuration

  1. In the list of per-directory configurations, locate the one you want to delete.

  2. In the Eliminate column, click the "x" next to the per-directory configuration you want to delete.

    The Configuration Manager reloads the page. The per-directory configuration no longer appears in the list.

If you change your mind before you finalize your changes, you can undo the deletion by restarting the Configuration Manager as described in "Starting and Stopping the Configuration Manager" on page 1-1. Keep in mind that once you write your changes to the configuration file, any per-directory configuration you have deleted is permanently lost.


To add a per-directory configuration

  1. Make sure the directory you want to configure already exists within your ServerRoot directory tree.

    If it does not, create it using the mkdir command:

    # mkdir directory
  2. In the text box on the main menu, enter the full path to the directory you want to configure.

    The path must be an absolute path that begins with a slash (/).

  3. Click Create Directory.

    The Configuration Manager reloads the page. The path you entered appears in the list of per-directory configurations.

Any new per-directory configuration you create is empty until you edit it. An empty configuration inherits the global server configuration, or a virtual host configuration if it lies within a virtual host's root document directory.


To edit a per-directory configuration

  1. From the list of per-directory configurations, click the one you want to edit..

    The Directory Configuration page appears. It shows you seven different configuration categories:

    • per-directory access control

    • per-directory file types

    • directory indexing

    • CGIs and server-side includes

    • miscellaneous

    • valid directives

    Click this category to go directly to a linked list of all valid per-directory configuration options.

    • optional features

  2. Edit the configuration.

  3. Return to the main menu.

  4. Finalize your changes by clicking Write Configuration File.



Module Configuration

The configuration page for Stronghold's modules consists of a list of all the modules that come with Stronghold, each with a check box and a Set button. The Configuration Manager uses the information on this page to determine which modules are currently compiled into the server. For information on recompiling Stronghold Web Server with a different module set, see Chapter 4.

Only the directives implemented by currently compiled modules can be used by Stronghold. The Configuration Manager displays only those directives when you are configuring the server.


To change the compiled module suite

  1. Go to the Module Configuration page at https://www.hostname.com:444/cgi-bin/config.py?facet=modules.

  2. For each module that you have added to the compiled module suite, check the box next to its name.

  3. Click the Set button next to the check box.

    Whenever you check or uncheck a module, you must click its Set button in order to inform the Configuration Manager about changes in your compiled module set.

  4. For each module that you have removed from the compiled module suite, uncheck the box next to its name.

  5. Click the Set button next to the check box.

You do not need to write to the configuration file or restart the server to implement these changes.



Keys and Certificate Enrollment

"Site Certificates and Keys" on page 6-10 describes encryption key pairs and site certificates in detail, and shows you how to manage these from the command line. With the Configuration Manager , you can perform two basic key and certificate management functions:


To start a new certificate request

  1. From the front page, click Keys & Certificate Enrollment.

  2. Under "Start a New Certificate Request," enter the following:

    • the fully-qualified domain name of the host or virtual host that will own this key pair and certificate

    • a key size, in bits

    For the highest degree of security, we recommend the largest key size available: 1024 bits.

  3. Click Generate Key.

    When key generation is finished, the new key pair is saved at ServerRoot/ssl/private/hostname.key and the temporary certificate form appears. The information you enter here is used to generate a Certificate Signing Request (CSR) and a temporary site certificate. See "Site Certificates and Keys" on page 6-10 for more information about CSRs and temporary site certificates.

  4. Enter the following information about the host or virtual host that will own this key pair and site certificate:

    • country code

    This is a two-letter code, such as JP for Japan or AT for Austria. For the complete list of country codes, see Appendix C.

    • state or province name

    • locality name

    • organization name

    • organizational unit name

    • common name

    This should be the same as the fully-qualified domain name you entered on the last page.

    If you do not want a temporary certificate, fill in these fields and select Skip Test Cert Generation. The information will be used to generate a CSR but not a temporary certificate.

  5. Click Next.

    Another page appears, informing you that test certificate generation was successful.

  6. Click Generate Cert Request.

    The Configuration Manager uses your test certificate information to generate a request for a signed certificate, then displays this request on the next page.

  7. Select the entire Certificate Signing Request (CSR), which looks something like this:

    -----BEGIN CERTIFICATE REQUEST-----
     MIIBLTCB2AIBADBzMQswCQYDVQQGEwJVUzETMBEGA1UECBMKQ2FsaWZvcm5pYTEP
     MA0GA1UEBxMGTXlCdXR0MRAwDgYDVQQKEwdZZXJCdXR0MRQwEgYDVQQLEwtZZXJN
     b21zQnV0dDEWMBQGA1UEAxMNc21hcnR5LmMyLm5ldDBcMA0GCSqGSIb3DQEBAQUA
     A0sAMEgCQQDQHGv4P3P25rzQQ77RPVtuJ0+ItbT4ManxZSAN98n/ZTdQ7Rsv6RUK
     sU3a+z0tEG8yE5ovkufRuXlGua7iwCPjAgMBAAGgADANBgkqhkiG9w0BAQQFAANB
     AFzYDnOaFiY/loKVWuQgI05OFzzyikB+Cz9Qv4W4Jm3tprCgoT7FA7E2kO3hSFWm
     g+BS1QSqOOBYBzDnTKQVJDQ=
     -----END CERTIFICATE REQUEST-----
  8. Click one of the links to the two major CAs, either Verisign or Thawte, or use another CA.

  9. Follow the instructions on your CA's certificate request pages.

When your CA responds by emailing you your signed certificate, you must install it in order to authenticate the host.


To install a certificate

  1. From the front page, click Keys & Certificate Enrollment.

  2. Under "Install a Signed Certificate," enter the fully-qualified domain name of the host whose certificate you want to install.

  3. Copy the entire email that you received from your CA.

    The text you copy is your site certificate. It should begin with this line

    -----BEGIN CERTIFICATE-----

    and end with this line

    -----END CERTIFICATE-----
  4. Paste the site certificate into the Cert box.

  5. Click Install Cert.

    Another page appears, informing you that your certificate has been installed.



Starting, Stopping, and Reloading the Server

The Start/Stop/Reload shortcut on the front page of the Configuration Manager leads you to a list of three links:

You can also reach this page by entering its URL: https://hostname:444/cgi-bin/config.py?view=AdminManager.

To start, stop, or reload the server, you only need to click the corresponding link. If you have changed the server configuration and written your changes to the configuration file, reloading the server implements your changes.

If you receive an error when starting or restarting Stronghold Web Server, see Chapter 8 for troubleshooting information.



Securing the Configuration Manager

The security of your Configuration Manager is crucial. If it is not properly secured, an intruder can reconfigure the server and gain access to your site. In order to protect your server, all transactions between your client and the Configuration Manager must be encrypted and authenticated. This section shows you how to



Encryption

By default, the Configuration Manager encrypts all transactions when you access it through the Stronghold Web Server.

If your Stronghold Web Server is not running and you must access the Configuration Manager through its own mini-server, remember that the mini-server does not support SSL encryption or authentication. To protect the Configuration Manager during these unencrypted transactions, the mini-server only responds to the hosts listed in the ServerRoot/conf/hosts.conf file. By default, this file contains only "localhost," meaning that you can only access the mini-server directly from the server platform. This prevents your transactions from entering any network. If you must add other hosts to this file, do so with caution. We recommend adding only hosts that reside behind your firewall.

When accessed through the Stronghold Web Server, the Configuration Manager inherits the server's global configuration for encryption. For example, the Configuration Manager's default configuration permits weak ciphers if your global server configuration permits them. However, you may find it necessary to configure your server to accomodate clients that do not support strong ciphers. If so, you should set the Configuration Manager's ciphers separately to prevent it from using weak cryptography.


To set the Configuration Manager ciphers

  1. From the Configuration Manager's front page, click Enter.

  2. On the main menu page, locate the Virtual Host section.

    The Configuration Manager appears in the virtual host list as a default host:

    _default_ port: 444

    Port 444 is the default Configuration Manager port. If you have configured the server to use a different port for the Configuration Manager, look for that port number in the virtual host list.

  3. Click the Configuration Manager host in the virtual host list.

    The Virtual Host Configuration page appears.

  4. Click Modify Security Settings.

    The Virtual Server Cryptography Configuration page appears.

  5. Move to the Allowed Ciphers and Signatures section.

    This is where you specify the ciphers that the Configuration Manager is allowed to use.

  6. Enter a colon-separated list of strong ciphers or cipher aliases in the text box.

    Use the cipher abbreviations in the table on page 3-87 and the cipher aliases on page 3-89. Be sure to choose only the strongest ciphers. For example, you can use the cipher alias "HIGH" to denote all high-security ciphers.

  7. Click Set Required Cipher Suite.

  8. In the navigation bar at the bottom of the page, click Configuration Home Page.

    The main menu appears.

  9. Click the Write Configuration File button to finalize your changes.

  10. Restart the server to implement your changes.

The client that you use to access the Configuration Manager must support the ciphers you set here.



Authentication

The Configuration Manager is password-protected by default, but this is a weak form of authentication. Client certificate authentication is much more reliable. As soon as possible, you should configure the server to require client certificate authentication for access to the Configuration Manager.

In order to set up client certificate authentication, you must first obtain a client certificate for yourself and any other authorized server administrator. If you have a private Certification Authority (CA), you can issue yourself a client certificate. This also makes it easier to restrict access, since you can configure the server to allow only clients certified by your private CA. For more information, see "Private Certification Authorities" on page 6-30.

If you do not have a private CA, you can obtain a client certificate from one of these widely recognized CAs:

Once you have your client certificate, you can configure Stronghold Web Server to provide access to the Configuration Manager only to clients that present your certificate.


To configure client certificate authentication

  1. From the Configuration Manager's front page, click Enter.

  2. On the main menu page, locate the Virtual Host section.

    The Configuration Manager appears in the virtual host list as a default host:

    _default_ port: 444

    Port 444 is the default Configuration Manager port. If you have configured the server to use a different port for the Configuration Manager, look for that port number in the virtual host list.

  3. Click the Configuration Manager host in the virtual host list.

    The Virtual Host Configuration page appears.

  4. Click Modify Security Settings.

    The Virtual Server Cryptography Configuration page appears.

  5. Move to the Client Certificate Details section.

    This is where you specify client certificate authentication options.

  6. In the Client Authentication Setting box, enter "2."

    This instructs the server to require a client certificate before fulfilling any request.

The next step depends on whether you have a certificate signed by your private CA or one that is signed by a public CA.


To configure access control for a private CA certificate

  1. Save your private CA's site certificate in the CA directory. Give it a recognizeable filename, such as "privateCA.pem."

  2. On the Virtual Server Cryptography Configuration page, locate the Trusted Roots File box.

  3. Enter "CA/privateCA.pem."

    This instructs the server to accept only client certificates signed by your private CA when granting access to the Configuration Manager.

  4. In the navigation bar at the bottom of the page, click Configuration Home Page.

  5. Click the Write Configuration File button to finalize your changes.

  6. Restart the server to implement your changes.


To configure access control for a public CA certificate

  1. In the navigation bar at the bottom of the page, click Configuration Home Page.

  2. Click the Write Configuration File button to finalize your changes.

  3. Use a text editor to open the configuration file:

    # vi ServerRoot/conf/httpd.conf
  4. Locate the following section:

    <VirtualHost _default_:444>
     . . .
     </VirtualHost>

    The directives between these angle-bracketed tags configure the Configuration Manager.

  5. Between the angle-bracketed tags, insert the following directive:

    SSL_Require "email = \"yourlogin@hostname\""

    This instructs the server to accept only certificates that are associated with your email address. Since CAs will only issue one certificate per email address, this value matches only your certificate.

    To allow multiple certificates, you can enter separate SSL_Require directives

    SSL_Require "email = \"login1@hostname\""
     SSL_Require "email = \"login2@hostname\""

    or use the OR operator to support multiple values for one directive:

    SSL_Require "email = \"login1@hostname\"" OR "email = \"login2@hostname\""
  6. Save the modified configuration file.

  7. Restart the server to implement your changes.

  8. Restart the Configuration Manager to allow it to read your changes.



Configuration Manager Logs

All Configuration Manager logs reside in the ServerRoot/logs/confsrvr directory. In order to make sure that no unauthorized users or hosts have accessed the Configuration Manager, and that it is using the appropriate ciphers, you should check these logs periodically.

When you access the Configuration Manager through the Stronghold server, Stronghold logs all transactions to a set of four logs:

Log File Description
access_log Logs each request that is directed to the Configuration Manager.
error_log Logs server errors related to requests that are directed to the Configuration Manager.
cipher_log Logs SSL transaction information.
ssl_error_log Logs SSL transaction errors.

When you access the Configuration Manager directly through its mini-server, it logs all transactions to the direct_log file. It is similar in format to the access_log, except for special entries that appear when errors occur. If you are accessing the Configuration Manager through its mini-server or it is not responding to requests through Stronghold, use this log to diagnose problems.




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