Back | Next | Contents Cams Web Agent Guide

Apache 2.0 Solaris Web Agent Integration

Cams web agents are integrated into web and application servers to protect the resources that they provide. When a user's web browser makes a request to a web or application server, the Cams web agent asks a Cams policy server if access is granted or denied. The Cams web agent enforces the decision, possibly prompting the user for authentication if required.

This document provides instructions on how to install and configure the Cams Apache 2.0 Solaris web agent, which is an Apache version 2.0.x module supporting:

  • Apache "prefork" Multi-Processing Module (MPM)
  • Solaris 8, 9, 10 for SPARC 64-bit

The Cams Apache 2.0 Solaris web agent supports the prefork Apache 2.0 Multi-Processing Module (MPM). Support for the worker and perchild MPMs is not currently available. See the Apache 2.0 documentation for more information on MPMs. If you need support for another operating system, hardware architecture, or MPM, please contact Cafésoft support.

NOTE: For known issues with the Cams Apache 2.0 Solaris web agent, see ReleaseNotes.html found in the root directory of the Cams Apache 2.0 Solaris web agent distribution.

Installation

These instructions guide you through the installation of the Cams Apache 2.0 Solaris web agent on a system with Apache 2.0.x already installed. If Apache is not yet installed, you must first do so. You must also download the Cams Apache web agent.

To identify your Apache server version, open a Solaris shell and change directories to the location where Apache 2.0.x binaries are installed and use the following command:

./httpd -V

Among other information, you should see lines that looks like this:

Server version: Apache/2.0.52
Server built: Jan 6 2005 10:33:13
Server's Module Magic Number: 20020903:9
Architecture: 64-bit
...

Your Apache 2 server version is compatible with the Cams Apache 2 Web Agent distribution if the server version starts with 2.0. (e.g. 2.0.50, 2.0.53, etc.) and the major part of the Magic Number (20020903) matches exactly. It's OK if the minor part of the magic number (the part after the colon character) differs for your server. If your Apache 2 server Magic Number is different, contact Cafésoft support to determine if another Cams web agent distribution is available for your environment. In addition, the Apache 2 httpd executable and libraries must have been compiled and linked for 64-bit use. If you're not sure, use the "file" command as shown below to confirm that the httpd program is a 64-bit executable:

file ./httpd

Output from the command should look like this:

./httpd: ELF 64-bit MSB executable SPARCV9 Version 1, dynamically linked, not stripped

If the file command indicates that your Apache web server executable is a 32-bit executable, then download and install the 32-bit version of the Cams Apache 2 Web Agent for Solaris.

Confirming Availability of OpenSSL

The Cams Apache 2.0 Solaris web agent requires the installation of OpenSSL libraries on your system to encrypt sensitive values sent to and received from the Cams policy server. These libraries may be installed in a standard system directory like /usr/lib or in a non-standard system directory hierarchy like /usr/local/ssl/lib.

Use a command like the following to look for existing OpenSSL libraries:

ls -laF /usr/lib/libssl*

If OpenSSL is installed, you should see a listing that looks something like this:

lrwxrwxrwx 1 root other 15 Jan 28 16:40 /usr/lib/libssl.so -> libssl.so.0.9.8*
-rwxr-xr-x 1 root other 232044 Feb 10 13:59 /usr/lib/libssl.so.0.9.8*

If OpenSSL is not installed in directory /usr/lib, it may be installed in directory /lib, /usr/local/ssl/lib, /opt/ssl/lib. This directory is often customized by sites that build and install OpenSSL from source.

OpenSSL also includes a cryptography library that is needed by the Cams Apache 2.0 Solaris web agent. The cryptography library version must be the same as the SSL library version. The following command can be used to confirm its availability:

ls -laF /usr/lib/libcrypto*

If the OpenSSL cryptography library is installed, you should see a listing that looks something like this:

lrwxrwxrwx 1 root other 18 Jan 28 16:40 /usr/lib/libcrypto.so -> libcrypto.so.0.9.8*
-rwxr-xr-x 1 root other 1311816 Feb 10 13:59 /usr/lib/libcrypto.so.0.9.8*

In addition, your OpenSSL libraries must be 64-bit compatible or they will not be successfully loaded by the Cams Apache 2 Web Agent. If you're not sure, use the "file" command as shown below to confirm that your OpenSSL libraries are compiled/linked for 64-bit use:

file /usr/lib/libcrypto.so.0.9.8

Output from the command should look like this:

... ELF 64-bit MSB dynamic lib SPARCV9 Version 1, ...

If the file command indicates that your OpenSSL libraries are compiled for 32-bit use, then you must either find the 64-bit version of the libraries on your system or create them by downloading OpenSSL source code and compiling it for 64-bit use.

Unpacking Distribution Files

The following instructions assume you are using Apache server version 2.0.52. Substitute the appropriate file name for your downloaded Cams Apache 2.0 Solaris web agent distribution.

You'll need to copy cams-webagent-apache2_0_52-prefork-solaris-sparc-64bit-3.2.X.tar.gz to a temporary directory on the target host. You must login as root and navigate to the directory where you copied the cams-webagent-apache2_0_52-prefork-solaris-sparc-64bit-3.2.X.tar.gz file and unpack it into the temporary directory.

cd /tmp
gunzip cams-webagent-apache2_0_52-prefork-solaris-sparc-64bit-3.2.X.tar.gz
tar xvf cams-webagent-apache2_0_52-prefork-solaris-sparc-64bit-3.2.X.tar

Change directories to cams-webagent-apache2_0_52-solaris-sparc-64bit-3.2.X. The files shown in Figure 1 should have been extracted from the distribution.

<!-- Cams Apache web agent documentation and license -->
LICENSE
ReleaseNotes.html
README.txt
install-webagent.sh

<!-- Cams Apache web agent configuration files -->
conf/cams-webagent.conf
conf/webagent.properties
conf/access-control.properties

<!-- Cams Apache web agent cgi-bin files -->
cgi-bin/cams-login.pl
cgi-bin/cams-slo.pl
cgi-bin/camstest.pl

<!-- Cams Apache web agent image files -->
images/slo.gif

<!-- Cams Apache web agent libraries -->
lib/libcscrypto.so.0.9.7
lib/libcscrypto.so.0.9.8
lib/libcscore.so.0
lib/libcsconv_iconv_1_0.so
lib/libcams.so.0
lib/libcams-common.so.0
lib/libcamsclient_mt_cams_3_0.so.0
lib/mod_cams_apache20_prefork.so
lib/mod_cams_client_cert_lookup.so

Figure 1 - Directory listing of the Cams Apache 2.0 Solaris web agent files after unpacking

The target directories into which these files are copied may be a function of both the versions of Solaris and Apache you are using. For example, the standard Apache 2.0 installation would have directories:

/usr/local/apache2/conf - the Apache configuration files
/usr/local/apache2/lib - the Apache libraries
/usr/local/apache2/modules - the Apache modules
/usr/local/apache2/cgi-bin - the cgi-bin scripts
/usr/local/apache2/htdocs - the web pages

Installing the Agent

The Cams Apache 2.0 Solaris web agent is installed using a shell script. The installation script attempts to find the Apache 2.0 web server executable (httpd) by looking in standard directories or by accepting a custom path typed in by you. Once the Apace 2.0 httpd executable is found, the script will identify the important installation directories and prompt you to confirm the copying of various Cams Apache 2 web agent files.

If an existing agent module and/or libraries are found from a previous Cams Apache 2 Web Agent installation, they will be removed. If an existing Cams web agent configuration file is found from a previous installation, you will be prompted to use the existing file or to save it using a ".save" file extension. NOTE: If you choose the use the existing configuration file, you must be certain that it is fully compatible with the new Cams Apache 2 Web Agent module and libraries. If you're not sure, then save the existing configuration file and integrate your site-specific values into the newly installation configuration file.

To run the installation script, use the following commands:

cd /tmp/cams-webagent-apache2_0_52-prefork-solaris-sparc-64bit-3.2.X/
./install-webagent.sh

Follow the prompts to provide required information. After running the installation script, you'll still need to:

  1. Edit the cams-webagent.conf file
  2. Edit the Apache httpd.conf file
  3. Edit Cams Login Page scripts (optional)

Cams Web Agent Configuration

The Cams Apache 2.0 web agent for Solaris is configured using the cams-webagent.conf file. However, you'll also need to edit Apache's httpd.conf file to register the Cams Apache 2.0 Solaris web agent module.

NOTE: To secure resources on your Apache 2.0 server, you'll also need to configure a Cams security domain. See the Cams Policy Server Configuration section in this document for more information.

Editing cams-webagent.conf

Open the cams-webagent.conf file in a text editor. The file contains comments to help you understand the property values that you may need to change. You can also reference more detailed information on the properties in the Configuration Properties document.

NOTE: The most important properties are at the top of cams-webagent.conf. In most cases, the default property values will work if the Cams policy server and Cams web agent are on the same host. As you begin to integrate more web and application servers, reference Configuration Properties to understand the properties that will usually be the focus of your attention.

Editing httpd.conf

You are now ready to edit Apache's httpd.conf file. Before proceeding, make sure that Apache is correctly working on the installation system by starting the server and browsing to a test page. If not, see the Apache documentation for troubleshooting. Before making changes to httpd.conf, you should backup your existing file.

The integration of the Cams Apache 2.0 Solaris web agent module requires the insertion of two lines that load the module and specify the location of Cams configuration information. Open the /usr/local/apache2/conf/httpd.conf file in a text editor and navigate to the Dynamic Shared Object (DSO) Support section where the modules are loaded. Then, add the following lines after the module loading and adding sections:

#
# Load Cams Apache web agent module
#
LoadModule CamsApache20PFWebAgent_module libexec/mod_cams_apache20_prefork.so
CamsWebAgentConfigFile /usr/local/apache2/conf/cams-webagent.conf

Example 1 shows and typical configuration from httpd.conf included with Apache 2.0. The inserted lines are in red.

#
# Dynamic Shared Object (DSO) Support
#
# To be able to use the functionality of a module which was built as a DSO you
# have to place corresponding `LoadModule' lines at this location so the
# directives contained in it are actually available _before_ they are used.
# Statically compiled modules (those listed by `httpd -l') do not need
# to be loaded here.
#
# Example:
# LoadModule foo_module libexec/mod_foo.so
#
... # # Load Cams Apache web agent module # LoadModule CamsApache20PFWebAgent_module libexec/mod_cams_apache20_prefork.so CamsWebAgentConfigFile /usr/local/apache2/conf/cams-webagent.conf ...

Example 1 - The Apache 2.0 httpd.conf file after registering the Cams Apache 2.0 Solaris web agent module

Provided you have already configured a Cams security domain, you should now be ready to test this Cams Apache 2.0 Solaris web agent installation. A self-documented test page is provided in the cgi-bin directory that you can use for testing.

NOTE: Due to the large number of Apache modules, testing all combinations of module loading is impossible. If you experience difficulty loading the Cams Apache web agent module, try changing the module loading order.

WARNING: To avoid security policy conflicts, you should disable Apache security specified in httpd.conf for all resources that are protected by Cams.

Editing ssl.conf

If you are planning to use client X509 certificate authentication, you'll need to find and edit your ssl.conf file to load mod_cams_client_cert_lookup. This Cams module works in conjunction with mod_ssl to make X509 client certficates available to the Cams Apache 2 web agent module.

Add the following configuration directives to your ssl.conf file:

#
# Load the Cams web agent client X509 certificate helper module
#
LoadModule CamsClientCertLookup_module libexec/mod_cams_client_cert_lookup.so
CamsClientCertLookup_debug false

NOTE: If mod_ssl is compiled into your Apache 2 httpd executable, then ssl.conf is usually found in the Apache "conf" directory. If mod_ssl is loaded at runtime using mod_ssl.so (in your Apache 2 "modules" or "libexec" directory), then ssl.conf is usually located in a parallel "conf.d" directory. You can use command: httpd -l (the lower case letter L) to list the Apache modules compiled into your Apache 2 web server.

Example 2 shows and typical configuration in ssl.conf with the inserted lines are in red. If your ssl.conf file does not load mod_ssl using a LoadModule directive, then it is probably compiled into your Apache 2 executable.

 


...
LoadModule mod_ssl libexec/mod_ssl.so # # Load the Cams web agent client X509 certificate helper module. # LoadModule CamsClientCertLookup_module libexec/mod_cams_client_cert_lookup.so CamsClientCertLookup_debug false
...

Example 2 - The Apache 2.0 ssl.conf file after registering the CamsClientCertLookup module

Provided you have already configured a Cams security domain, you should now be ready to test this Cams Apache 2.0 Solaris web agent installation. A self-documented test page is provided in the cgi-bin directory that you can use for testing.

NOTE: Due to the large number of Apache modules, testing all combinations of module loading is impossible. If you experience difficulty loading the Cams Apache web agent module, try changing the module loading order.

Editing envvars

If your OpenSSL libraries are not installed in a system-wide library directory like /usr/lib or /lib, then you may need to edit the Apache 2 file at HTTPD_ROOT/bin/envvars and add the OpenSSL library directory to the LD_LIBRARY_PATH. The following message is reported on the console if the OpenSSL libraries cannot be loaded:

Cannot load /usr/local/apache2/modules/mod_cams_apache20_prefork.so into server: ld.so.1: /usr/local/apache2/bin/httpd: fatal: libcrypto.so.0.9.8: open failed: No such file or directory

To resolve this issue, edit the file: HTTPD_ROOT/bin/envvars and add the directory where OpenSSL libraries are installed to the LD_LIBRARY_PATH. For example, if your OpenSSL libraries are installed in directory /usr/local/ssl/lib, insert that directory into the LD_LIBRARY_PATH as shown below:

LD_LIBRARY_PATH="/usr/local/apache2/lib:/usr/local/ssl/lib:$LD_LIBRARY_PATH"

In some cases, OpenSSL libraries are created with a dependency on a GNU C compiler library. The following message is reported on the console if libgcc_s.so.1 cannot be loaded:

Cannot load /usr/local/apache2/modules/mod_cams_apache20_prefork.so into server: ld.so.1:
/usr/local/apache2/bin/httpd: fatal: libgcc_s.so.1: open failed: No such file or directory

To resolve this issue, edit the file: HTTPD_ROOT/bin/envvars and add the directory where gcc libraries are installed to the LD_LIBRARY_PATH. For example, if your gcc libraries are installed in directory /usr/local/lib/sparcv9, insert that directory into the LD_LIBRARY_PATH as shown below:

LD_LIBRARY_PATH="/usr/local/apache2/lib:/usr/local/ssl/lib:/usr/local/lib/sparcv9:$LD_LIBRARY_PATH"

Scripts

The distribution cgi-bin directory includes four sample Perl scripts:

  • camstest.pl - facilitates integration testing
  • cams-login.pl - displays a login page if a protected resource request is made and the user's identity is not known

For information on how to customize these pages, see Scripts. For information on how to configure the Cams Apache 2.0 Solaris web agent to redirect to these pages, see Configuration Properties.

NOTE: The camstest.pl page is extremely useful for integration testing. You can use it to quickly confirm correct Cams web agent communications with a Cams policy server, validate authentication configuration and determine if expected user session values are available in the web environment for authenticated users.

Securing Directories and Files

If you have not done so already, you should secure important Apache configuration and log directories and files which may contain Apache SSL certificates, configuration files containing passwords or secret keys, and log files containing sensitive information.

In most cases, the Apache 2.0 web server process is started under root user ownership and creates child processes that run as another user, like apache or nobody. Generally, the original process opens and reads configuration files and sockets, then forks child processes to handle requests. Each child process inherits the open file descriptors created by the parent process, so they are able to write to logs files and communicate via sockets. The configuration file APACHE_HOME/conf/cams-webagent.conf file is read by mod_cams_apache20_prefork.so within the parent process and the log file APACHE_HOME/logs/cams-webagent.log is also created by the Apache parent process and inherited by children.

In the instructions that follow, it is assumed that the Apache server is executed by root on your Solaris/UNIX system. This example assumes that:

  1. Apache is installed at /usr/local/apache2/bin/httpd
  2. The Apache configuration directory is at /usr/local/apache2/conf
  3. The Apache logs directory is at /usr/local/apache2/logs
  4. That you are logged in as root.

As is the case with any command executed by root, you must take care that it is protected from modification by non-root users. Not only must the files themselves be writable only by root, but so must the directories, and parents of all directories. It is assumed that /, /usr, /usr/local, and /usr/local/apache2 are only modifiable by root. When you install the Apache server, you should ensure that it is similarly protected.

The following steps secure the directories and files relevant to Cams in the Apache environment:

Step 1 - Change directories to the Apache server installation directory

cd /usr/local/apache2

Step 2 - Set user and group ownership of all files and directories

chown root conf
chgrp root conf
chown root conf/cams-webagent.conf
chgrp root conf/cams-webagent.conf
chown root logs
chgrp root logs

This command sets user and group ownership to root.

NOTE: You may consider setting the ownership of all files within the Apache installation tree to root using the following command:

chown -R root .
chgrp -R root . 

Step 3 - Set directory permissions

chmod 700 conf
chmod 700 logs

This command gives read/write/execute permissions only for the owner (root). No other users or groups are given permissions on these directories, so they will unable to view or modify their contents.

Step 4 - Set file permissions

chmod 600 conf/cams-webagent.conf
chmod 600 logs/cams-webagent.log (Use only if this file exists)

These commands gives them read/write permissions for the owner (root). No other users or groups are given permission to read or write these files.

Step 5 - Set Apache startup/shutdown script umask

To further secure your Apache server and Cams Apache 2.0 Solaris web agent installation, you may consider setting file creation permissions so that only root may read/write log files. This is desirable if log files (like the cams-webagent.log file) contain sensitive DEBUG-level information or to avoid hackers from replacing log files or setting up symbolic links that can redirect the contents of log files.

Newly created files (e.g. Apache log files) are given default permissions which are a combination of: 666 (read/write permission for everybody) and the currently-set file creation mask (called the umask). The umask is combined with permission 666 to take away permissions that might otherwise be granted. By setting the umask value for the shell that executes Apache, log files that are created can be given a default permission 600, which enables the owner (root) to read/write to them, but denies permissions to all other users.

Generally, user accounts setup a default umask of 022, which results in newly created file permissions of 644. This permission value still enables group and world users to read a file, which is not desirable with sensitive log files. Using umask value 077 will cause newly created files to be given the desired permissions 600.

If the Apache web server is started using the shell script at:

/usr/init.d/httpd

You can set the umask for the associated shell by inserting a command at the top of the script as shown in Example 3.

#!/bin/sh
#
# Startup script for the Apache Web Server
#
# chkconfig: - 85 15
# description: Apache is a World Wide Web server.  It is used to serve \
#              HTML files and CGI.
# processname: httpd
# pidfile: /var/run/httpd.pid
# config: /usr/local/apache2/conf/access.conf
# config: /usr/local/apache2/conf/httpd.conf
# config: /usr/local/apache2/conf/srm.conf

# Source function library.
. /etc/rc.d/init.d/functions

# This will prevent initlog from swallowing up a pass-phrase prompt if
# mod_ssl needs a pass-phrase from the user.
INITLOG_ARGS=""

# Path to the apachectl script, server binary, and short-form for messages.
apachectl=/usr/local/apache2/bin/apachectl
httpd=/usr/local/apache2/bin/httpd
prog=httpd
RETVAL=0

umask 077

...

Example 3 - Setting the Apache server's file creation mask

To test these file and directory permissions:

  1. If the system hosting Cams supports normal user accounts, try logging in as a normal user.
  2. Try to list the contents of /usr/local/apache2/logs (permission should be denied)
  3. Try changing directories to /usr/local/apache2/logs (permission should be denied)
  4. Try creating a test file in /usr/local/apache2/logs/test.txt using a text editor (permission should be denied)
  5. To test file creation permissions, login as root. If file /usr/local/apache2/logs/cams-webagent.log exists, remove it. Then start the Apache web server and confirm that the cams-webagent.log file was created in the logs directory with permission 600 (rw-------).

Cams Policy Server Configuration

Before you start the Apache server with a Cams Apache 2.0 Solaris web agent, you'll need to ensure that the Cams policy server knows about it. See the Cams Administrator's Guide - Integration Quick Start to learn more. Pay close attention during integration to steps 4 and 5, which provide information on the settings that must be configured correctly for a Cams web agent to connect to a Cams policy server. You'll need to configure an access control policy corresponding to your site requirements.

Testing

That's it, you should now be able to start Apache to test your Cams Apache 2.0 Solaris web agent configuration. After you've started both Apache with the Cams Apache 2.0 Solaris web agent and the Cams policy server, test the configuration using the Cams web agent test page:

http://[hostname:port]/cgi-bin/camstest.pl

Login to an account in the security domain that you've established. See the test page for more configuration and testing information.

Debugging

Debugging information is available in the following web server-specific log files:

  1. The Apache 2.0 web server errors log file (APACHE_HOME/logs/error_log)
  2. The Cams web agent cams-webagent.log file (APACHE_HOME/logs/cams-webagent.log)

During Cams web agent integration, it is helpful to set the following values in cams-webagent.conf:

cams.debug=true
cams.cluster.debug=true

If the Cams web agent is successfully loaded and initialized, verbose DEBUG messages will be logged to cams-webagent.log. If the Cams web agent fails to load or initialize, errors will be reported in the APACHE_HOME/logs/error_log file. In most cases, errors will be cause by misconfigured values in httpd.conf and/or cams-webagent.conf.

WARNING: Remember to disable all Cams web agent debug flags for production environments. Leaving them enabled will decrease performance and result in very large log files.

Installation Management

The installation script (install-webagent.sh) provides a way to query and remove the installed Cams Apache 2.0 web agent files and configuration directives for a selected Apache 2.0 web server. After starting the installation script (as you would for initial installation) and identifying the Apache 2.0 web server executable you will be prompted by the following menu:

[INFO] - Cams Apache 2.0 Web Agent installation management options
================================================================================
1 - Install Cams Apache 2.0 Web Agent
2 - Uninstall Cams Apache 2.0 Web Agent
3 - Query installed Cams Apache 2.0 Web Agent files and settings
E - Exit

[????] - Choose an option:

Simply choose management option 2 for installation and 3 for a report specific to your installed options or configuration settings will display.

NOTE: During Cams Apache 2.0 web agent removal, the script will give you the opportunity to save (or leave in place) the cams-webagent.conf and the Cams login and test scripts for future use or reference.

WARNING: After the Cams Apache 2.0 web agent files have been removed, you must remove (or comment out) the changes you made to the Apache 2.0 web server's httpd.conf file, which registers the Cams Apache 2.0 web agent module. See Cams Web Agent Configuration for more information on configuration changes you may have made.

Back | Next | Contents