This document is the first place to go to get started using the SDK (Software Development Kit) version of Rhino. It includes hardware and software requirements, installation instructions, and the basic steps for installing and running a Rhino SDK.

Topics

Preparing to Install the Rhino SDK

Checking hardware and operating system requirements, installing Java, and configuring the network

Unpacking the Rhino SDK

Unpacking the Rhino SDK

Running the Rhino SDK

Starting and stopping the Rhino SDK

Uninstalling the Rhino SDK

Stopping the Rhino SDK and deleting the directory.
Tip The SDK version of Rhino SLEE is intended to support development of prototype and proof-of-concept services, and evaluation of Rhino. It runs in a single Java Virtual Machine and does not provide all of the fault-tolerance capabilities of a production Rhino installation. A software development license that allows the use of production Rhino for development can be purchased from Metaswitch.

Other documentation for the Rhino TAS can be found on the Rhino TAS product page.

Preparing to Install the Rhino SDK

Before installing the Rhino SDK, you need to:

Check Hardware and Operating System Prerequisites

Rhino SDK requires a platform capable of running Oracle’s JDK or OpenJDK for Java Standard Edition (SE) 11.

The system requirements for running Java can be found on www.oracle.com.

Install Java

Follow the instructions on docs.oracle.com for installing Java. Ensure you download and install the JDK not the JRE. The JRE does not contain all the tools needed to run Rhino.

Warning Check the Rhino Compatibility Guide to ensure Rhino 3.0.0 is supported on your version of Java.

Set the JAVA_HOME environment variable (Optional)

You can set the JAVA_HOME environment variable to point to your Java installation or you can specify the Java home directory the first time you start the Rhino SDK.

Configure Network Features

Before installing Rhino, ensure that:

  • the system has an IP address and is visible on the network.

  • the system can resolve localhost to the loopback interface, and that the host name of the machine resolves to an external IP address, not a loopback address.

Unpacking the Rhino SDK

The Rhino SDK is delivered as a compressed zip file named rhino-sdk-3.0.0.x.zip.

To begin the Rhino installation, unzip rhino-sdk-3.0.0.x.zip:

  • To extract, use the unzip command:

    $ unzip rhino-sdk-3.0.0.x.zip

    This will create the directory RhinoSDK in the current working directory.

Running the Rhino SDK

This section includes the following topics:

Start the Rhino SDK

Below are details on the supported command-line arguments and instruction for starting the Rhino SDK.

Command-line arguments

The Rhino SDK start scripts support the following command-line options:

Option Purpose 
 -j <JAVA_HOME>

Specifies the path to a JDK installation that should be used to run the Rhino SDK. This option only has effect when starting the Rhino SDK for the first time. After the first start the file config/config_variables is read to find the JDK.

Important If you have not configured the JAVA_HOME environment variable, you must provide this argument the first time you start the Rhino SDK. 
 -s

Indicates that Rhino should be started with the SLEE in the Running state.

 
 -x

Indicates that Rhino should be started with the SLEE in the Stopping state.
Note

The -s and -x options are mutually exclusive.

In the case neither the -s nor -x option is specified, the following default behaviours occur:

  • If it is the first time that the Rhino SDK is started (or the persistent database has been reinitialised), then then SLEE starts in the Running state.

  • If the Rhino SDK has been shutdown and restarted, then the SLEE starts in whatever operational state it had before the previous shutdown.

Run start-rhino.sh

To start the Rhino SDK, execute the start-rhino.sh shell script in the RhinoSDK folder.

Stop the Rhino SDK

Below are instructions on stopping the Rhino SDK.

Run stop-rhino.sh with Linux

To stop the Rhino SDK, execute the stop-rhino.sh shell script in the $RHINO_HOME folder. This script has the following options:

$ ./stop-rhino.sh --help

Usage:
    stop-rhino.sh (--nice|--terminate|--kill|--restart)
    (Terminates the Rhino SDK.)
    Options:
    --nice          - Performs a clean shutdown of the SDK via management commands.
    --terminate     - Terminates the SDK via management commands.
    --kill          - Kills the SDK's JVM via unix system commands (unix only).
    --restart       - Restart the SDK via management commands.

For example:

$ ./stop-rhino.sh --nice
Shutting down the Rhino SDK.
Stopping the SLEE.
Waiting for SLEE to enter STOPPED state.
SLEE is in the Stopped state on node(s) [101]
Shutdown complete.
Warning The --restart option is not currently supported if a user-defined namespace exists in Rhino with a SLEE state that is not INACTIVE.

Rhino SDK Configuration Files

The Rhino SDK configuration is stored in the config directory of the Rhino home directory. This contains configuration files for Rhino and JVM settings.

File Purpose 
 config_variables

Basic Rhino configuration. The most common settings can be configured here

 
 jvm_args

All JVM configuration arguments including Java system properties for configuring Rhino.

Tip To add classes to the system classpath, edit the line starting with
-Drhino.runtime.classpath in this file. 
 logging.xml

Log keys, levels and appenders. Configuration of tracers as used by Resource Adaptors and Services is managed separately with the Rhino management interface

 
 rhino-config.xml

Configuration of Rhino facilities such as the timer facility and monitoring statistics collection.

 
 defaults.xml

Default settings for access control, limiters, logging, persistence and SNMP. Not used after first boot.

 
 init_*_db.sql

Scripts for initialising the Rhino management database

 
 jetty.xml

Configuration for the embedded Jetty web server used by the embedded REM instance.

 
 mlet.conf

Security permissions for JMX MLets. Configure if custom access permissions for management are required. Usually this is only required in production Rhino deployments.

 
 persistence.xml

Database configuration for persistent storage of Rhino settings, profiles and JDBC data sources.

 
 rhino.jaas

JAAS authentication settings. Configures how Rhino authenticates users of the management API and tools.

 
 rhino-boot.policy

Java security policy for the Rhino starter. Usually this should not be changed.

 
 rhino.policy

Java security policy for the Rhino application server. Edit this if you are developing a service with native components or additional database drivers. In general services and resource adaptors should have security permissions set in their respective descriptor files.

 
 rmissl.jmxr-adaptor.properties

Location of SSL keystores for JMX authentication

 
 runtime.xml

Configuration of Symmetric Activation for production Rhino clusters. Not functional in the Rhino SDK.

(Optionally) Configure Rhino SDK to use PostgreSQL

Use the following procedures to (optionally) use PostgreSQL instead of Derby with the Rhino SLEE SDK.

Note

The Rhino SLEE SDK uses a Derby embedded database to store its internal state. There is generally nothing to configure with the Derby database. It is stored in $RHINO_HOME/work/rhino_sdk, and the default configuration variables should work. You only need to be aware of the embedded Derby database if you want to remove all state from the SDK (using the init-management-db.sh script).

The Rhino SLEE SDK can optionally be reconfigured to use PostgreSQL to store state. It can use either the Derby embedded database or PostgreSQL, but not both at the same time.

1
Install PostgreSQL

PostgreSQL is usually available from your Linux distribution repositories.

2
Create a user

Once PostgreSQL has been installed, the next step is to create or assign a database user for the Rhino SLEE. This user will need permissions to create databases, but does not need permissions to create users. Use the createuser script supplied with PostgreSQL, as follows:

[postgres]$ createuser
Enter name of user to add: rhino
Shall the new user be allowed to create databases? (y/n) y
Shall the new user be allowed to create more new users? (y/n) n
CREATE USER

3
Configure access control

The default PostgreSQL installation trusts connections from the local host. If the Rhino SLEE and PostgreSQL are installed on the same host, the access control for the default configuration is sufficient. Below is a sample access-control configuration, from the file $PGDATA/pg_hba.conf:

#TYPE DATABASE USER IP-ADDRESS IP-MASK METHOD
local all all trust
host all all 127.0.0.1 255.255.255.255 trust

When you need to install the Rhino SLEE and PostgreSQL on separate hosts, or need a stricter security policy, you’ll need to tailor the access control rules in $PGDATA/pg_hba.conf to allow connections from Rhino to the database manager. For example, to allow connections from a Rhino instance on another host, make the following changes:

#TYPE DATABASE USER IP-ADDRESS IP-MASK METHOD
local all all trust
host all all 127.0.0.1 255.255.255.255 trust
host rhino rhino 192.168.0.5 255.255.255.0 password

After making these changes, you’ll need to completely restart the PostgreSQL server. Telling the server to reload the configuration file does not cause it to enable TCP/IP networking as this is initialised when the database is initialised. To restart PostgreSQL, either use the command supplied by the package (for example, /etc/init.d/postgresql restart), or use the pg_ctl restart command provided with PostgreSQL.

5
Edit configuration variables

By default, the Rhino SLEE SDK uses its own Derby embedded database. To use PostgreSQL rather than Derby, make the following changes.

  1. Edit the following configuration variables in the file $RHINO_HOME/config/config_variables, to point to your PostgreSQL configuration:

    # Management database settings
MANAGEMENT_DATABASE_NAME=rhino_sdk
MANAGEMENT_DATABASE_HOST=localhost
MANAGEMENT_DATABASE_PORT=5432
MANAGEMENT_DATABASE_USER=username
MANAGEMENT_DATABASE_PASSWORD=changeit
    Warning If you cannot find the file $RHINO_HOME/config/config_variables, this probably means that you haven’t run the start-rhino.sh script yet. Please run it first to generate a $RHINO_HOME/config/config_variables file.

  2. Edit the file $RHINO_HOME/config/persistence.xml. Find the <persistence-resource> elements with the names management and profiles and change their <persistence-resource-ref> sub-elements to reference the persistence resource with the name postgres instead of derby.

Note If the $RHINO_HOME/config/persistence.xml is ever deleted, the Rhino SLEE SDK will reconstruct its content from the values contained in $RHINO_HOME/config/defaults.xml. If you wish the change to use PostgreSQL to be more permanent in this case, then edit the $RHINO_HOME/config/defaults.xml file in the same way.

6
Initialise the PostgreSQL database

To initialise the database, run:

./init-management-db.sh postgres
Warning From now on, you will always need to pass the word postgres to this script.

Now, executing start-rhino.sh should start the Rhino SLEE using the PostgreSQL database backend.

(Optionally) Configure Session Ownership Facility Support

The session ownership subsystem is an optional Rhino platform extension with the primary purpose of allowing SLEE services and resource adaptors on a given node to claim ownership of a particular thing such as an individual SLEE activity or a complete identifiable session .

The Cassandra session ownership store implementation is included with a Rhino SDK installation. It is disabled by default but can be enabled following these configuration steps.

Note that the Rhino SDK does not offer an automated means of enabling the session ownership subsystem. The configuration steps need to be followed manually.

Uninstalling the Rhino SDK

To uninstall the Rhino SDK:

1

Stop the Rhino SDK.

2

Delete the directory into which the Rhino SDK was installed.

Note The Rhino SDK keeps all of its files in the same directory and does not store data elsewhere on the system.