Back | Next | Contents Cams Administrator's Guide

Installation

Installation of the Cams policy server takes only a couple of minutes on either Windows or Linux/UNIX systems. The six steps you will take are:

  1. Obtain Cams
  2. Unpack the distribution files
  3. Install the license key
  4. Install Java (if necessary)
  5. Start the Cams policy server
  6. Test

The Cams download includes the Cams policy server and a Jetty web server you'll use for testing and to help configure authentication. The Cams policy server documentation is available online and can be downloaded from the Cafésoft web site. Let's get started!

Step 1 - Obtain Cams

Cams is available for download from the Cafésoft web site at http://www.cafesoft.com in zip, tar/gzip, and RPM formats. Download the zip file for Windows and the gzip (.gz) or RPM (.rpm) file for Linux/UNIX systems. For Windows only, Cams for Windows includes a Java Runtime Environment (JRE) release 1.6, which elminates the need to install Java.

Step 2 - Unpack the distribution files

The .zip and .tar.gz distribution files will unpack into a directory named cams-policy-server-3.2.X. The .rpm file can be installed directly on Linux/UNIX systems using the 'rpm' command. Change to a directory where you'll install Cams.

Windows

cd c:\

Linux/UNIX

cd /var

Unpack the distribution file:

Windows

copy c:\tmp\cams-policy-server-3.2.X.zip .
pkunzip cams-policy-server-3.2.X.zip

Linux/UNIX (.tar.gz)

gunzip /var/cams-policy-server-3.2.0.tar.gz
tar xvf /var/cams-policy-server-3.2.X.tar

Linux/UNIX (.rpm)

rpm -i cams-policy-server-3.2-1.i386.rpm

NOTE: By default, the Cams Policy Server .rpm file will install to directory /var/cams. To install to another directory of your choice, use the rpm --prefix command line option. For example: rpm --prefix /usr/local/cams -i cams-policy-server-3.2-1.i386.rpm

From here on, we'll use the symbol CAMS_HOME to represent the full path to the Cams root directory. For example, if you unpacked the distribution to C:\ on Windows, CAMS_HOME would be C:\cams-policy-server-3.2.X\cams.

NOTE: The Windows instructions above assume you have the pkunzip command line utility on your system. You may use any zip program including graphical tools like Winzip.

Step 3 - Install the license keys

Cams requires valid license keys that you obtain from Cafésoft. You must save the license keys sent to you in a file named cams-license-keys.xml in the CAMS_HOME/conf directory. Do not include the lines:

-----BEGIN LICENSE KEYS-----

------END LICENSE KEYS------

in cams-license-keys.xml, only include the enclosed XML tags.

WARNING: The Cams license keys include values that restrict the use of Cams by version, date, host IP address and number of concurrent connections. Do not attempt to change these values as it will invalidate the license keys. If the cams-license-keys.xml file is not valid or not found, you will see an error message when attempting to start Cams. If the number of concurrent sessions is exceeded at any time, a WARNING is logged and a notification is sent no more than once every two hours. You are expected to upgrade if the number of concurrent sessions is exceeded at any time.

Step 4 - Install Java (if necessary)

If you are using the Cams for Windows installation or the Linux distribution packaged as an RPM file, they include the Java 2 Platform Standard Edition JRE (JRE) and you can skip this step. All other Cams installations require that Java JDK or JRE 1.4 or greater be installed on your system. Use of the latest release of Java JDK/JRE 1.6 is recommended to take advantage of the latest performance and features. If a JRE is not already installed, please do so by referring to the Java 2 Platform Standard Edition download and installation instructions at:

http://www.java.com/en/download/index.jsp

The Java installation process may set the JAVA_HOME environment variable on your system. For correct operation of Cams, JAVA_HOME must point to the JDK or JRE installation. You may verify the JAVA_HOME setting by typing:

Windows

set j

Linux/UNIX

env | grep JAVA_HOME

If JAVA_HOME does not point to the correct directory, you may temporarily set it in the console you are using, or set is permanently. Assuming the JRE 1.6.0_22 is installed in the default location, you would temporarily set the value of JAVA_HOME by entering in a console:

Windows

set JAVA_HOME=C:\Program Files\Java\jre1.6.0_22

To permanently set JAVA_HOME, you set a system environment variable shown above. The steps you use in Windows to set this value is dependent upon the version of Windows you are using. If you do not know how, please contact your system administrator.

WARNING: You must set a system environment variable. If you set a user environment variable and attempt to start the Cams policy server as a service, the service will not find Java, which will result in a Windows error.

Linux/UNIX (Borne or bash shell):

JAVA_HOME=/usr/java/jdk1.6.0_22
export JAVA_HOME

To permanently set the JAVA_HOME environment variable, you can edit the Cams policy server startup script to include the lines above at the top.

That's it, you should now be ready to start the Cams policy server!

Step 5 - Start the Cams Policy Server

The Cams policy server is a standalone server with services that handle authentication, access control and session access requests received from Cams web agents. You'll usually run the Cams policy server in it's own Java Virtual Machine (JVM).

Windows

The Cams policy server can be run in a Windows console or as a service. You should try to start the Cams policy server in a console window before attempting to install and start it as a service. When you start the Cams policy server in a Windows console system messages display immediately, which helps you detect and diagnose any startup issues. This is also a good approach when making updates or using a Cams policy server for development.

To run the Cams policy server in a Windows console:

%CAMS_HOME%\bin\runcams console

Enter control-C in the console window to gracefully stop the Cams policy server.

To install the Cams policy server as a Windows service, you must be logged into an account with administrator privileges. If you are using your own JRE installation, you must also ensure that JAVA_HOME is correctly defined (see Step 4).

Installing, Starting, and Stopping the Cams Policy Server as a Windows Service

Running the following script will install a service named Cams Policy Server:

%CAMS_HOME%\bin\runcams install

Now start the Cams policy server service from the Windows Services client, or by entering at the command line either:

%CAMS_HOME%\bin\runcams start

or:

net start CamsPolicyServer

Stop the Cams policy server service from the Windows Services client, or by entering at a command line either:

%CAMS_HOME%\bin\runcams stop

or:

net stop CamsPolicyServer

To remove the Windows service named Cams Policy Server:

%CAMS_HOME%\bin\runcams remove

If you upgrade from a previous Cams policy server release or change the location of the Cams policy server, you may need to update the Cams policy server service by entering at the command line:

%CAMS_HOME%\bin\runcams update

NOTE: Cafésoft licenses the Java Service Wrapper to manage Cams policy server startup services on Windows only. The configuration values for the Java Service Wrapper, which includes JVM startup options for the Cams policy server, are found in CAMS_HOME/conf/runcams.conf. The Java Service Wrapper includes features to monitor the log file it creates (found in CAMS_HOME/logs/console.log) for Java system errors and to detect thread deadlock conditions. By default, the Cams policy server on Windows will uses these features to write a heapdump file and restart automatically if either a java.lang.OutOfMemoryError or thread deadlock condition is detected. Customers may add other conditions and triggers as desired. Customer may also upgrade to use the Java Service Wrapper Professional Edition, which adds support for e-mail notification and other other JVM and application management tools. For more information, see the the Java Service Wrapper web site, or contact Cafésoft support.

Linux/UNIX

If you start the Cams policy server from the CAMS_HOME or CAMS_HOME/bin directory, you will not need to set the CAMS_HOME environment variable. However, if you start from any other directory, you'll need to set CAMS_HOME. Also, if you want to run the Cams policy server using a JVM security manager, a -security flag can be used. The default Cams policy server security policy is installed at CAMS_HOME/conf/cams.policy and grants all permissions for classes installed in CAMS_HOME/lib and CAMS_HOME/classes.

CAMS_HOME=/var/cams-policy-server-3.2.X
export CAMS_HOME

To start the Cams policy server:

$CAMS_HOME/bin/runcams.sh

or

$CAMS_HOME/bin/runcams.sh -security

or

service cams start (on Linux systems supporting the 'service' command)

NOTE: If the scripts in this directory do not untar with execution permissions, you'll need to use the chmod 755 *.sh command before executing the runcams.sh command.

To gracefully shutdown the Cams policy server, use:

$CAMS_HOME/bin/shutdown.sh

or

service cams stop (on Linux systems supporting the 'service' command)

NOTE: You can start and stop the Cams policy server and web agents in any order and connections will be established and cleaned up automatically. However, there is a benefit to using the following order:

  1. Start the Cams policy server first and then the web servers with Cams web agents. That prevents connection errors in Cams web agent logs that result from a Cams web agent trying to connect before the Cams policy server is started (and will prevent users from possibly experiencing Cams web agent connection during startup).
  2. Gracefully stop the web servers with Cams web agents first and then the Cams policy server. The Cams web agents will close their connections, which will reduce the time is takes the Cams policy server to gracefully shutdown to between 5 to 10 seconds. Otherwise, the Cams policy server will serially wait up to 5 seconds for each Cams web agent connection to close. This can take a long time when using more than one multi-process web server like Apache, which can have hundreds of connections to the Cams policy server.
Installing, Starting, and Stopping the Cams Policy Server as a Linux Service

The Cams Policy Server ships with a shell script that can be used to start the Cams Policy Server when Linux is started and to stop the Cams Policy Server when Linux is shutdown. The script can also be used to start and stop the Cams Policy Service from a command line using the Linux "service" or by directly executing the script using its full directory path.

NOTE: If you installed the Cams Policy Server from the Linux .rpm distribution, then an init.d script was automatically created in file: /etc/init.d/cams and symbolic links were created in /etc/rc*.d directories as described later in this section. To start the Cams Policy Server, simply use the Linux "service" commands: "service cams start" or "service cams stop".

To install and configure the Cams Policy Server as a Linux Service:

1. Login as "root" so that you can copy the Cams Policy Server service script to a protected directory.

2. Copy the Linux-specific script to the init.d service directory using command:

cp $CAMS_HOME/bin/initd_cams_linux.sh /etc/init.d/cams

3. Set the following permissions and user and group ownerships on the file:

chmod 744 /etc/init.d/cams
chown root /etc/init.d/cams
chgrp sys /etc/init.d/cams

4. Edit the script and set appropriate values for environment variables CAMS_HOME and JAVA_HOME:

vi /etc/init.d/cams

JAVA_HOME=/usr/java
CAMS_HOME=/var/cams

5. Use the chkconfig command to add symbolic links to this script in the Linux kernel directories for run levels 3, 4, and 5:

chkconfig --add cams

NOTE: This command should create symbolic links to /etc/init.d/cams from the following locations:

/etc/rc3.d/S95cams
/etc/rc4.d/S95cams
/etc/rc5.d/S95cams

/etc/rc0.d/K15cams
/etc/rc1.d/K15cams
/etc/rc2.d/K15cams
/etc/rc6.d/K15cams

6. Test Cams Policy Server startup from the command line by typing:

service cams start

NOTE: The script redirects messages for stdout and stderr to file: $CAMS_HOME/logs/console.log

7. Test Cams Policy Server startup from the command line by typing:

service cams stop

To uninstall the Cams Policy Server init.d service script:

1. Use the chkconfig command to remove symbolic links to this script from the Linux kernel directories for run levels 3, 4, and 5:

chkconfig --del cams

2. Remove the Cams Policy Server init.d script:

rm -f /etc/init.d/cams

NOTE: Consider saving the script for future use or simply leaving the script in place. Once the symbolic links from the Linux kernel directories for run levels 3, 4, and 5 have been removed, the Cams Policy Server will no longer start when Linux is booted and stop when Linux is shutdown.

Installing, Starting, and Stopping the Cams Policy Server as a Unix Service

The Cams Policy Server ships with a shell script that can be used to start the Cams Policy Server when Unix operating systems are started and to stop the Cams Policy Server when they are shutdown. The script can also be used to start and stop the Cams Policy Service from a command line by directly executing the script using its full directory path.

To install and configure the Cams Policy Server as a Unix Service:

1. Login as "root" so that you can copy the Cams Policy Server service script to a protected directory.

2. Copy the Unix shell script to the init.d service directory using command:

cp $CAMS_HOME/bin/initd_cams_unix.sh /etc/init.d/cams

3. Set the following permissions and user and group ownerships on the file:

chmod 744 /etc/init.d/cams
chown root /etc/init.d/cams
chgrp sys /etc/init.d/cams

4. Edit the script and set appropriate values for environment variables CAMS_HOME and JAVA_HOME:

vi /etc/init.d/cams

JAVA_HOME=/usr/java
CAMS_HOME=/var/cams

5. Create symbolic links in the Unix kernel directories for run levels 3, 4, and 5 (if directories for those run levels exist):

ln -s /etc/init.d/cams /etc/rc3.d/S95cams
ln -s /etc/init.d/cams /etc/rc4.d/S95cams
ln -s /etc/init.d/cams /etc/rc5.d/S95cams

ln -s /etc/init.d/cams /etc/rc0.d/K15cams
ln -s /etc/init.d/cams /etc/rc1.d/K15cams
ln -s /etc/init.d/cams /etc/rc2.d/K15cams

NOTE: Run-level directories /etc/rc4.d and /etc/rc5.d may not exist on some Unix systems. Disregard run level directories that don't exist on your system.

6. Test Cams Policy Server startup from the command line by typing:

/etc/init.d/cams start

NOTE: The script redirects messages for stdout and stderr to file: $CAMS_HOME/logs/console.log

7. Test Cams Policy Server startup from the command line by typing:

/etc/init.d/cams stop

To uninstall the Cams Policy Server init.d service script:

1. Remove symbolic links in the Unix kernel directories for run levels 3, 4, and 5:

rm -f /etc/rc3.d/S95cams
rm -f /etc/rc4.d/S95cams
rm -f /etc/rc5.d/S95cams

rm -f /etc/rc0.d/K15cams
rm -f /etc/rc1.d/K15cams
rm -f /etc/rc2.d/K15cams

2. Remove the Cams Policy Server init.d script:

rm -f /etc/init.d/cams

NOTE: Consider saving the script for future use or simply leaving the script in place. Once the symbolic links from the Unix kernel directories for run levels 3, 4, and 5 have been removed, the Cams Policy Server will no longer start when Unix is booted and stop when Unix is shutdown.

Step 6 - Test

A Jetty web server with an integrated Cams Servlet Filter web agent is included with the Cams policy server to verify the installation. It also includes useful tools to configure authentication and generate secret keys. Using the default settings supplied with the Cams policy server, the Cams Servlet Filter web agent will connect to a Cams policy server on the same system.

WARNING: If you change the default settings in the Cams policy server or in this Cams Servlet Filter web agent, your results may be different.

To run the Jetty web server in a Windows console:

cd %CAMS_HOME%\jetty\
camstest.bat

Enter control-C in the console window to gracefully stop the Jetty HTTP server.

To start the Jetty test web server on Linux/UNIX:

cd $CAMS_HOME/jetty/
./camstest.sh

Enter http://localhost:8080/ if your web browser is on the same system as the Cams policy server and Jetty web server and http://hostname:8080/ (where hostname is the DNS name or IP address of the system) if your web browser is on a remote system. The default access control policy grants access to the link below. You can enter the default values supplied in the Cams test page to authenticate:

http://localhost:8080/cams/camstest.jsp

The Cams test page is included with every Cams web agent to verify installation against a Cams policy server. You'll use it here to verify that the Cams policy server is working correctly. Upon successful authentication, you should see a Cams session cookie and Cams secure HTTP request headers for the admin user. You can also try an incorrect user name or password to see the corresponding redirect to the login page and error message.

NOTE: The Cams test page contains additional information on usage. The Jetty web server also contains useful web applications that you can use to help configure Cams login modules and secret key values.

Congratulations, you've now completed the installation!

To learn how to begin integrating the Cams policy server (we recommend this next), see the Integration Quick Start. To learn how to integrate Cams web agents in web and applications servers, see the Cams web agent guides found at the Cafesoft Documentation Center.

Back | Next | Contents