| Back | Next | Contents | Cams Web Agent Guide |
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 response, possibly prompting the user for authentication if required.
This document provides instructions on how to install and configure the Cams Apache 1.3 Solaris web agent, which is an Apache version 1.3 module available for:
If you need support for another operating system or hardware architecture, please contact Cafésoft support.
NOTE: For known issues with the Cams Apache 1.3 Solaris web agent, see ReleaseNotes.html found in the root directory of the Cams Apache web agent distribution.
These instructions guide you through the installation of the Cams Apache 1.3 Solaris web agent on a system with Apache 1.3.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 1.3.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/1.3.33 (Unix)
Server built: Apr 21 2005 17:02:59
Server's Module Magic Number: 19990320:16
Server compiled with....
-D EAPI
...
Your Apache 1.3 server version is compatible with the Cams Apache 1.3 Web Agent distribution if the Server version starts with "1.3." (e.g. 1.3.29, 1.3.32, etc.) and the major part of the "Magic Number" (19990320) 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 1.3 server "Magic Number" is different, contact Cafésoft support to determine if another web agent distribution is available for your environment.
In addition, your Apache 1.3 server must have been built with Apache "Extended Application Programmer's Interface" (EAPI) support. The "-D EAPI" compilation option will be displayed with command "httpd -V" if this option is included. If it is not available, you will need to obtain or build an Apache 1.3 server that includes this option before proceeding.
The Cams Apache 1.3 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 general system library directory like /usr/lib or in an OpenSSL-specific directory 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.7*If OpenSSL is not installed in directory /usr/lib, it may be installed in directory /lib, /usr/local/ssl/lib, /opt/ssl/lib, or some other directory. This location 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 1.3 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.7*
-rwxr-xr-x 1 root other 1311816 Feb 10 13:59 /usr/lib/libcrypto.so.0.9.7*
You'll need to copy cams-webagent-apache13-solaris-sparc-eapi-2.1.X.tar.gz to a temporary directory on the target host. Login as root and navigate to the directory where you copied the cams-webagent-apache13-solaris-sparc-eapi-2.1.X.tar.gz file and unpack it into the temporary directory.
cd /tmp
gunzip cams-webagent-apache13-solaris-sparc-eapi-2.1.X.tar.gz
tar xvf cams-webagent-apache13-solaris-i386-eapi-2.1.X.tar
Change directories to cams-webagent-apache13-solaris-sparc-eapi-2.1.X. The files shown in Figure 1 should have been extracted from the distribution.
<!-- Cams Apache web agent documentation and license --> LICENSE README.txt ReleaseNotes.html install-webagent.sh <!-- Cams Apache web agent cgi-bin files --> cgi-bin/cams-denied.pl cgi-bin/cams-error.pl cgi-bin/cams-login.pl cgi-bin/camstest.pl <!-- Cams Apache 1.3 web agent configuration files --> conf/cams-webagent.conf conf/webagent.properties conf/access-control.properties <!-- Cams Apache 1.3 web agent libraries (NOTE: Some file names may differ) --> lib/mod_cams_apache13.so lib/libcams.so.0 lib/libcamsclient_mt_cams_1_0.so.0 lib/libcamsclient_mt_cams_2_0.so.0 lib/libcams-common.so.0 lib/libcscore.so.0 lib/libcscrypto.so.0.9.6 lib/libcscrypto.so.0.9.7 lib/libapr-0.so.0.9.5 |
Figure 1 - The Cams Apache 1.3 Solaris web agent installation files after unpacking
Apache 1.3 is highly configurable, so the target directories into which these files are copied by the installation script may vary widely. Standard Apache 1.3 built from the source distribution installs in the following directories:
/usr/local/apache/conf - the Apache configuration files
/usr/local/apache/libexec - the Apache modules
/usr/local/apache/cgi-bin - the cgi-bin scripts
/usr/local/apache/htdocs - the web pages
The installation script attempts to find the directories listed above, sometimes with your help. It then removes or backs up any previous Cams Apache 1.3 Solaris web agent files it finds and copies the new files to the target locations you specify. If you want to run the installation script, do it now and skip to the Web Agent Configuration section:
cd /tmp/cams-webagent-apache13-solaris-sparc-eapi-2.1.X/
./install-webagent.sh
Follow the prompts to provide required information.
The Cams Apache web agent is configured in the cams-webagent.conf file. However, you'll also need to edit Apache's httpd.conf file and integrate Cams login, error, and denied shell pages.
NOTE: To secure resources on your Apache web server, you'll also need to configure a Cams security domain. See the Cams Policy Server Configuration section in this document for more information.
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.
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 Apache 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 1.3 Solaris web agent module requires the addition of commands to load the module and Cams libraries needed by the module.
NOTE: Cams Apache 1.3 Solaris web agent installations prior to version 2.1 did not use the "LoadFile" directive to load dependent Cams libraries. Instead, dependent libraries were generally installed in a central system library directory like /usr/lib, which sometimes caused problems when multiple Cams agents needed to be installed on a single host. Starting with Cams 2.1, libraries are now installed in the Apache 1.3 web server-specific modules installation directory and because this directory is not usually in the library load path, the LoadFile directives ensure they are loaded for the Cams webagent Apache module.
To add the required directives, open the Apache 1.3 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 lines shown in Example 1 (in red). If your module directory is different from "libexec" or has a different path relative to the Apache 1.3 root directory, use those values instead.
Make sure that the value for CamsWebAgentConfigFile corresponds to the location on your system. Example 1 shows and typical configuration from httpd.conf. The inserted lines are in red.
#
LoadFile libexec/libapr-0.so.0 LoadFile libexec/libcscrypto.so.0 LoadFile libexec/libcscore.so LoadFile libexec/libcams.so LoadFile libexec/libcams-common.so LoadModule cams_apache13_module libexec/mod_cams_apache13.so CamsWebAgentConfigFile /usr/local/apache/conf/cams-webagent.conf ... |
Example 1 - Cams Apache 1.3 Solaris web agent module registration in httpd.conf
Provided you have already configured a Cams security domain, you should now be ready to test this Cams Apache 1.3 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 1.3 Solaris 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.
The distribution cgi-bin directory includes four sample Perl scripts:
For information on how to customize these pages, see Scripts. For information on how to configure the Cams web agent to redirect to these pages, see Configuration Properties.
NOTE: The camstest.pl 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.
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 1.3.x web server process is started under root 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_apache13 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 system. This example assumes that:
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 /, /usr, /usr/local, and /usr/local/apache 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:
cd /usr/local/apache
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 .
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.
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.
To further secure your Apache server/Cams 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:
/etc/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 2.
#!/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: /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. INITLOG_ARGS="" # Path to the apachectl script, server binary, and short-form for messages. apachectl=/usr/local/apache/bin/apachectl httpd=/usr/local/apache/bin/httpd prog=httpd RETVAL=0 umask 077 ... |
Example 2 - Setting the Apache server's file creation mask
To test these file and directory permissions:
Before you start the Apache server with a Cams Apache 1.3 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.
Debugging information is available in the following web server-specific log files:
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.
That's it, you should now be able to start Apache to test your Cams Apache 1.3 Solaris web agent configuration. After you've started both Apache with the Cams Apache 1.3 Solaris web agent and the Cams policy server, test the configuration using:
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.
The installation script (install-webagent.sh) provides a way to query and remove the installed Cams Apache 1.3 web agent files and configuration directives for a selected Apache 1.3 web server. After starting the installation script (as you would for initial installation) and identifying the Apache 1.3 web server executable you will be prompted by the following menu:
[INFO] - Cams Apache 1.3 Web Agent installation management options
================================================================================
1 - Install Cams Apache 1.3 Web Agent
2 - Uninstall Cams Apache 1.3 Web Agent
3 - Query installed Cams Apache 1.3 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 1.3 web agent removal, the script will give you the opportunity to save (or leave in place) the cams-webagent.conf and the Cams login, error and denied scripts for future use or reference.
WARNING: After the Cams Apache 1.3 web agent files have been removed, you must remove (or comment out) the changes you made to the Apache 1.3 web server's httpd.conf file, which registers the Cams Apache 1.3 web agent module. See Cams Web Agent Configuration for more information on configuration changes you may have made.
© Copyright 1996-2005 Cafésoft LLC. All rights reserved.