| Back | Next | Contents | Cams Administrator's Guide |
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:
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!
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.4, which elminates the need to install Java.
The .zip and .tar.gz distribution files will unpack into a directory named cams-policy-server-3.0.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.0.X.zip .
pkunzip cams-policy-server-3.0.X.zipLinux/UNIX (.tar.gz)
gunzip /var/cams-policy-server-3.0.0.tar.gz
tar xvf /var/cams-policy-server-3.0.X.tarLinux/UNIX (.rpm)
rpm -i cams-policy-server-3.0-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.0-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.0.X\cams. By the default, the
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 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 "-----BEGIN LICENSE KEYS-----" and "------END LICENSE KEYS------" in cams-license-keys.xml, only include the XML tags.
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 or the Linux distribution packaged as an RPM file, they include 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 or greater 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_13 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_13
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/local/j2sdk1.4.2_13
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, 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).
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.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 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.0.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:
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 camsNOTE: 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 startNOTE: 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.
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/K15camsNOTE: 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 startNOTE: 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.
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:
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.
© Copyright 1996-2008 Cafésoft LLC. All rights reserved.