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
Checking hardware and operating system requirements, installing Java, and configuring the network |
|
Unpacking the Rhino SDK |
|
Starting and stopping the Rhino SDK |
|
Stopping the Rhino SDK and deleting the directory. |
|
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.
![]() |
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.
![]() |
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.
![]() |
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:
-
Stop the Rhino SDK if it is running.
-
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
-
-
Enable the embedded REM in the SDK by changing the value of the
REM_ENABLED
configuration variable inRhinoSDK/config/config_variables
totrue
, as shown below:# Element Manager REM_ENABLED=true
If you cannot find the file RhinoSDK/config/config_variables
, start the SDK to generate it. -
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";
-
Start the Rhino SDK.
You can access REM at localhost:8066/rem/.
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
|
||
-s |
Indicates that Rhino should be started with the SLEE in the |
||
-x |
Indicates that Rhino should be started with the SLEE in the |
![]() |
The In the case neither the
|
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.
![]() |
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.
|
||
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.
![]() |
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 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 [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 #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 #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, |
||||
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.
|
||||
6 |
Initialise the PostgreSQL database
To initialise the database, run: ./init-management-db.sh postgres
Now, executing |
(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 |
|||
---|---|---|---|
2 |
Delete the directory into which the Rhino SDK was installed.
|
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
![]() |
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:
-
Download and unpack the Rhino SDK. Typically, the Rhino SDK will have been saved to the Windows Downloads directory. In WSL this can be found at the path
/mnt/c/Users/username/Downloads/rhino-sdk-install-…zip
.
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.