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.

Using the Rhino SDK on Windows

Using the Rhino SDK in the Windows Subsystem for Linux

After installing the Rhino SDK, you can find further information on using the tools for general operation, administration and maintenance in the Rhino Administration and Deployment Guide.

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.

Notices

Copyright © 2023 Microsoft. All rights reserved

This manual is issued on a controlled basis to a specific person on the understanding that no part of the Metaswitch Networks product code or documentation (including this manual) will be copied or distributed without prior agreement in writing from Metaswitch Networks.

Metaswitch Networks reserves the right to, without notice, modify or revise all or part of this document and/or change product features or specifications and shall not be responsible for any loss, cost, or damage, including consequential damage, caused by reliance on these materials.

Metaswitch and the Metaswitch logo are trademarks of Metaswitch Networks. Other brands and products referenced herein are the trademarks or registered trademarks of their respective holders.

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 and scripts written for the Bash shell.

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

The Bash shell is available on the majority of UNIX distributions and can be run on Windows using the Windows Subsystem for Linux.

Note The Rhino SDK has been tested on Red Hat, CentOS and Ubuntu Linux distributions and the WSL variant of Ubuntu Linux. No support is provided for running Rhino on other UNIX systems, although it is expected that the Rhino SDK will function on any POSIX system that can run a compatible JDK.

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.1 is supported on your version of Java.

Install System Utilities

To install the Rhino SDK a program capable of unzipping the SDK archive is required. The installation instructions assume the use of the unzip utility.

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. It is useful to export this variable to ensure it is available to all scripts and subshells and add it to your user config ~/.profile to make it available in future login sessions. Similarly, the path $JAVA_HOME/bin is useful in the PATH environment variable for running Java based development tools.

export JAVA_HOME="<path to installed jdk>"
export PATH="$JAVA_HOME/bin:$PATH"

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.

Download Installation Files

To install the Rhino SDK, download its installation package.

If you want to use the Rhino Element Manager (REM) to manage the SDK, download the relevant REM installation package as well.

Two versions of REM are available:

  • The standalone version: This version runs independently and works with both the SDK and the production versions of Rhino TAS.

  • The embeddable version: This version only runs inside the Rhino SDK. It doesn’t support the production version of Rhino. To use it in Rhino SDK 3.1 or later, you must manually embed the REM files into the SDK.

Make sure that you download the installation package for the version of REM you need.

Unpacking the Rhino SDK

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

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

  • To extract, use the unzip command:

    $ unzip rhino-sdk-3.1.x.zip

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

Embedding REM in the Rhino SDK

To use the embeddable version of REM to manage the Rhino SDK, first embed the required REM files in the SDK and enable the SDK to run REM as part of the Rhino process. If you want to use the standalone version of REM, see the Rhino Element Manager (REM) Guide.

To embed REM, take the following steps:

  1. Stop the Rhino SDK if it is running.

  2. Extract the installation package of the embeddable REM to the RhinoSDK/lib directory.

    The following files are added to the directory:

    • rem.war

    • rem-container.jar

  3. Enable the embedded REM in the SDK by changing the value of the REM_ENABLED configuration variable in RhinoSDK/config/config_variables to true, as shown below:

    # Element Manager
REM_ENABLED=true
    Note If you cannot find the file RhinoSDK/config/config_variables, start the SDK to generate it.

  4. Grant necessary permissions by uncommenting the following lines in RhinoSDK/config/rhino.policy:

    // permission java.io.FilePermission "$${rhino.dir.work}$${/}tmp$${/}-","read";
// permission java.lang.RuntimePermission "accessClassInPackage.sun.misc";
// permission java.lang.RuntimePermission "accessDeclaredMembers";

  5. Start the Rhino SDK.

    You can access REM at localhost:8066/rem/.

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.

Using the Rhino SDK on Windows

The Rhino SDK can be run on any POSIX system that has a Bourne shell and Java 11 JDK installed. On Windows this support is provided by the Windows Subsystem for Linux version 2 (WSL). WSL can be installed on Windows 10 or 11 by following the instructions at Install WSL | Microsoft Docs

Note The minimum release version of Windows 10 is Version 2004, Build 19041. Earlier versions of Windows 10 provide WSL version 1 which is not a supported environment.

To install Rhino in the WSL environment:

The Rhino SDK should now be running. The Rhino Element Manager is directly accessible on http://localhost:8066/rem. To connect using the Rhino console or other command-line management and monitoring utilities start a new WSL terminal from a Windows command prompt by running the wsl command. In the new terminal cd to the directory of the newly installed Rhino to find the command-line management utilities. These are present in the client/bin subdirectory of the Rhino directory.

For further information on using the tools for general operation, administration and maintenance, see the Rhino Administration and Deployment Guide.