Raven™ service admin - user guide

This documents outlines how to install and use the Caboodle mobile server admin client that is distributed with Net Caboodle Raven™

Installation

To install the software use the following command assuming that the Java 5.0 executable is in your path. 

java -jar install-netcaboodle.jar

If you get the following exception when trying to run the installer, this is because you have not used Java 5.0 to start the installer.

 Exception in thread "main" java.lang.UnsupportedClassVersionError:

To resolve this problem use the full path to the Java 5.0 executable, for example, 

C:\Program Files\Java\jre1.5.0\bin\java -jar install-netcaboodle.jar

When the installer starts up (see figure 1) you will be presented with the Net Caboodle license for this product plus the options to accept or reject the license. If you are willing to accept the license, then check the "Accept license" box, which will enable the "Install" button.

You can now install the software into the default directory suggested by the installer or select a location of your choice.

On windows platforms the Installer also creates a Desktop folder called "Net Caboodle", which contains copies of the Net Caboodle documentation, plus a copy of the BAT file used to start the admin client.

Figure 1: Caboodle server admin

On completion of the installation process the installer will startup the Caboodle admin client and display the following dialog box.

Figure 2: Installation complete

Troubleshooting installation problems

If the Caboodle admin client does not appear after a few seconds, please make a note of where you installed the software and then exit the installer. Next bring up a command prompt and change directory to the install directory, for example 

cd "c:\Program Files\NetCaboodle\server"

and then try to run the admin client directly with the following command. caboodle-admin.bat or sh caboodle-admin.sh on UNIX platforms. Please then contact us so we can help you diagnose why the installation process failed and also talk you though running the software without the installer.

Getting Started

When you first start up the Caboodle admin client it will automatically do the following so you can get started with Raven (the mobile client) without the need to configure any users or connectors.

  • Start the Caboodle server & gateway services
  • Create a JMX connector for the Caboodle server
  • Create a "guest" user and assign the Caboodle server's JMX connector to that user

Figure 3: Caboodle server admin

Getting started with Raven

Before embarking on creating new users and JMX connectors it is first worth familiarizing yourself with the Raven mobile client application by testing it with Sun's Wireless Toolkit. If you don't already have Sun's Wireless Toolkit (WTK) you can download it from http://java.sun.com/products/j2mewtoolkit/download-2_0.html

Having installed the WTK locate and run up the WTK "OTA provisioning" application. On Windows this can be founf under the WTK program group off the "Start" and "Programs" menu.

Now follow the steps below to download and run up the mobile Raven client application in the OTA provisioning device emulator.

  • Select the "Apps" option in the device emulator
  • Select "install applications" from the list available MIDlets
  • Click the "menu" option and select "Launch"
  • Next enter the OTA provisioning URL ("ota.htm") shown in the output window of the admin client e.g, http://192.168.0.2:8205/bin/ota.htm
  • Having entered the URL select the "Menu" option followed by the "Go" sub menu item.
  • You should now see "Raven" displayed as a single item in a list
  • Next click the install button and the Raven application will be downloaded.
  • Now select the "Install" option and "Raven" should appear in the installed applications list.
  • Finally use the "menu" option and select "Launch"

Assuming everything has gone according to plan you should now see the mobile Raven splash screen. Select the "Connect" option to log into the gateway. For more information on using the mobile Raven client please refer to Raven documentation, which you can find in the installation directory.

Running Raven over the Internet

To run Raven over the Internet you require the following configurations.

  • Internet connection
  • Firewall
  • Firewall configured to forward requests to the Caboodle server's host & port
  • Configured the "gatewayHost" property in the admin client to your Internet address.
  • Wireless device supporting the J2ME profile MIDP 1.0 or above

With the above configuration in place you can then use you your mobile devices to download and install the mobile Raven client application. Each device has a slightly different way of handling this, but in most cases you can use the device's Internet browser to point to the provisioning URL shown in the admin client's output window.

Caboodle server admin

The Caboodle server admin client provides the following functionality

  • Start, stop and configure the Caboodle server/gateway
  • Manage JMX connector configurations
  • Manage users and connector mappings

The Caboodle admin client has five tabs

  • Gateway
    This tab used to configure the gateway and start, stop the gateway services.
  • JMX Connectors
    This tab is used to create and manage the host/port JMX connectors
  • Users
    The Users tab allows you to create new users and assign connectors to them.
    Help
    Shows a cut down version of this document
  • Support
    This is a dynamically created view containing information that will help us answer any support inquiries. When you contact Net Caboodle support please copy and paste the contents of the support view into your email. Please note that the server log is included with the support information. We only really need to see any exceptions that might relate to the problem you are reporting.

JMX Connector configuration

The "Connector" tab allows you to setup the host/port JMX combinations that you have previously configured for your JVMs. To add new Connectors click the button on the toolbar. When you have completed adding or editing the connector table, click the button on the toolbar to commit your changes.

For each connector you need to specify the following information

  • Name
    This is the name that gets displayed in the mobile Raven application
  • Host
    This is the host on which the remote JVM is running
    Port
    This is the JMX RMI port you specified in your application's start script using     
    -Dcom.sun.management.jmxremote.port=
  • Lookup name
    By default this is set to "jmxrmi". You only need to change this value if you are connecting to a customer JMX server, which has a different name registered with the RMI registry.

Figure 4: JMX Connectors

Managing users

The "Users" tab provide you with the functionality to create user identities and "map" connectors to those users. Each mobile user is only permitted to use connectors configured for that user.

To create new users first select the "Users" node in the tree and then click on the button on the toolbar, when you have finished creating/modifying users you must click the button to commit those changes.

Mapping connectors

To map connectors to individual users, first select the user from the tree. This will then display the current connector mappings for the selected user. Use the button on the toolbar to delete existing connectors or use the button to add additional connectors, as shown in figure 5.

Figure 5: Mapping connectors to users


Caboodle gateway configuration

The Caboodle gateway has four configurable properties, which you can modify to suit your system/environment.

gatewayHost & gatewayPort properties
The "gatewayHost" parameter is used for the OTA provisioning of the Raven mobile client application. By default this property is set to host computer the gateway is running on to help you get started.

Please note that the address/host name assigned to this property is the address that the mobile Raven clients will use to access the gateway.

For professional deployments it is likely are that the IP address the mobile clients will connect to will be different than that of the host running the gateway. For example, mobile users might be connecting to a firewall with the address 81.xxx.xxx.xxx, which is connectable via the Internet, but the gateway is running on 192.168.xxx.xxx. In cases like these the firewall needs to configured to forward request to the 192.168.xxx.xxx address to the port number specified in the property "gatewayPort"

nThreads property
The "nThreads" property is used to specify how many threads the gateway should used for serving requests.

bindPort property
The "bindPort" property is used to specify a free port that the gateway can use for internal communications. You should only need to change this property if a port conflict is detected.

Starting the Caboodle server

The Caboodle server is automatically started when you launch the admin client as shown in figure 3 above.

Logging information from the server will be displayed in the window below the gateway properties table.

When the gateway starts up it will output the current OTA provisioning URLS for the mobile Raven client application. For example, 

Gateway port=8205 
Internal port=6066 
Raven OTA provisioning URLs 
http://192.168.0.2:8205/bin/ota.htm 
http://192.168.0.2:8205/bin/raven.jad

To stop/restart the gateway use the button on the toolbar. For information how to test your configurations see the previous section Getting started with Raven

Testing Raven with the sample applications

When the admin client starts up it configures a JMX connector for the Caboodle server. This is primarily to help getting started easier when using the software for the first time. However, you probably wont see any spectacular charts or be able to test the alert functionality in Raven.

If you are new to JMX then you can get started with some of the example applications included with this software, which you can find in the file examples.zip in the installation directory.

  • MemUser.java
    This example eats and spits out memory and is useful to test the "Alerts" feature in Raven
  • ThreadUser.java
    This example creates and disposes of threads and is useful to see the "Threads chart" in Raven in action

Both examples have sample start scripts for Windows and UNIX platforms. In the start script you will see an environment variable called JMX_PORT. The value set here is the value you need to use when creating a JMX connector in the admin client. Below is a brief description of how to run the examples.

  • Run the example with the Java 5.0 JRE
  • Create a JMX connector in the admin client that uses the same port number as the example's start script
  • Map the new connector to a user in the admin client
  • Restart the Caboodle server.

Support

If encounter any problems using the Caboodle server or Raven mobile client, please contact us
To help us provide you better and faster response time, please include the information in the admin client's support tab.

 

Copyright notice

The information within this document remains the sole property of Net Caboodle - www.netcaboodle.com

No part of this document may be copied or reproduced in any form or by any means, and the information
contained within it is not to be communicated to a third party, without the prior written consent of
Net Caboodle. All trademarks remain the property of their respective owners. NetCaboodle, Caboodle server
and Raven are all trademarks of Net Caboodle.