| Back | Next | Contents | Cams Administrator's Guide |
The following instructions will help you install Cams on Windows and Linux/UNIX systems. In summary, the steps you will take include:
The Cams download includes the Cams policy server and a lightweight Jetty web server, which is pre-configured to run without any changes. Cams policy server documentation is available in a separate download. Once you complete initial Cams policy server installation and testing, the next step is to install and integrate at least one Cams web agent. Let's get started!
Cams is available for download from the Cafésoft web site at http://www.cafesoft.com in both zip and tar/gzip formats. Download the zip file for Windows and the gzip (.gz) file for Linux/UNIX systems. For Windows only, Cams for Windows includes a Java Runtime Environment (JRE) release 1.4, which elminates the need to install Java. A smaller download is available for Windows that does not include Java if it is already installed on the target system.
The distribution files will unpack into a directory named cams-policy-server-2.1.X. 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-2.1.X.zip .
pkunzip cams-policy-server-2.1.X.zipLinux/UNIX
gunzip /var/cams-policy-server-2.1.0.tar.gz
tar xvf /var/cams-policy-server-2.1.X.tar
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-2.1.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.
Cams requires a valid license-keys file 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.
WARNING: The Cams license-keys include values that may 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.
If you are using the Cams for Windows installation, it includes the Java 2 Platform Standard Edition JRE (JRE) 1.4 and you can skip this step. All other Cams installations require that JRE 1.4 be installed on your system. If JRE 1.4 is not already installed, please do so by referring to the Java 2 Platform Standard Edition download and installation instructions at:
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 JRE 1.4 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.4.2_06 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:\j2sdk1.4.2_06
To permanently set JAVA_HOME, you set a system environment variable as defined above. The way you use the graphical administrative tools to do this 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/local/j2sdk1.4.2_06
export JAVA_HOMETo 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!
The Cams policy server is a standalone server with services that handle authentication and access control requests received from Cams web agents. You'll usually run the Cams policy server in it's own Java Virtual Machine (JVM), but can optionally embed it within other servers and applications. If you desire to do the later, please contact Cafésoft support.
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 the console 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.bat
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 1.4 installation, you must also ensure that JAVA_HOME is correctly defined (see Step 4).
Running the following script will install a service named Cams Policy Server:
%CAMS_HOME%\bin\cams-service-install.bat
Now start the Cams policy server service from the Windows Services client, or by entering at the command line:
net start CamsPolicyServer
Stop the Cams policy server service from the Windows Services client, or by entering at a command line:
net stop CamsPolicyServer
To remove the Windows service named Cams Policy Server:
%CAMS_HOME%\bin\cams-service-remove.bat
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 Java Virtual Machine 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-2.1.X
export CAMS_HOME
To start the Cams policy server:
$CAMS_HOME/bin/runcams.sh
or
$CAMS_HOME/bin/runcams.sh -security
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 previous command.
To gracefully shutdown the Cams policy server, use:
$CAMS_HOME/bin/shutdown.sh
A lightweight Jetty test 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. 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 test 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 test 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:
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 username 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 root directory on the Jetty test 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 integrate 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.
NOTE: You can start or restart the Cams policy server and Cams web agents in any order.
© Copyright 1996-2005 Cafésoft LLC. All rights reserved.