Back | Next | Contents Cams Administrator's Guide

Running Cams as a Service

Cams is run by default using the command-line scripts runcams.bat/runcams.sh to start and shutdown.bat/shutdown.sh to stop the server. However, you may want to run Cams as a Microsoft Windows NT/2000/XP service or as a Linux service/daemon. Doing so allows you to configure it to automatically start when the system is booted, as well as set some run-time priorities. This document provides instructions on how to use the Java Wrapper to do so, which provides some additional benefits including a way to monitor and recover from any virtual machine anomalies.

Installation

Download the Wrapper and uncompress the archive into the directory of your choice. The installation and configuration documented in this chapter is tested with the Java Wrapper version 2.2.8 under Windows NT 4.0 with Service Pack 6a and Redhat Linux 7.3. You can download a zip or tar file.

Windows

Copy the Wrapper.exe file from the WRAPPER_HOME\bin directory into the CAMS_HOME\bin directory.

copy %WRAPPER_HOME%\bin\Wrapper.exe %CAMS_HOME%\bin

Template batch files to execute Wrapper.exe are available in WRAPPER_HOME\src\bin.

Copy these three files into the CAMS_HOME\bin directory and rename to something easier to remember such as:

cd %CAMS_HOME%
copy %WRAPPER_HOME%\src\bin\App.bat.in runCamsConsole.bat
copy %WRAPPER_HOME%\src\bin\InstallApp-NT.bat.in installCamsService.bat
copy %WRAPPER_HOME%\src\bin\UninstallApp-NT.bat.in removeCamsService.bat

Next, create a new directory in CAMS_HOME named native and copy Wrapper.DLL to it.

mkdir %CAMS_HOME%\native
copy %WRAPPER_HOME%\lib\Wrapper.dll %CAMS_HOME%\native

Now copy wrapper.jar into the CAMS_HOME/lib directory.

copy %WRAPPER_HOME%\lib\wrapper.jar %CAMS_HOME%\lib

Finally, copy the template wrapper configuration file wrapper.conf.in from the WRAPPER_HOME\src\conf directory into the CAMS_HOME\conf directory, renaming it to wrapper.conf.

copy %WRAPPER_HOME%\lib\wrapper.conf.in %CAMS_HOME%\conf\wrapper.conf

NOTE: You can save time by using wrapper.conf which is already configured as outlined in the configuration instructions below.

Linux

Copy the wrapper binary file from the WRAPPER_HOME\bin directory into the CAMS_HOME\bin directory and make sure that it has execute privileges.

cp $WRAPPER_HOME/bin/wrapper $CAMS_HOME/bin
chmod 755 $CAMS_HOME/bin/wrapper

Copy the template script file sh.script.in from the WRAPPER_HOME/src/bin/ directory into the /etc/rc.d/init.d directory, renaming it to "cams", and making sure that it has execute privileges.

cp $WRAPPER_HOME/src/bin/sh.script.in /etc/rc.d/init.d/cams
chmod 755 /etc/rc.d/init.d/cams

NOTE: The Java Wrapper documentation recommends use of the bash.script.in template but our tests indicate that the sh.script.in file works best when installing a Linux service.

Edit the cams script file. At the top of the file, edit the comments with values that will allow the Linux chkconfig utility to manage the service.

#! /bin/bash# chkconfig: 345 20 80
# description: Provides centralized authentication and access control for \
# secure network resources.
# processname: cams
# pidfile: /var/run/cams.pid
# config: /var/cams/conf/wrapper.conf

Below this in the Application section, you will find two tokens which need to be replaced. Replace the token "@app.name@" with "cams", and "@app.long.name@" with "Cams Server".

# Application
APP_NAME="cams"
APP_LONG_NAME="Cams Server"

Also, replace the two relative Wrapper environment variables with explicit paths for your installation as shown here (if you do not do this, you need to copy the realpath binary file from WRAPPER_HOME/bin to CAMS_HOME/bin).

# Fully qualified Wrapper directories
WRAPPER_DIR="/var/cams"
WRAPPER_CMD="$WRAPPER_DIR/bin/wrapper"
WRAPPER_CONF="$WRAPPER_DIR/conf/wrapper.conf"
cd $WRAPPER_DIR/bin

Create a new directory in CAMS_HOME named native and copy WRAPPER_HOME/lib/libwrapper.so to it.

mkdir $CAMS_HOME/native
cp $WRAPPER_HOME/lib/libwrapper.so $CAMS_HOME/native

Copy the required wrapper.jar library from the WRAPPER_HOME/lib directory into the CAMS_HOME/lib directory.

cp $WRAPPER_HOME/lib/wrapper.jar $CAMS_HOME/lib

Finally, copy the template wrapper configuration file wrapper.conf.in from the WRAPPER_HOME/src/conf directory into the CAMS_HOME/conf directory, renaming it to wrapper.conf.

copy $WRAPPER_HOME/src/conf/wrapper.conf.in $CAMS_HOME/conf/wrapper.conf

Note: You can save time by using wrapper.conf which is already configured as outlined in the configuration instructions below.

Configuration

Now that you've installed the wrapper, this section describes how to configure wrapper.conf to start and stop Cams. As it turns out, the Cams start and stop scripts under both Windows and Linux work well with the WrapperStartStopApp helper class.

Open CAMS_HOME/conf/wapper.conf in your text edit. The first parameter is the command to execute the java virtual machine. It's safest to give the full path, but you can also use a relative path if you have environment variables configured.

# Java Application
wrapper.java.command=/j2sdk1.4.0_02/bin/Java

Next, you specify that you'll be using the WrapperStartStopApp helper class as the main class.

# Java Main class
wrapper.java.mainclass=com.silveregg.wrapper.WrapperStartStopApp

The next section build the class path. For the default Cams installation, the following is sufficient.

# Java Classpath (include wrapper.jar) Add class path elements as
# needed starting from 1
wrapper.java.classpath.1=.
wrapper.java.classpath.2=../classes
wrapper.java.classpath.3=../lib/*.jar

Now specify the location of the native library you installed.

# Java Library Path (location of Wrapper.DLL or libwrapper.so)
wrapper.java.library.path=../native

Add additional JVM parameters required by Cams.

# Java Additional Parameters
wrapper.java.additional.1=-server
wrapper.java.additional.2=-Dcams.home=..
wrapper.java.additional.3=-DvalidateXML=true

Specify the heap parameters.

# Initial Java Heap Size (in MB)
wrapper.java.initmemory=32

# Maximum Java Heap Size (in MB)
wrapper.java.maxmemory=64

You do not need to change the Wrapper port unless it conflicts with an existing use of the port. The logging parameters can also be maintained in their default state. You should consult the wrapper documentation to learn more about logging parameters.

This completes the general configuration, the next two sections are platform specific.

Windows

Skip the the section of wrapper.conf with the following header:

#********************************************************************
# Wrapper Logging parameters
#********************************************************************

You should not modify any of these parameters when an application using this configuration file has been installed as a service. Uninstall the service before modifying this section. The service can then be reinstalled with the new parameters.

Set the service name, display name, and description (description is only used in Windows 2000/XP, not in NT).

# Name of the service
wrapper.ntservice.name=CamsServer

# Display name of the service
wrapper.ntservice.displayname=Cams Server

# Description of the service
wrapper.ntservice.description=Cams Server with Wrapper Service

Set the names of any other services which must be running before the Cams service can be started. Stopping any of the listed services will also stop this service. Add dependencies as needed starting from 1. For example, there are no default services required, but you may be using a database service that needs to be started for Cams to work properly.

# Service dependencies. Add dependencies as needed starting from 1
#wrapper.ntservice.dependency.1=

Specify the mode in which the service is installed. AUTO_START starts the service automatically when the system is rebooted. Or DEMAND_START which requires that the service me started manually.

# Mode in which the service is installed. AUTO_START or DEMAND_START
wrapper.ntservice.starttype=AUTO_START

Specifies the priority at which the Wrapper and its JVM will be run at when run as a service or as a console application. Possible values are NORMAL, LOW, HIGH, and REALTIME. Defaults to NORMAL.

# Priority at which the service is run. NORMAL, LOW, HIGH, or REALTIME
wrapper.ntservice.process_priority=NORMAL

Linux

Skip the the section of wrapper.conf with the following header:

#********************************************************************
# Wrapper Unix daemon parameters
#********************************************************************

There is only one parameter that you can specify, which is the file to write process ID to.

# File to write process ID to
wrapper.pidfile=/var/run/cams.pid

Testing

You should now be able to run Cams using the scripts installed above.

On Windows, you can use runCamsConsole.bat to test the configuration from the console before installing it as a service. Once your testing is complete, execute installCamsService.bat. You should see the service appear in the service manager. You can now start and stop the service using the start and stop buttons in the service manager.

On Linux, use the service command to start/stop/restart Cams.

service cams start

You can also use the "chkconfig --list" command to change startup priorities.

For more information on how to configure and use the Java Wrapper, see the online documentation (also available in the download).

Back | Next | Contents

© Copyright 1996-2003 Cafésoft LLC. All rights reserved.