Back | Next | Contents Cams Web Agent Guide

Apache 2.2 Worker MPM Linux 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.2 Linux web agent, which is an Apache version 2.2.x module for:

  • Apache "worker" Multi-Processing Module (MPM)
  • Red Hat 5.x, 6.x for AMD/Intel x86 64-bit
  • SUSE Linux Server 10, 11 for AMD/Intel x86 64-bit
  • May support other Linux distributions

The Cams Apache 2.2 Linux web agent supports the worker Apache 2.2 Multi-Processing Module (MPM). Support for the prefork MPM is also available using a different web agent distribution. See the Apache 2.2 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.2 Worker MPM Linux 64-bit web agent, see ReleaseNotes.html found in the root directory of the Cams Apache 2.2 Linux web agent distribution.


These instructions guide you through the installation of the Cams Apache 2.2 Linux web agent on a system with Apache 2.2.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 Linux shell and change directories to the location where Apache 2.2.x binaries are installed and one of the following commands:

For an Apache installation built from source, execute the following command from the "bin" subdirectory:

./httpd -V

For an Apache installation shipped with RedHat or RedHat-derived Linux distrutions (like CentOS) and installed from RPM files, use:

/usr/sbin/httpd -V

For an Apache installation shipped with SuSE Linux distrutionsand installed from RPM files, use:

/usr/sbin/httpd2 -V

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

Server version: Apache/2.2.11 (Unix)
Server built: Oct 5 2012 12:39:24
Server's Module Magic Number: 20051115:21
Architecture: 64-bit
Server MPM: Worker

Your Apache 2 server version is compatible with the Cams Apache 2 Web Agent distribution if the server version starts with 2.2. (e.g. 2.2.11, 2.2.5, etc.) and the major part of the Magic Number (20051115) 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.

Confirming Availability of OpenSSL

The Cams Apache 2.2 Linux 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 on RedHat distributions:

ls -laF /lib64/libssl*

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

ls -laF /usr/lib64/libssl*

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

lrwxrwxrwx 1 root other 15 Jan 28 16:40 /lib64/ ->*
-rwxr-xr-x 1 root other 232044 Feb 10 13:59 /lib64/*

If OpenSSL is not installed in a system library directory like /lib64 or /usr/lib64, it may be installed in directory /usr/local/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.2 Linux 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 /lib64/libcrypto*


ls -laF /usr/lib64/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 /lib64/ ->*
-rwxr-xr-x 1 root other 1311816 Feb 10 13:59 /lib64/*

Unpacking Distribution Files

The following instructions assume you are using Apache server version 2.2.11. Substitute the appropriate file name for your downloaded Cams Apache 2.2 Linux web agent distribution.

You'll need to copy cams-webagent-apache2_2_11-worker-linux-x86-64bit-3.2.X.tar.gz or cams-webagent-apache2_2_11-worker-linux-x86-64bit-3.2.X.rpm to a temporary directory on the target host. You must login as root and navigate to the directory where you copied the downloaded file to a temporary directory.

Linux/UNIX (.tar.gz)

cd /tmp
gunzip cams-webagent-apache2_2_11-worker-linux-x86-64bit-3.2.X.tar.gz
tar xvf cams-webagent-apache2_2_11-worker-linux-x86-64bit-3.2.X.tar

Change directories to cams-webagent-apache2_2_11-worker-linux-x86-64bit-3.2.X. The files shown in Figure 1 should have been extracted from the distribution.

<!-- Cams Apache web agent documentation and license -->

<!-- Cams Apache web agent configuration files -->

<!-- Cams Apache web agent cgi-bin files -->

<!-- Cams Apache web agent image files -->

<!-- Cams Apache web agent libraries -->

Figure 1 - Directory listing of the Cams Apache 2.2 Linux web agent files after unpacking

Installing the Agent

The Apache 2.2/worker MPM web server is generally built by customers directly from a source code distribution. Conseqently, the currently supported installation script is:

  1. "Standard Apache" environments built from source. Use installation script:

If you have an Apache 2.2/worker installation that was provided through a Linux distribution or from a third party, please try the provided installation script. If it does not work for you, please contact Cafésoft support for help: we may be able to provide a new installation script for you.

See the descriptions for each of these Apache environments in the following three sections to choose the installation script best suited for your environment. If you are still unsure of the best installation option for your environment, please contact Cafésoft support.

Installing the Agent in a "Standard Apache" Environment

The standard Apache 2.2 installation built from the source code distribution obtained from a directory structure like the following:

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

Most sites will customize the Apache directory installation "prefix" (/usr/local/apache2 in the example above) and add site-specific Apache modules during the configuration step. The resulting Makefiles are then then used to build (make) the Apache binaries and install (make install) the web server. If this describes your Apache environment, use the "" script:

cd /tmp/cams-webagent-apache2_2_11-worker-linux-x86-64bit-3.2.X/

Final Steps

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 script (optional)

Cams Web Agent Configuration

The Cams Apache 2.2 Linux web agent 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.2 Linux web agent module and integrate the Cams login page into cgi-bin.

NOTE: To secure resources on your Apache 2.2 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.2 Linux web agent module requires the insertion of two lines that load the module and specify the location of Cams configuration information. Open the /etc/httpd/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 CamsApache22PFWebAgent_module modules/
CamsWebAgentConfigFile /etc/httpd/conf/cams-webagent.conf


Example 1 shows and typical configuration from httpd.conf included with Red Hat 5.x. 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 modules/
LoadModule access_module modules/
LoadModule auth_module modules/ ... LoadModule mem_cache_module modules/
LoadModule cgi_module modules/
# # Load Cams Apache web agent module and set the config file path # LoadModule CamsApache22PFWebAgent_module modules/ CamsWebAgentConfigFile /etc/httpd/conf/cams-webagent.conf ...

Example 1 - The Apache 2.2 httpd.conf file after registering the Cams Apache 2.2 Linux web agent module for the "RedHat Apache" and "Standard Apache" Environements

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.

Enabling mod_cams_client_cert_lookup for X.509 Client Certificate Authentication (Optional)

If you are planning to use client X509 certificate authentication, you'll need add directives to your Apache configuration 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.2 web agent module. The Apache file you'll need to edit depends on your environment.

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 (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.2 web server.

Example 2 shows a typical configuration from ssl.conf included with Red Hat 5.x. 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.2 executable.

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

Example 2 - The Apache 2.2 ssl.conf file after registering the CamsClientCertLookup module ("Standard Apache" and "Red Hat Apache" Environments)

Provided you have already configured a Cams security domain, you should now be ready to test this Cams Apache 2.2 Linux 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

This step is generally needed only for "Standard Apache" environments built from source. The standard "Red Hat Apache" and "SuSE Apache" environments use OpenSSL and other general purpose libraries installed in system library directories, so these environments are already pre-configured.

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/ into server: /usr/local/apache2/bin/httpd: fatal: 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:



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

  • - facilitates integration testing
  • - 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.2 Linux web agent to redirect to these pages, see Configuration Properties.

NOTE: The page is extremely useful for integration testing. You 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.2 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 a child process 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, sockets, etc. The configuration file APACHE_HOME/conf/cams-webagent.conf file is read by mod_cams_apache20_worker 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 Linux/UNIX system. This example assumes that:

  1. Apache is installed at /etc/httpd
  2. The Apache configuration directory is at /etc/httpd/conf
  3. The Apache log directory is at /etc/httpd/logs
  4. That you are logged in as root.

As is the case with any command that root executes, 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 /, /etc and /etc/httpd 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 /etc/httpd

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.2 Linux web agent installation, you may consider setting file creation permissions so that only root may read/write log files. This is desireable 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 desireable 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:


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

# 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/
# config: /etc/httpd/conf/access.conf
# config: /etc/httpd/conf/httpd.conf
# config: /etc/httpd/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.

# Path to the apachectl script, server binary, and short-form for messages.

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 /etc/httpd/logs (permission should be denied)
  3. Try changing directories to /etc/httpd/logs (permission should be denied)
  4. Try creating a test file in /etc/httpd/logs/test.txt using a text editor (permission should be denied)
  5. To test file creation permissions, login as root. If file /etc/httpd/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.2 Linux 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.


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


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


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

  1. The Apache 2.2 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:


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 options for managing your Cams Apache 2.2 web agent installation vary depending on the distribution type. Choose the instructions for the .tar.gz or the .rpm distribution below.

Installation Management (.tar.gz distribution)

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

[INFO] - Cams Apache 2.2 Web Agent installation management options
1 - Install Cams Apache 2.2 Web Agent
2 - Uninstall Cams Apache 2.2 Web Agent
3 - Query installed Cams Apache 2.2 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.2 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.2 web agent files have been removed, you must remove (or comment out) the changes you made to the Apache 2.2 web server's httpd.conf file, which registers the Cams Apache 2.2 web agent module. See Cams Web Agent Configuration for more information on configuration changes you may have made.

Back | Next | Contents