This document details basic procedures for system administrators managing, maintaining, configuring and deploying Rhino 2.7 using the command-line console. To manage using a web interface, see the Rhino Element Manager documentation.

Topics

SLEE Management

Administrative tasks for day-to-day management of the Rhino SLEE, its components and entities deployed in it, including: operational state, deployable units, services, resource adaptor entities, per-node activation state, profile tables and profiles, alarms, usage, user transactions, and component activation priorities.

Rhino Configuration

Procedures for configuring Rhino upon installation, and as needed (for example to tune performance), including: logging, staging, object pools, licenses, rate limiting, security and external databases.

Application-State Maintenance

Finding Housekeeping MBeans, and finding, inspecting and removing one or all activities or SBB entities.

Backup and Restore

Backing up and restoring the database, and exporting and importing SLEE deployment state.

SNMP Management

Managing the SNMP subsystem in Rhino, including: configuring the agent, managing MIB files, assigning OID mappings.

Replication Support Services

Configuring supplementary replication support services such as the session ownership store.

Management Tools

Tools included with Rhino for system administrators to manage Rhino.

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

SLEE Management

This section covers general administrative tasks for day-to-day management of the Rhino SLEE, its components and entities deployed in it.

JMX MBeans

Rhino SLEE uses Java Management Extension (JMX) MBeans for management functionality. This includes both functions defined in the JAIN SLEE 1.1 specification and Rhino extensions that allow additional functionality, beyond what’s in the specification.

Rhino’s command-line console is a front end for these MBeans, providing access to functions for managing:

Management may also be performed via the Rhino Element Manager web interface.

Namespaces

As well as an overview of Rhino namespaces, this section includes instructions for performing the following Rhino SLEE procedures, with explanations, examples, and links to related javadocs:

Procedure rhino-console command MBean → Operation
createnamespace
Namespace Management → createNamespace
removenamespace
Namespace Management → removeNamespace
listnamespaces
Namespace Management → getNamespaces

Setting the active namespace
for a client connection

-n <namespace> (command-line option)
setactivenamespace (interactive command)
Namespace Management → setActiveNamespace

Getting the active namespace
for a client connection


         
Namespace Management → getActiveNamespace

About Namespaces

A namespace is an independent deployment environment that is isolated from other namespaces.

A namespace has:

  • its own SLEE operational state

  • its own set of deployable units

  • its own set of instantiated profile tables, profiles, and resource adaptor entities

  • its own set of component configuration state

  • its own set of activation states for services and resource adaptor entities.

All of these things can be managed within an individual namespace without affecting the state of any other namespace.

Tip A namespace can be likened to a SLEE in itself, where Rhino with multiple namespaces is a container of SLEEs.

A Rhino cluster always has a default namespace that cannot be deleted. Any number of user-defined namespaces may also be created, managed, and subsequently deleted when no longer needed.

Management clients by default interact with the default namespace unless they explicitly request to interact with a different namespace.

Creating a Namespace

To create a new namespace, use the following rhino-console command or related MBean operation.

Console command: createnamespace

Command

createnamespace <name> [-replication-resource <resource-name>]
[-with-session-ownership-facility]
  Description
    Create a new deployment namespace. If the optional replication resource is not
    specified then the resource used for this namespace is the same as that used in
    the default namespace.

Example

$ ./rhino-console createnamespace testnamespace
Namespace testnamespace created

MBean operation: createNamespace

MBean

Rhino extension

public void createNamespace(String name, NamespaceOptions options)
  throws NullPointerException, InvalidArgumentException,
    NamespaceAlreadyExistsException, ManagementException;

Removing a Namespace

To remove an existing user-defined namespace, use the following rhino-console command or related MBean operation.

Tip The default namespace cannot be removed.
Note All deployable units (other than the deployable unit containing the standard JAIN SLEE-defined types) must be uninstalled and all profile tables removed from a namespace before that namespace can be removed.

Console command: removenamespace

Command

removenamespace <name>
  Description
    Remove an existing deployment namespace

Example

$ ./rhino-console removenamespace testnamespace
Namespace testnamespace removed

MBean operation: removeNamespace

MBean

Rhino extension

public void removeNamespace(String name)
  throws NullPointerException, UnrecognizedNamespaceException,
    InvalidStateException, ManagementException;

Listing Namespaces

To list all user-defined namespaces in a SLEE, use the following rhino-console command or related MBean operation.

Console command: listnamespaces

Command

listnamespaces [-v]
  Description
    List all deployment namespaces.  If the -v (verbose) option is given then the
    options that each namespace was created with is also given

Example

$ ./rhino-console listnamespaces
testnamespace

MBean operation: getNamespaces

MBean

Rhino extension

public String[] getNamespaces()
  throws ManagementException;

This operation returns the names of the user-defined namespaces that have been created.

Setting the Active Namespace

Each individual authenticated client connection to Rhino is associated with a namespace.

This setting, known as the active namespace, controls which namespace is affected by management commands such as those that install deployable units or change operational states.

To change the active namespace for a client connection, use the following rhino-console command or related MBean operation.

Console command: setactivenamespace

Command and command-line option

Interactive mode

In interactive mode, the setActiveNamespace command can be used to set the active namespace for future management operations.

setactivenamespace <-default|name>
  Description
    Set the active namespace
Non-interactive mode

In non-interactive mode, the -n command-line option can be used to select the namespace that the executed command is processed against.

Example

Interactive mode
$ ./rhino-console
Interactive Rhino Management Shell
Rhino management console, enter 'help' for a list of commands
[Rhino@localhost (#0)] setactivenamespace testnamespace
The active namespace is now testnamespace
[Rhino@localhost [testnamespace] (#1)] setactivenamespace -default
The active namespace is now the default namespace
[Rhino@localhost (#2)]

Non-interactive mode
$ ./rhino-console -n testnamespace start
The active namespace is now testnamespace
Starting SLEE on node(s) [101]
SLEE transitioned to the Starting state on node 101

MBean operation: setActiveNamespace

MBean

Rhino extension

public void setActiveNamespace(String name)
  throws NoAuthenticatedSubjectException, UnrecognizedNamespaceException,
    ManagementException;

This operation sets the active namespace for the client connection. A null parameter value can be used to specify that the default namespace should be made active.

Getting the Active Namespace

To get the active namespace for a client connection, use the following rhino-console information and related MBean operation.

Console:

Command prompt information

The currently active namespace is reported in the command prompt within square brackets.

If no namespace is reported, then the default namespace is active.

Example

$ ./rhino-console
Interactive Rhino Management Shell
Rhino management console, enter 'help' for a list of commands
[Rhino@localhost (#0)] setactivenamespace testnamespace
The active namespace is now testnamespace
[Rhino@localhost [testnamespace] (#1)] setactivenamespace -default
The active namespace is now the default namespace
[Rhino@localhost (#2)]

MBean operation: getActiveNamespace

MBean

Rhino extension

public String getActiveNamespace()
  throws NoAuthenticatedSubjectException, ManagementException;

This operation returns the name of the namespace currently active for the client connection.

Operational State

As well as an overview of SLEE operational states, this section includes instructions for performing the following Rhino SLEE procedures, with explanations, examples and links to related javadocs:

Procedure rhino-console command MBean → Operation
start
SLEE Management → start
stop
SLEE Management → stop

Retrieving the basic operational state of nodes

state
SLEE Management → getState

Retrieving detailed information for every node in the cluster

getState
Rhino Housekeeping → getClusterState

Gracefully shutting nodes down

shutdown
SLEE Management → shutdown

Forcefully terminating nodes

kill
SLEE Management → kill

Gracefully rebooting nodes

reboot
SLEE Management → reboot

Enabling the symmetric activation state mode

enablesymmetricactivationstatemode
Runtime Config Management → enableSymmetricActivationStateMode

Disabling the symmetric activation state mode

disablesymmetricactivationstatemode
Runtime Config Management → disableSymmetricActivationStateMode

Getting the current activation state mode

getsymmetricactivationstatemode
Runtime Config Management → isSymmetricActivationStateModeEnabled

Listing nodes with per-node activation state

getnodeswithpernodeactivationstate
Node Housekeeping → getNodesWithPerNodeActivationState

Copying per-node activation state to another node

copypernodeactivationstate
Node Housekeeping → copyPerNodeActivationState

Removing per-node activation state

removePerNodeActivationState
Node Housekeeping → removePerNodeActivationState

About SLEE Operational States

The SLEE specification defines the operational lifecycle of a SLEE — illustrated, defined, and summarised below.

SLEE lifecycle
Figure 1. The SLEE lifecycle

SLEE lifecycle states

The SLEE lifecycle states are:

State Definition
STOPPED

The SLEE has been configured and initialised, and is ready to be started. Active resource adaptor entities have been loaded and initialised, and SBBs corresponding to active services have been loaded and are ready to be instantiated. The entire event-driven subsystem, however, is idle: resource adaptor entities and the SLEE are not actively producing events, the event router is not processing work, and the SLEE is not creating SBB entities.

STARTING

Resource adaptor entities in the SLEE that have been recorded in the management database as being in the ACTIVE state are started. The SLEE still does not create SBB entities.

The node automatically transitions from this state to the RUNNING state when all startup tasks are complete, or to the STOPPING state if a startup task fails.

RUNNING

Activated resource adaptor entities in the SLEE can fire events, and the SLEE creates SBB entities and delivers events to them as needed.

STOPPING

Identical to the RUNNING state, except resource adaptor entities do not create (and the SLEE does not accept) new activity objects. Existing activity objects can end (according to the resource adaptor specification).

The node automatically transitions out of this state, returning to the STOPPED state, when all SLEE activities have ended. The node can transition to this state directly from the STARTING state, effective immediately, if it has no activity objects.

Independent SLEE states

Each namespace in each event-router node in a Rhino cluster maintains its own SLEE-lifecycle state machine, independent from other namespaces on the same or other nodes in the cluster. For example:

  • the default namespace on one node in a cluster might be in the RUNNING state

  • while a user-defined namespace on the same node is in the STOPPED state

  • while the default namespace on another node is in the STOPPING state

  • and the user-defined namespace on that node is in the RUNNING state.

The operational state of each namespace on each cluster node persists to the disk-based database.

Bootup SLEE state

After completing bootup and initialisation, a namespace on a node will enter the STOPPED state if:

  • the database has no persistent operational state information for that namespace on that node;

  • the namespace’s persistent operational state is STOPPED on that node; or

  • the node was started with the -x option (see Start Rhino in the Rhino Getting Started Guide).

Otherwise, the namespace will return to the same operational state that it was last in, as recorded in persistent storage.

Changing a namespace’s operational state

You can change the operational state of any namespace on any node at any time, as long as least one node in the cluster is available to perform the management operation (regardless of whether or not the node whose operational state being changed is a current cluster member). For example, you might set the operational state of the default namespace on node 103 to RUNNING before node 103 is started — then, when node 103 is started, after it completes initialising, the default namespace will enter the RUNNING state.

Warning
Changing a quorum node’s operational state

You can also change the operational state of a node which is a current member of the cluster as a quorum node…​ but quorum nodes make no use of operational state information stored in the database, and will not respond to operational state changes. (A node only uses operational state information if it starts as a regular event-router node.)

Starting the SLEE

To start a SLEE on one or more nodes, use the following rhino-console command or related MBean operation.

Console command: start

Command

start [-nodes node1,node2,...] [-ifneeded]
  Description
    Start the SLEE (on the specified nodes)

Example

To start nodes 101 and 102:

$ ./rhino-console start -nodes 101,102
Starting SLEE on node(s) [101,102]
SLEE transitioned to the Starting state on node 101
SLEE transitioned to the Starting state on node 102

MBean operation: start

MBean

SLEE-defined

Start all nodes
public void start()
  throws InvalidStateException, ManagementException;

Rhino’s implementation of the SLEE-defined start operation attempts to transition all event-router nodes in the primary component from the STOPPED to the STARTING state. For this to work, all nodes must be in the STOPPED state.

Rhino extension

Start specific nodes
public void start(int[] nodeIDs)
  throws NullPointerException, InvalidArgumentException,
    InvalidStateException, ManagementException;

Rhino provides an extension that adds an argument which lets you control which nodes to start (by specifying node IDs). For this to work, the specified nodes must be in the STOPPED state.

Stopping the SLEE

To stop SLEE event-routing functions on one or more nodes, use the following rhino-console command or related MBean operation.

Console command: stop

Command

stop [-nodes node1,node2,...] [-reassignto -node3,node4,...] [-ifneeded]
  Description
    Stop the SLEE (on the specified nodes (reassigning replicated activities to the
    specified nodes))

Examples

To stop nodes 101 and 102:

$ ./rhino-console stop -nodes 101,102
Stopping SLEE on node(s) [101,102]
SLEE transitioned to the Stopping state on node 101
SLEE transitioned to the Stopping state on node 102

To stop only node 101 and reassign replicated activities to node 102:

$ ./rhino-console stop -nodes 101 -reassignto 102
Stopping SLEE on node(s) [101]
SLEE transitioned to the Stopping state on node 101
Replicated activities reassigned to node(s) [102]

To stop node 101 and distribute replicated activities of each replicating resource adaptor entity to all other eligible nodes (those on which the resource adaptor entity is in the ACTIVE state and the SLEE is in the RUNNING state), specify an empty (zero-length) argument for the -reassignto option:

$ ./rhino-console stop -nodes 101 -reassignto ""
Stopping SLEE on node(s) [101]
SLEE transitioned to the Stopping state on node 101
Replicated activities reassigned to node(s) [102,103]
Tip See also Reassigning a Resource Adaptor Entity’s Activities to Other Nodes, particularly the Requirements tab.

MBean operation: stop

MBean

SLEE-defined

Stop all nodes
public void stop()
  throws InvalidStateException, ManagementException;

Rhino’s implementation of the SLEE-defined stop operation attempts to transition all event-router nodes in the primary component from the RUNNING to the STOPPING state. For this to work, all nodes must begin in the RUNNING state.

Rhino extensions

Stop specific nodes
public void stop(int[] nodeIDs)
  throws NullPointerException, InvalidArgumentException,
    InvalidStateException, ManagementException;

Rhino provides an extension that adds an argument which lets you control which nodes to stop (by specifying node IDs). For this to work, specified nodes must begin in the RUNNING state.


Reassign activities to other nodes
public void stop(int[] stopNodeIDs, int[] reassignActivitiesToNodeIDs)
  throws NullPointerException, InvalidArgumentException,
    InvalidStateException, ManagementException;

Rhino also provides an extension that adds another argument, which lets you reassign ownership of replicated activities (from replicating resource adaptor entities) from the stopping nodes, distributing the activities of each resource adaptor entity equally among other event-router nodes where the resource adaptor entity is eligible to adopt them. With a smaller set of activities, the resource adaptor entities on the stopping nodes can more quickly return to the INACTIVE state (which is required for the SLEE to transition from the STOPPING to the STOPPED state). This only works for resource adaptor entities that are replicating activity state (see the description of the "Rhino-defined configuration property" on the MBean tab on Creating a Resource Adaptor Entity). See also Reassigning a Resource Adaptor Entity’s Activities to Other Nodes, in particular the Requirements tab.

Retrieving the State of Nodes

Basic Operational State of a Node

To retrieve the basic operational state of a node, use the following rhino-console command or related MBean operation.

Console command: state

Command

state [-nodes node1,node2,...]
  Description
    Get the state of the SLEE (on the specified nodes)

Output

The rhino-console client displays the operational state of the specified node(s), or every event-router node in the primary component if none are specified.

Examples

To display the state of only node 101:

$ ./rhino-console state -nodes 101
Node 101 is Stopped

To display the state of every event-router node:

$ ./rhino-console state
Node 101 is Stopped
Node 102 is Running

MBean operation: getState

MBean

SLEE-defined

Return state of current node
public SleeState getState()
  throws ManagementException;

Rhino’s implementation of the SLEE-defined getState operation returns the state of the node where the operation is invoked.

Rhino extension

Return state of specific nodes
public SleeState[] getState(int[] nodeIDs)
  throws NullPointerException, InvalidArgumentException,
    ManagementException;

Rhino provides an extension that adds an argument which lets you control which nodes to examine (by specifying node IDs).

Detailed Information for Every Node in the Cluster

To retrieve detailed information for every node in the cluster (including quorum nodes), use the following rhino-console command or related MBean operation.

Console command: getclusterstate

Command

getclusterstate
  Description
    Display the current state of the Rhino Cluster

Output

For every node in the cluster, retrieves detailed information on the:

  • node ID

  • type (event-router or quorum)

  • host name of the machine the node is running on

  • time the node was started, and how long it has been alive

  • operational state

  • number of alarms currently raised on the node.

Example

$ ./rhino-console getclusterstate
node-id   active-alarms   host               node-type      slee-state   start-time          up-time
--------  --------------  -----------------  -------------  -----------  ------------------  -----------------
     101               0   host1.domain.com   event-router      Stopped   20080327 12:16:26    0days,2h,40m,3s
     102               0   host2.domain.com   event-router      Running   20080327 12:16:30   0days,2h,39m,59s
     103               0   host3.domain.com         quorum          n/a   20080327 14:36:25    0days,0h,20m,4s

MBean operation: getClusterState

MBean

Rhino extension

public TabularData getClusterState()
throws ManagementException;

(Refer to the javadoc for the structure of the TabularData returned by this operation.)

Terminating Nodes

To terminate cluster nodes, you can:

Note

You can stop functions on nodes and nodes themselves, by:

  • Stopping  — stops event-routing functions on the node, but the node remains alive and a member of the primary component.

  • Shutting down — terminates the node (so that it leaves the primary component). A node must in the STOPPED state before it can be shut down.

  • Killing  — terminates the node regardless of its operational state. Killing a node is not recommended unless the node cannot be shut down normally (for example, the node becomes stuck in the STOPPING state for some reason).

See also Stop Rhino in the Getting Started Guide, which details using the stop-rhino.sh script (which uses the rhino-console commands described in this section) to shut down or kill nodes or clusters.

Shut Down Gracefully

To gracefully shut down one or more nodes, use the following rhino-console command or related MBean operation.

Console command: shutdown

Command

shutdown [-nodes node1,node2,...] [-timeout timeout] [-restart]
  Description
    Gracefully shutdown the SLEE (on the specified nodes). The optional timeout is
    specified in seconds. Optionally restart the node(s) after shutdown

Examples

To shut down the entire cluster:

$ ./rhino-console shutdown
Shutting down the SLEE
Shutdown successful

To shut down only node 102:

$ ./rhino-console shutdown -nodes 102
Shutting down node(s) [102]
Shutdown successful

MBean operation: shutdown

MBean

SLEE-defined

Shut down all nodes
public void shutdown()
  throws InvalidStateException, ManagementException;

Rhino’s implementation of the SLEE-defined shutdown operation terminates every node in the cluster.

Rhino extension

Shut down specific nodes
public void shutdown(int[] nodeIDs)
  throws NullPointerException, InvalidArgumentException,
    InvalidStateException, ManagementException;

Rhino provides an extension that adds an argument which lets you control which nodes to shut down (by specifying node IDs).

Warning Event-router nodes can only be shut down when STOPPED — if any in the set of nodes that a shutdown operation targets is not in the STOPPED state, the shutdown operation will fail (and no nodes will shut down). Quorum nodes can be shut down at any time.

Forcefully Terminate

To forcefully terminate a cluster node that is in any state where it can respond to management operations, use the following rhino-console command or related MBean operation.

Console command: kill

Command

kill -nodes node1,node2,...
  Description
    Forcefully terminate the specified nodes (forces them to become non-primary)

Example

To forcefully terminate nodes 102 and 103:

$ ./rhino-console kill -nodes 102,103
Terminating node(s) [102,103]
Termination successful

MBean operation: kill

MBean

Rhino operation

public void kill(int[] nodeIDs)
  throws NullPointerException, InvalidArgumentException,
    ManagementException;

Rhino’s kill operation immediately and forcefully terminates specified nodes. It requires an argument to select which nodes to terminate (by specifying node IDs).

Caution
Application state may be lost

Killing a node is not recommended — forcibly terminated nodes lose all non-replicated application state.

Rebooting Nodes

To gracefully reboot one or more nodes, use the following rhino-console command or related MBean operation.

Console command: reboot

Command

reboot [-nodes node1,node2,...] {-state state | -states state1,state2,...}
  Description
    Gracefully shutdown the SLEE (on the specified nodes), restarting into either
    the running or stopped state.
  Use either the -state argument to set the state for all nodes or the -states
  argument to set it separately for each node rebooted.
  If a list of nodes is not provided then -state must be used to set the state of
  all nodes.
  Valid states are (r)unning and (s)topped

Examples

To reboot the entire cluster:

$ ./rhino-console reboot -states running,running,stopped
Restarting node(s) [101,102,103] (using Rhino's default shutdown timeout)
Restarting

To shut down only node 102:

$ ./rhino-console reboot -nodes 102 -states stopped
Restarting node(s) [102] (using Rhino's default shutdown timeout)
Restarting

MBean operation: reboot

MBean

Rhino extension

Reboot all nodes
public void reboot(SleeState[] states)
  throws InvalidArgumentException, InvalidStateException, ManagementException;

Reboots every node in the cluster to the state specified.

Rhino extension

Reboot specific nodes
public void reboot(int[] nodeIDs, SleeState[])
  throws NullPointerException, InvalidArgumentException, InvalidStateException, ManagementException;

Extension to reboot that adds an argument which lets you control which nodes to shut down (by specifying node IDs).

Note Event-router nodes can restart to either the RUNNING state or the STOPPED state. Quorum nodes must have a state provided but do not use this in operation.

Activation State

As well as an overview of activation state modes, this section includes instructions for performing the following Rhino SLEE procedures, with explanations, examples, and links to related javadocs:

Procedure rhino-console command MBean → Operation

Enabling the symmetric activation state mode

enablesymmetricactivationstatemode
Runtime Config Management → enableSymmetricActivationStateMode

Disabling the symmetric activation state mode

disablesymmetricactivationstatemode
Runtime Config Management → disableSymmetricActivationStateMode

Getting the current activation state mode

getsymmetricactivationstatemode
Runtime Config Management → isSymmetricActivationStateModeEnabled

Listing nodes with per-node activation state

getnodeswithpernodeactivationstate
Node Housekeeping → getNodesWithPerNodeActivationState

Copying per-node activation state to another node

copypernodeactivationstate
Node Housekeeping → copyPerNodeActivationState

Removing per-node activation state

removePerNodeActivationState
Node Housekeeping → removePerNodeActivationState

About Activation State Modes

Rhino has two modes of operation for managing the activation state of services and resource adaptor entities: per-node and symmetric.

The activation state for the SLEE event-routing functions is always maintained on a per-node basis.

Per-node activation state

In the per-node activation state mode, Rhino maintains activation state for the installed services and created resource adaptor entities in a namespace on a per-node basis. That is, the SLEE records separate activation state information for each individual cluster node.

The per-node activation state mode is the default mode in a newly installed Rhino cluster.

Symmetric activation state

In the symmetric activation state mode, Rhino maintains a single cluster-wide activation state view for each installed service and created resource adaptor entity. So, for example, if a service is activated, then it is simultaneously activated on every cluster node. If a new node joins the cluster, then the services and resource adaptor entities on that node each enter the same activation state as for existing cluster nodes.

Warning

MBean operations affecting the activation state of services or resource adaptor entities that accept a list of node IDs to apply the operation to, such as the ServiceManagementMBean activate operation, cannot be used while the symmetric activation state mode is in force.

Similary, MBean operations that inspect or manage per-node activation state, such as the NodeHousekeepingMBean copyPerNodeActivationState operation, also cannot be used while the symmetric activation state mode is in force.

Symmetric Activation State

This section includes instructions for performing the following Rhino SLEE procedures, with explanations, examples and links to related javadocs:

Procedure rhino-console command MBean → Operation
enablesymmetricactivationstatemode
Runtime Config Management → enableSymmetricActivationStateMode
disablesymmetricactivationstatemode
Runtime Config Management → disableSymmetricActivationStateMode
getsymmetricactivationstatemode
Runtime Config Management → isSymmetricActivationStateModeEnabled

Enable Symmetric Activation State Mode

To switch from the per-node activation state mode to the symmetric activation state mode, use the following rhino-console command or related MBean operation.

Console command: enablesymmetricactivationstatemode

Command

enablesymmetricactivationstatemode <template-node-id>
  Description
    Enable symmetric activation state mode of services and resource adaptor entities
    across the cluster.  Components across the cluster will assume the state of the
    specified template node

Example

$ ./rhino-console enablesymmetricactivationstatemode 101
Symmetric activation state mode enabled using node 101 as a template

MBean operation: enableSymmetricActivationStateMode

MBean

Rhino operation

public void enableSymmetricActivationStateMode(int templateNodeID)
    throws InvalidStateException, InvalidArgumentException,
      ConfigurationException;

This operation activates and/or deactivates services and resource adaptor entities on other cluster nodes such that their activation state matches that of the template node.

If a service or resource adaptor entity is deactivated on a node where the SLEE operational state is RUNNING or STOPPING, that service or resource adaptor entity will enter the STOPPING state and be allowed to drain before it transitions to the INACTIVE state.

Disable Symmetric Activation State Mode

To switch from the symmetric activation state mode back to the per-node activation state mode, use the following rhino-console command or related MBean operation.

Console command: disablesymmetricactivationstatemode

Command

disablesymmetricactivationstatemode
  Description
    Disable symmetric activation state mode of services and resource adaptor
    entities across the cluster, such that components may have different activation
    states on different nodes

Example

$ ./rhino-console disablesymmetricactivationstatemode
Symmetric activation state mode disabled

MBean operation: disableSymmetricActivationStateMode

MBean

Rhino operation

public void disableSymmetricActivationStateMode()
    throws InvalidStateException, ConfigurationException;

This operation disables the symmetric activation state mode, thus restoring the per-node activation state mode. The existing activation states of services and resource adaptor entities are not affected by this operation — the per-node activation state of each service and resource adaptor entity is simply set to the current corresponding symmetric state.

Get the Current Activation State Mode

To determine if the symmetric activation state mode is enabled or disabled, use the following rhino-console command or related MBean operation.

If the symmetric activation state mode is disabled, then the per-node activation state mode consequently must be in force.

Console command: getsymmetricactivationstatemode

Command

getsymmetricactivationstatemode
  Description
    Display the current status of the symmetric activation state mode

Example

$ ./rhino-console getsymmetricactivationstatemode
Symmetric activation state mode is currently enabled

MBean operation: isSymmetricActivationStateModeEnabled

MBean

Rhino operation

public boolean isSymmetricActivationStateModeEnabled()
    throws ConfigurationException;

Per-Node Activation State

This section includes instructions for performing the following Rhino SLEE procedures, with explanations, examples, and links to related javadocs.

Procedure rhino-console command MBean → Operation
getnodeswithpernodeactivationstate
Node Housekeeping → getNodesWithPerNodeActivationState
copypernodeactivationstate
Node Housekeeping → copyPerNodeActivationState
removepernodeactivationstate
Node Housekeeping → removePerNodeActivationState

Listing Nodes with Per-Node Activation State

To get a list of nodes with per-node activation state, use the following rhino-console command or related MBean operation.

Console command: getnodeswithpernodeactivationstate

Command

getnodeswithpernodeactivationstate
  Description
    Get the set of nodes for which per-node activation state exists

Example

$ ./rhino-console getnodeswithpernodeactivationstate
Nodes with per-node activation state: [101,102,103]

MBean operation: getNodesWithPerNodeActivationState

MBean

Rhino operation

public int[] getNodesWithPerNodeActivationState()
    throws ManagementException;

This operation returns an array, listing the cluster node IDs for nodes that have per-node activation state recorded in the database).

Copying Per-Node Activation State to Another Node

To copy per-node activation state from one node to another, use the following rhino-console command or related MBean operation.

Console command: copypernodeactivationstate

Command

copypernodeactivationstate <from-node-id> <to-node-id>
  Description
    Copy per-node activation state from one node to another

Example

To copy the per-node activation state from node 101 to node 102:

$ ./rhino-console copypernodeactivationstate 101 102
Per-node activation state copied from 101 to 102
Warning

The target node cannot be a current cluster member (unless the node is a quorum node, as quorum nodes do not make use of this state). When the target node is started (as an event-router node), it will assume the same activation state for the SLEE, services and resource adaptor entities as the node from which the per-node activation state was copied.

Per-node activation state cannot be copied to a target node if that node already has some per-node activation state recorded for it in the database. To remove per-node activation state for a target node, see Removing Per-Node Activation State.

MBean operation: copyPerNodeActivationState

MBean

Rhino operation

public boolean copyPerNodeActivationState(int targetNodeID)
    throws UnsupportedOperationException, InvalidArgumentException,
           InvalidStateException, ManagementException;

This operation:

  • copies the per-node activation state recorded in the database for the node for which the Node Housekeeping MBean was created (see Finding Housekeeping MBeans) to the given target node

  • returns the value true if it found and copied per-node activation state, or false if it found no per-node activation state to copy.

Note The start-rhino.sh command with the Production version of Rhino also includes an option (-c) to copy per-node activation state from another node to the booting node as it initialises. (See Start Rhino in the Getting Started Guide.)

Removing Per-Node Activation State

To remove per-node activation state, use the following rhino-console command or related MBean operation.

Console command: removepernodeactivationstate

Command

removepernodeactivationstate <from-node-id>
  Description
    Remove per-node activation state from a node

Example

To remove per-node activation state from node 103:

$ ./rhino-console removepernodeactivationstate 103
Per-node activation state removed from 103
Warning The specified node cannot be a current cluster member (unless the node is a quorum node, as quorum nodes do not make use of per-node activation state).

MBean operation: removePerNodeActivationState

MBean

Rhino operation

public boolean removePerNodeActivationState()
    throws UnsupportedOperationException, InvalidStateException,
           ManagementException;

This operation:

  • removes the per-node activation state recorded in the database for node for which this Node Housekeeping MBean was created (see Finding Housekeeping MBeans) to the given target node

  • returns the value true if it found and removed per-node activation state, or false if it found no per-node activation state to remove.

Note The start-rhino.sh command with the Production version of Rhino also includes an option (-d) to remove per-node activation state from the booting node as it initialises. (See Start Rhino in the Getting Started Guide.)

Startup and Shutdown Priority

Startup and shutdown priorities should be set when resource adaptors and services need to be activated or deactivated in a particular order when the SLEE is started or stopped. For example, the resource adaptors responsible for writing Call Detail Records often need to be deactivated last.

Valid priorities are between -128 and 127. Startup and shutdown occur from highest to lowest priority.

Console commands

Console command: getraentitystartingpriority

Command

getraentitystartingpriority <entity-name>
  Description
    Get the starting priority for a resource adaptor entity

Examples

./rhino-console getraentitystartingpriority sipra
Resource adaptor entity sipra activation priority is currently 0

Console command: getraentitystoppingpriority

Command

getraentitystoppingpriority <entity-name>
  Description
    Get the stopping priority for a resource adaptor entity

Examples

./rhino-console getraentitystoppingpriority sipra
Resource adaptor entity sipra deactivation priority is currently 0

Console command: getservicestartingpriority

Command

getservicestartingpriority <service-id>
  Description
    Get the starting priority for a service

Examples

./rhino-console getservicestartingpriority name=SIP\ Presence\ Service,vendor=OpenCloud,version=1.1
Service ServiceID[name=SIP Presence Service,vendor=OpenCloud,version=1.1] activation priority is currently 0

Console command: getservicestoppingpriority

Command

getservicestoppingpriority <service-id>
  Description
    Get the stopping priority for a service

Examples

./rhino-console getservicestoppingpriority name=SIP\ Presence\ Service,vendor=OpenCloud,version=1.1
Service ServiceID[name=SIP Presence Service,vendor=OpenCloud,version=1.1] deactivation priority is currently 0

Console command: setraentitystartingpriority

Command

setraentitystartingpriority <entity-name> <priority>
  Description
    Set the starting priority for a resource adaptor entity.  The priority must be
    between -128 and 127 and higher priority values have precedence over lower
    priority values

Examples

./rhino-console setraentitystartingpriority sipra 127
Resource adaptor entity sipra activation priority set to 127
./rhino-console setraentitystartingpriority sipra -128
Resource adaptor entity sipra activation priority set to -128

Console command: setraentitystoppingpriority

Command

setraentitystoppingpriority <entity-name> <priority>
  Description
    Set the stopping priority for a resource adaptor entity.  The priority must be
    between -128 and 127 and higher priority values have precedence over lower
    priority values

Examples

./rhino-console setraentitystoppingpriority sipra 127
Resource adaptor entity sipra deactivation priority set to 127
./rhino-console setraentitystoppingpriority sipra -128
Resource adaptor entity sipra deactivation priority set to -128

Console command: setservicestartingpriority

Command

setservicestartingpriority <service-id> <priority>
  Description
    Set the starting priority for a service.  The priority must be between -128 and
    127 and higher priority values have precedence over lower priority values

Examples

./rhino-console setservicestartingpriority name=SIP\ Presence\ Service,vendor=OpenCloud,version=1.1 127
Service ServiceID[name=SIP Presence Service,vendor=OpenCloud,version=1.1] activation priority set to 127
./rhino-console setservicestartingpriority name=SIP\ Presence\ Service,vendor=OpenCloud,version=1.1 -128
Service ServiceID[name=SIP Presence Service,vendor=OpenCloud,version=1.1] activation priority set to -128

Console command: setservicestoppingpriority

Command

setservicestoppingpriority <service-id> <priority>
  Description
    Set the stopping priority for a service.  The priority must be between -128 and
    127 and higher priority values have precedence over lower priority values

Examples

./rhino-console setservicestoppingpriority name=SIP\ Presence\ Service,vendor=OpenCloud,version=1.1 127
Service ServiceID[name=SIP Presence Service,vendor=OpenCloud,version=1.1] deactivation priority set to 127
./rhino-console setservicestoppingpriority name=SIP\ Presence\ Service,vendor=OpenCloud,version=1.1 -128
Service ServiceID[name=SIP Presence Service,vendor=OpenCloud,version=1.1] deactivation priority set to -128

MBean operations

Services

MBean

Rhino extensions

getStartingPriority
byte getStartingPriority(ServiceID service)
    throws NullPointerException, UnrecognizedServiceException, ManagementException;
getStartingPriorities
Byte[] getStartingPriorities(ServiceID[] services)
    throws NullPointerException, ManagementException;
getStoppingPriority
byte getStoppingPriority(ServiceID service)
   throws NullPointerException, UnrecognizedServiceException, ManagementException;
getStoppingPriorities
Byte[] getStoppingPriorities(ServiceID[] services)
    throws NullPointerException, ManagementException;
setStartingPriority
void setStartingPriority(ServiceID service, byte priority)
    throws NullPointerException, UnrecognizedServiceException, ManagementException;
setStoppingPriority
void setStoppingPriority(ServiceID service, byte priority)
    throws NullPointerException, UnrecognizedServiceException, ManagementException;

Resource Adaptors

MBean

Rhino extensions

getStartingPriority
byte getStartingPriority(String entityName)
    throws NullPointerException, UnrecognizedResourceAdaptorEntityException, ManagementException;
getStartingPriorities
Byte[] getStartingPriorities(String[] entityNames)
    throws NullPointerException, ManagementException;
getStoppingPriority
byte getStoppingPriority(String entityName)
   throws NullPointerException, UnrecognizedResourceAdaptorEntityException, ManagementException;
getStoppingPriorities
Byte[] getStoppingPriorities(String[] entityNames)
    throws NullPointerException, ManagementException;
setStartingPriority
void setStartingPriority(String entityName, byte priority)
    throws NullPointerException, UnrecognizedResourceAdaptorEntityException, ManagementException;
setStoppingPriority
void setStoppingPriority(String entityName, byte priority)
    throws NullPointerException, UnrecognizedResourceAdaptorEntityException, ManagementException;

Deployable Units

As well as an overview of deployable units, this section includes instructions for performing the following Rhino SLEE procedures with explanations, examples and links to related javadocs:

Procedure rhino-console command(s) MBean → Operation
install
installlocaldu
DeploymentMBean → install
uninstall
DeploymentMBean → uninstall
listdeployableunits
DeploymentMBean → getDeployableUnits

About Deployable Units

Below are a definition, preconditions for installing and uninstalling, and an example of a deployable unit.

What is a deployable unit?

A deployable unit is a jar file that can be installed in the SLEE. It contains:

  • a deployment descriptor

  • constituent jar files, with Java class files and deployment descriptors for components such as:

    • SBBs

    • events

    • profile specifications

    • resource adaptor types

    • resource adaptors

    • libraries

  • XML files for services.

Note The JAIN SLEE 1.1 specification defines the structure of a deployable unit.

Installing and uninstalling deployable units

You must install and uninstall deployable units in a particular order, according to the dependencies of the SLEE components they contain. You cannot install a deployable unit unless either it contains all of its dependencies, or they are already installed. For example, if your deployable unit contains an SBB which depends on a library jar, the library jar must either already be installed in the SLEE, or be included in that same deployable unit jar.

Pre-conditions

A deployable unit cannot be installed if any of the following is true:

  • A deployable unit with the same URL has already been installed in the SLEE.

  • The deployable unit contains a component with the same name, vendor and version as a component of the same type that is already installed in the SLEE.

  • The deployable unit contains a component that references other components that are not yet installed in the SLEE and are not included in the deployable unit jar. (For example, an SBB component may reference event-type components and profile-specification components that are not included or pre-installed.)

A deployable unit cannot be uninstalled if either of the following is true:

  • There are any dependencies on any of its components from components in other installed deployable units. For example, if a deployable unit contains an SBB jar that depends on a profile-specification jar contained in a second deployable unit, the deployable unit containing the profile-specification jar cannot be uninstalled while the deployable unit containing the SBB jar remains installed.

  • There are "instances" of components contained in the deployable unit. For example, a deployable unit containing a resource adaptor cannot be uninstalled if the SLEE includes resource adaptor entities of that resource adaptor.

Deployable unit example

The following example illustrates the deployment descriptor for a deployable unit jar file:

<deployable-unit>
<description> ... </description>
...
<jar> SomeProfileSpec.jar </jar>
<jar> BarAddressProfileSpec.jar </jar>
<jar> SomeCustomEvent.jar </jar>
<jar> FooSBB.jar </jar>
<jar> BarSBB.jar </jar>
...
<service-xml> FooService.xml </service-xml>
...
</deployable-unit>

The content of the deployable unit jar file is as follows:

META-INF/deployable-unit.xml
META-INF/MANIFEST.MF
...
SomeProfileSpec.jar
BarAddressProfileSpec.jar
SomeCustomEvent.jar
FooSBB.jar
BarSBB.jar
FooService.xml
...

Installing Deployable Units

To install a deployable unit, use the following rhino-console command or related MBean operation.

Console commands: install, installlocaldu

Commands

Installing from a URL
install <url> [-type <type>] [-installlevel <level>]
  Description
    Install a deployable unit jar or other artifact.  To install something other
    than a deployable unit, the -type option must be specified.  The -installlevel
    option controls to what degree the deployable artifact is installed
Installing from a local file
installlocaldu <file url> [-type <type>] [-installlevel <level>] [-url url]
  Description
    Install a deployable unit or other artifact. This command will attempt to
    forward the file content (by reading the file) to rhino if the management client
    is on a different host.  To install something other than a deployable unit, the
    -type option must be specified.  The -installlevel option controls to what
    degree the deployable artifact is installed.  The -url option allows the
    deployment unit to be installed with an alternative URL identifier

Examples

To install a deployable unit from a given URL:

$ ./rhino-console install file:/home/rhino/rhino/examples/sip-examples-2.0/lib/jsip-library-du-1.2.jar
installed: DeployableUnitID[url=file:/home/rhino/rhino/examples/sip-examples-2.0/lib/jsip-library-du-1.2.jar]

To install a deployable unit from the local file system of the management client:

$ ./rhino-console installlocaldu file:/home/rhino/rhino/examples/sip-examples-2.0/lib/jsip-library-du-1.2.jar
installed: DeployableUnitID[url=file:/home/rhino/rhino/examples/sip-examples-2.0/lib/jsip-library-du-1.2.jar]

MBean operation: install

MBean

SLEE-defined

Install a deployable unit from a given URL
public DeployableUnitID install(String url)
  throws NullPointerException, MalformedURLException,
    AlreadyDeployedException, DeploymentException,
      ManagementException;

Installs the given deployable unit jar file into the SLEE. The given URL must be resolvable from the Rhino node.

Rhino extension

Install a deployable unit from a given byte array
public DeployableUnitID install(String url, byte[] content)
  throws NullPointerException, MalformedURLException,
      AlreadyDeployedException, DeploymentException,
          ManagementException;

Installs the given deployable unit jar file into the SLEE. The caller passes the actual file contents of the deployable unit in a byte array as a parameter to this method. The SLEE then installs the deployable unit as if it were from the URL.

Uninstalling Deployable Units

To uninstall a deployable unit, use the following rhino-console command or related MBean operation.

Warning A deployable unit cannot be uninstalled if it contains any components that any other deployable unit installed in the SLEE depends on.

Console command: uninstall

Command

uninstall <url>
  Description
    Uninstall a deployable unit jar

Examples

To uninstall a deployable unit which was installed with the given URL:

$ ./rhino-console uninstall file:/home/rhino/rhino/examples/sip-examples-2.0/lib/jsip-library-du-1.2.jar
uninstalled: DeployableUnitID[url=file:/home/rhino/rhino/examples/sip-examples-2.0/lib/jsip-library-du-1.2.jar]

Console command: cascadeuninstall

Command

cascadeuninstall <type> <url|component-id> [-force] [-s]
  Description
    Cascade uninstall a deployable unit or copied component. The optional -force
    argument prevents the command from prompting for confirmation before the
    uninstall occurs. The -s argument removes the shadow from a shadowed component
    and is not valid for deployable units

Examples

To uninstall a deployable unit which was installed with the given URL and all deployable units that depend on this:

  $ ./rhino-console cascadeuninstall du file:du/ocsip-ra-2.3.1.17.du.jar
Cascade removal of deployable unit file:du/ocsip-ra-2.3.1.17.du.jar requires the following operations to be performed:
  Deployable unit file:jars/sip-registrar-service.jar will be uninstalled
    SBB with SbbID[name=RegistrarSbb,vendor=OpenCloud,version=1.8] will be uninstalled
    Service with ServiceID[name=SIP Registrar Service,vendor=OpenCloud,version=1.8] will be uninstalled
      This service will first be deactivated
  Deployable unit file:jars/sip-presence-service.jar will be uninstalled
    SBB with SbbID[name=EventStateCompositorSbb,vendor=OpenCloud,version=1.0] will be uninstalled
    SBB with SbbID[name=NotifySbb,vendor=OpenCloud,version=1.1] will be uninstalled
    SBB with SbbID[name=PublishSbb,vendor=OpenCloud,version=1.0] will be uninstalled
    Service with ServiceID[name=SIP Notification Service,vendor=OpenCloud,version=1.1] will be uninstalled
      This service will first be deactivated
    Service with ServiceID[name=SIP Presence Service,vendor=OpenCloud,version=1.1] will be uninstalled
      This service will first be deactivated
    Service with ServiceID[name=SIP Publish Service,vendor=OpenCloud,version=1.0] will be uninstalled
      This service will first be deactivated
  Deployable unit file:jars/sip-proxy-service.jar will be uninstalled
    SBB with SbbID[name=ProxySbb,vendor=OpenCloud,version=1.8] will be uninstalled
    Service with ServiceID[name=SIP Proxy Service,vendor=OpenCloud,version=1.8] will be uninstalled
      This service will first be deactivated
  Deployable unit file:du/ocsip-ra-2.3.1.17.du.jar will be uninstalled
    Resource adaptor with ResourceAdaptorID[name=OCSIP,vendor=OpenCloud,version=2.3.1] will be uninstalled
      Resource adaptor entity sipra will be removed
        This resource adaptor entity will first be deactivated
        Link name OCSIP bound to this resource adaptor entity will be removed

Continue? (y/n): y
Deactivating service ServiceID[name=SIP Registrar Service,vendor=OpenCloud,version=1.8]
Deactivating service ServiceID[name=SIP Notification Service,vendor=OpenCloud,version=1.1]
Deactivating service ServiceID[name=SIP Presence Service,vendor=OpenCloud,version=1.1]
Deactivating service ServiceID[name=SIP Publish Service,vendor=OpenCloud,version=1.0]
Deactivating service ServiceID[name=SIP Proxy Service,vendor=OpenCloud,version=1.8]
All necessary services are inactive
Deactivating resource adaptor entity sipra
All necessary resource adaptor entities are inactive
Uninstalling deployable unit file:jars/sip-registrar-service.jar
Uninstalling deployable unit file:jars/sip-presence-service.jar
Uninstalling deployable unit file:jars/sip-proxy-service.jar
Unbinding resource adaptor entity link name OCSIP
Removing resource adaptor entity sipra
Uninstalling deployable unit file:du/ocsip-ra-2.3.1.17.du.jar

Utility: cascade-uninstall

cascade-uninstall

Uninstalls a deployable unit along with everything that depends on it

MBean operation: uninstall

MBean

SLEE-defined

public void uninstall(DeployableUnitID id)
  throws NullPointerException, UnrecognizedDeployableUnitException,
         DependencyException, InvalidStateException, ManagementException;

Uninstalls the given deployable unit jar file (along with all the components it contains) out of the SLEE.

Listing Deployable Units

To list the installed deployable units, use the following rhino-console command or related MBean operation.

Console command: listdeployableunits

Command

listdeployableunits
  Description
    List the current installed deployable units

Example

To list the currently installed deployable units:

$ ./rhino-console listdeployableunits
DeployableUnitID[url=file:/home/rhino/rhino/examples/sip-examples-2.0/lib/jsip-library-du-1.2.jar]
DeployableUnitID[url=file:/home/rhino/rhino/lib/javax-slee-standard-types.jar]

MBean operation: getDeployableUnits

MBean

SLEE-defined

  public DeployableUnitID[] getDeployableUnits()
    throws ManagementException;

Returns the set of deployable unit identifiers that identify all the deployable units installed in the SLEE.

Services

As well as an overview of SLEE services, this section includes instructions for performing the following Rhino SLEE procedures with explanations, examples and links to related javadocs:

Procedure rhino-console command(s) MBean → Operation(s)
listservices
Deployment → getServices
listservicesbystate
Service Management → getServices
activateservice
Service Management → activate
deactivateservice
Service Management → deactivate
deactivateandactivateservice
Service Management → deactivateAndActivate
listserviceralinks
Deployment → getServices
listsbbs
Deployment → getSbbs

         
Deployment → getDescriptors
getservicemetricsrecordingenabled
ServiceManagementMBean → getServiceMetricsRecordingEnabled
setservicemetricsrecordingenabled
ServiceManagementMBean → setServiceMetricsRecordingEnabled
getservicereplicationselectors
ServiceManagementMBean → getReplicationSelectors
setservicereplicationselectors
ServiceManagementMBean → setReplicationSelectors

About Services

The SLEE specification presents the operational lifecycle of a SLEE service — illustrated, defined and summarised below.

Note
What are SLEE services?

Services are SLEE components that provide the application logic to act on input from resource adaptors.

Service lifecycle

Service lifecycle

Service lifecycle states

State Definition
INACTIVE

The service has been installed successfully and is ready to be activated, but not yet running. The SLEE will not create SBB entities of the service’s root SBB, to process events.

ACTIVE

The service is running. The SLEE will create SBB entities, of the service’s root SBB, to process initial events. The SLEE will also deliver events to SBB entities of the service’s SBBs, as appropriate.

STOPPING

The service is deactivating. Existing SBB entities of the service continue running and may complete their processing. But the SLEE will not create new SBB entities of the service’s root SBB, for new activities.

Note When the SLEE can reclaim all of a service’s SBB entities, it transitions out of the STOPPING state and returns to the INACTIVE state.

Independent operational states

As explained in About SLEE Operational States, each event-router node in a Rhino cluster maintains its own lifecycle state machine, independent of other nodes in the cluster. This is also true for each service: one service might be INACTIVE on one node in a cluster, ACTIVE on another, and STOPPING on a third. The operational state of a service on each cluster node also persists to the disk-based database.

A service will enter the INACTIVE state, after node bootup and initialisation completes, if the database’s persistent operational state information for that service is missing, or is set to INACTIVE or STOPPING.

And, like node operational states, you can change the operational state of a service at any time, as long as least one node in the cluster is available to perform the management operation (regardless of whether or not the node whose operational state being changed is a current cluster member). For example, you might activate a service on node 103 before node 103 is booted — then, when node 103 boots, and after it completes initialisation, that service will transition to the ACTIVE state.

Configuring services

An administrator can configure a service before deployment by modifying its service-jar.xml deployment descriptor (in its deployable unit). This includes specifying:

  • the address profile table to use when a subscribed address selects initial events for the service’s root SBB

  • the default event-router priority for the SLEE to give to root SBB entities of the service when processing initial events.

Individual SBBs used in a service can also have configurable properties or environment entries. Values for these environment entries are defined in the sbb-jar.xml deployment descriptor included in the SBB’s component jar. Administrators can set or adjust the values for each environment entry before the SBB is installed in the SLEE.

The SLEE only reads the configurable properties defined for a service or SBB deployment descriptor at deployment time. If you need to change the value of any of these properties, you’ll need to:

  • uninstall the related component (service or SBB whose properties you want to configure) from the SLEE

  • change the properties

  • reinstall the component

  • uninstall and reinstall other components (as needed) to satisfy dependency requirements enforced by the SLEE.

Listing Services

All Available Services

To list all available services installed in the SLEE, use the following rhino-console command or related MBean operation.

Console command: listservices

Command

listservices
  Description
    List the current installed services

Example

$ ./rhino-console listservices
ServiceID[name=SIP AC Location Service,vendor=OpenCloud,version=1.7]
ServiceID[name=SIP Proxy Service,vendor=OpenCloud,version=1.8]
ServiceID[name=SIP Registrar Service,vendor=OpenCloud,version=1.8]

MBean operation: getServices

MBean

SLEE-defined

public ServiceID[] getServices()
  throws ManagementException;

This operation returns an array of service component identifiers, identifying the services installed in the SLEE.

Tip See also Services by State.

Services by State

To list a specified activation state, use the following rhino-console command or related MBean operation.

Console command: listservicesbystate

Command

listservicesbystate <state> [-node node]
  Description
    List the services that are in the specified state (on the specified node)

Output

The activation state of a service is node-specific. If the -node argument is not provided, this command returns the services in the given activation state on the node that rhino-console is connected to for management. (Otherwise, the command returns the services in the given activation state on the specified node.)

Example

To list the services in the ACTIVE state on node 102:

$ ./rhino-console listservicesbystate Active -node 102
Services in Active state on node 102:
  ServiceID[name=SIP Proxy Service,vendor=OpenCloud,version=1.8]
  ServiceID[name=SIP Registrar Service,vendor=OpenCloud,version=1.8]

MBean operation: getServices

MBean

SLEE-defined

Get services on all nodes
public ServiceID[] getServices(ServiceState state)
  throws NullPointerException, ManagementException;

Rhino’s implementation of the SLEE-defined getServices operation returns an array identifying all the services in the requested state on the node where you invoke the operation.

Rhino extension

Get services on specific nodes
public ServiceID[] getServices(ServiceState state, int nodeID)
  throws NullPointerException, InvalidArgumentException,
    ManagementException;

Rhino provides an extension that adds an argument that lets you control the nodes on which to list services in a particular state (by specifying node IDs).

Activating and Deactivating Services

Activating Services

To activate one or more services, use the following rhino-console command or related MBean operation.

Console command: activateservice

Command

activateservice <service-id>* [-nodes node1,node2,...] [-ifneeded]
  Description
    Activate a service (on the specified nodes)

Example

To activate the Call Barring and Call Forwarding services on nodes 101 and 102:

$ ./rhino-console activateservice \
  "name=Call Barring Service,vendor=OpenCloud,version=0.2" \
  "name=Call Forwarding Service,vendor=OpenCloud,version=0.2" \
  -nodes 101,102
Activating services [ServiceID[name=Call Barring Service,vendor=OpenCloud,version=0.2],
  ServiceID[name=Call Forwarding Service,vendor=OpenCloud,version=0.2]] on node(s) [101,102]
Services transitioned to the Active state on node 101
Services transitioned to the Active state on node 102

MBean operation: activate

MBean

SLEE-defined

Activate on all nodes
public void activate(ServiceID id)
    throws NullPointerException, UnrecognizedServiceException,
        InvalidStateException, InvalidLinkNameBindingStateException,
        ManagementException;

public void activate(ServiceID[] ids)
    throws NullPointerException, InvalidArgumentException,
        UnrecognizedServiceException, InvalidStateException,
        InvalidLinkNameBindingStateException, ManagementException;

Rhino’s implementation of the SLEE-defined activate operation will attempt to activate particular services on all current event-router nodes in the primary component. For this to work, the specified services must be in the INACTIVE state on those nodes.

Rhino extension

Activate on specific nodes
public void activate(ServiceID id, int[] nodeIDs)
    throws NullPointerException, InvalidArgumentException,
        UnrecognizedServiceException, InvalidStateException,
        ManagementException;

public void activate(ServiceID[] ids, int[] nodeIDs)
    throws NullPointerException, InvalidArgumentException,
        UnrecognizedServiceException, InvalidStateException,
        ManagementException;

Rhino provides an extension that adds a argument to let you control the nodes on which to activate the specified services (by specifying node IDs). For this to work, the specified services must be in the INACTIVE state on the specified nodes.

Warning A service may require resource adaptor entity link names to be bound to appropriate resource adaptor entities before it can be activated. (See Getting Link Bindings Required by a Service and Managing Resource Adaptor Entity Link Bindings.)

Deactivating Services

To deactivate one or more services on one or more nodes, use the following rhino-console command or related MBean operation.

Console command: deactivateservice

Command

deactivateservice <service-id>* [-nodes node1,node2,...] [-ifneeded]
  Description
    Deactivate a service (on the specified nodes)

Example

To deactivate the Call Barring and Call Forwarding services on nodes 101 and 102:

$ ./rhino-console deactivateservice \
    "name=Call Barring Service,vendor=OpenCloud,version=0.2" \
    "name=Call Forwarding Service,vendor=OpenCloud,version=0.2" \
    -nodes 101,102
Deactivating services [ServiceID[name=Call Barring Service,vendor=OpenCloud,version=0.2],
  ServiceID[name=Call Forwarding Service,vendor=OpenCloud,version=0.2]] on node(s) [101,102]
Services transitioned to the Stopping state on node 101
Services transitioned to the Stopping state on node 102

MBean operation: deactivate

MBean

SLEE-defined

Deactivate on all nodes
public void deactivate(ServiceID id)
    throws NullPointerException, UnrecognizedServiceException,
          InvalidStateException, ManagementException;

public void deactivate(ServiceID[] ids)
    throws NullPointerException, InvalidArgumentException,
          UnrecognizedServiceException, InvalidStateException,
          ManagementException;

Rhino’s implementation of the SLEE-defined deactivate operation attempts to deactivate particular services on all current event-router nodes in the primary component. For this to work, the specified services must be in the ACTIVE state on those nodes.

Rhino extension

Deactivate on specific nodes
public void deactivate(ServiceID id, int[] nodeIDs)
    throws NullPointerException, InvalidArgumentException,
        UnrecognizedServiceException, InvalidStateException,
        ManagementException;

public void deactivate(ServiceID[] ids, int[] nodeIDs)
    throws NullPointerException, InvalidArgumentException,
        UnrecognizedServiceException, InvalidStateException,
        ManagementException;

Rhino provides an extension that adds an argument that lets you control the nodes on which to deactivate the specified services (by specifying node IDs). For this to work, the specified services must be in the ACTIVE state on the specified nodes.

Console command: waittilserviceisinactive

Command

waittilserviceisinactive <service-id> [-timeout timeout] [-nodes node1,node2,...]
    Wait for a service to finish deactivating (on the specified nodes) (timing out after N seconds)

Example

To wait for the Call Barring and Call Forwarding services on nodes 101 and 102:

$ ./rhino-console waittilserviceisinactive \
    "name=Call Barring Service,vendor=OpenCloud,version=0.2" \
    "name=Call Forwarding Service,vendor=OpenCloud,version=0.2" \
    -nodes 101,102
Service ServiceID[name=Call Barring Service,vendor=OpenCloud,version=0.2] is in the Inactive state on node(s) [101,102]
Service ServiceID[Call Forwarding Service,vendor=OpenCloud,version=0.2] is in the Inactive state on node(s) [101,102]

Upgrading (Activating & Deactivating) Services

To activate some services and deactivate others, use the following rhino-console command or related MBean operation.

Tip
Activating and deactivating in one operation

The SLEE specification defines the ability to deactivate some services and activate other services in a single operation. As one set of services deactivates, the existing activities being processed by those services continue to completion, while new activities (started after the operation is invoked) are processed by the activated services. The intended use of this is to upgrade a service or services with new versions (however the operation does not have to be used strictly for this purpose).

Console command: deactivateandactivateservice

Command

deactivateandactivateservice Deactivate <service-id>* Activate <service-id>*
[-nodes node1,node2,...]
  Description
    Deactivate some services and Activate some other services (on the specified
    nodes)

Example

To deactivate version 0.2 of the Call Barring and Call Forwarding services and activate version 0.3 of the same services on nodes 101 and 102:

$ ./rhino-console deactivateandactivateservice \
    Deactivate "name=Call Barring Service,vendor=OpenCloud,version=0.2" \
               "name=Call Forwarding Service,vendor=OpenCloud,version=0.2" \
    Activate   "name=Call Barring Service,vendor=OpenCloud,version=0.3" \
               "name=Call Forwarding Service,vendor=OpenCloud,version=0.3" \
    -nodes 101,102
On node(s) [101,102]:
    Deactivating service(s) [ServiceID[name=Call Barring Service,vendor=OpenCloud,version=0.2],
      ServiceID[name=Call Forwarding Service,vendor=OpenCloud,version=0.2]]
    Activating service(s) [ServiceID[name=Call Barring Service,vendor=OpenCloud,version=0.3],
      ServiceID[name=Call Forwarding Service,vendor=OpenCloud,version=0.3]]
Deactivating service(s) transitioned to the Stopping state on node 101
Activating service(s) transitioned to the Active state on node 101
Deactivating service(s) transitioned to the Stopping state on node 102
Activating service(s) transitioned to the Active state on node 102

MBean operation: deactivateAndActivate

MBean

SLEE-defined

Deactivate and activate on all nodes
public void deactivateAndActivate(ServiceID deactivateID, ServiceID activateID)
    throws NullPointerException, InvalidArgumentException,
           UnrecognizedServiceException, InvalidStateException,
           InvalidLinkNameBindingStateException, ManagementException;

public void deactivateAndActivate(ServiceID[] deactivateIDs, ServiceID[] activateIDs)
    throws NullPointerException, InvalidArgumentException,
           UnrecognizedServiceException, InvalidStateException,
           InvalidLinkNameBindingStateException, ManagementException;

Rhino’s implementation of the SLEE-defined deactivateAndActivate operation attempts to deactivate specified services and activate others on all current event-router nodes in the primary component. For this to work, the services to deactivate must be in the ACTIVE state, and the services to activate must be in the INACTIVE state, on those nodes.

Rhino extension

Deactivate and activate on specific nodes
public void deactivateAndActivate(ServiceID deactivateID, ServiceID activateID, int[] nodeIDs)
    throws NullPointerException, InvalidArgumentException,
           UnrecognizedServiceException, InvalidStateException,
           ManagementException;

public void deactivateAndActivate(ServiceID[] deactivateIDs, ServiceID[] activateIDs, int[] nodeIDs)
    throws NullPointerException, InvalidArgumentException,
           UnrecognizedServiceException, InvalidStateException,
           ManagementException;

Rhino provides an extension that adds an argument that lets you control the nodes on which to activate and deactivate services (by specifying node IDs). For this to work, the services to deactivate must be in the ACTIVE state, and the services to activate must be in the INACTIVE state, on the specified nodes.

To find the resource adaptor entity link name bindings needed for a service, and list the service’s SBBs, use the following rhino-console commands or related MBean operations.

Command

listserviceralinks service-id
  Description
    List resource adaptor entity links required by a service

Example

To list the resource adaptor entity links that the JCC VPN service needs:

$ ./rhino-console listserviceralinks "name=JCC 1.1 VPN,vendor=Open Cloud,version=1.0"
In service ServiceID[name=JCC 1.1 VPN,vendor=Open Cloud,version=1.0]:
    SBB SbbID[name=AnytimeInterrogation sbb,vendor=Open Cloud,version=1.0] requires entity link bindings: slee/resources/map
    SBB SbbID[name=JCC 1.1 VPN sbb,vendor=Open Cloud,version=1.0] requires entity link bindings: slee/resources/cdr

Command

listsbbs [service-id]
  Description
    List the current installed SBBs.  If a service identifier is specified only the
    SBBs in the given service are listed

Example

To list the SBBs in the JCC VPN service:

$ ./rhino-console listsbbs "name=JCC 1.1 VPN,vendor=Open Cloud,version=1.0"
SbbID[name=AnytimeInterrogation sbb,vendor=Open Cloud,version=1.0]
SbbID[name=JCC 1.1 VPN sbb,vendor=Open Cloud,version=1.0]
SbbID[name=Proxy route sbb,vendor=Open Cloud,version=1.0]

MBean

SLEE-defined

Get all services in the SLEE
public ServiceID[] getServices()
    throws ManagementException;

getServices returns an array containing the component identifiers of all services installed in the SLEE.


Get all SBBs in a service
public SbbID[] getSbbs(ServiceID service)
    throws NullPointerException, UnrecognizedServiceException,
        ManagementException;

getSbbs returns an array containing the component identifiers of all SBBs included in the given service.


Get the component descriptor for a component
public ComponentDescriptor[] getDescriptors(ComponentID[] ids)
    throws NullPointerException, ManagementException;

getDescriptors returns the component descriptor for each given component.

Tip

To find the entity link names for an individual SBB, you can:

  • cast a ComponentDescriptor object for the SBB to an SbbDescriptor

  • retrieve an array of entity link names required by the SBB (from the SbbDescriptor), using the getResourceAdaptorEntityLinks operation. The array will be zero-length if the SBB does not require any entity link bindings.

Configuring service metrics recording status

To check and configure the status for recording service metrics, use the following rhino-console commands or related MBean operations.

The details for metrics stats are listed in Metrics.Services.cmp and Metrics.Services.lifecycle.

Note The default is set to disabled for performance consideration.

Console commands

getservicemetricsrecordingenabled

Command

getservicemetricsrecordingenabled <service-id>
  Description
    Determine if metrics recording for a service has been enabled

Example

To check the status for recording metrics:

$ ./rhino-console getservicemetricsrecordingenabled name=service1,vendor=OpenCloud,version=1.0
Metrics recording for ServiceID[name=service1,vendor=OpenCloud,version=1.0] is currently disabled

setservicemetricsrecordingenabled

Command

setservicemetricsrecordingenabled <service-id> <true|false>
  Description
    Enable or disable the recording of metrics for a service

Example

To enable the recording metrics:

$ ./rhino-console setservicemetricsrecordingenabled name=service1,vendor=OpenCloud,version=1.0 true
Metrics recording for ServiceID[name=service1,vendor=OpenCloud,version=1.0] has been enabled

MBean operations: getServiceMetricsRecordingEnabled and setServiceMetricsRecordingEnabled

MBean

Rhino extension

Determine if the recording of metrics for a service is currently enabled or disabled.
public boolean getServiceMetricsRecordingEnabled(ServiceID service)
    throws NullPointerException, UnrecognizedServiceException, ManagementException;
Enable or disable the recording of metrics for a service.
public void setServiceMetricsRecordingEnabled(ServiceID service, boolean enabled)
    throws NullPointerException, UnrecognizedServiceException, ManagementException;

Configuring service replication

The default replication behaviour of a service is defined by the service in its deployment descriptor, but may be overridden by an administrator after the service has been installed into the SLEE.

Default replication behaviour

Default replication behaviour is specified by a service in its oc-service.xml extension service deployment descriptor. The service can specify the conditions under which the application state of the service will be replicated by using the following replication selectors:

  • Savanna — Service replication will occur if the namespace the service is installed in replicates application state over the traditional savanna framework.

  • KeyValueStore — Service replication will occur if the namespace the service is installed in utilises a key/value store to persist application state.

  • Always — The service will always be replicated regardless of any underlying replication mechanism.

Zero or more replication selectors can be specified by the service. If any condition for replication is matched at deployment time then the service application state will be replicated. If not, no replication will take place for that service.

Configuring replication behaviour

The default replication selectors specified by a service can be changed by an administrator after the service is installed, but before it is deployed, using the following rhino-console commands or related MBean operations.

Console commands

getservicereplicationselectors

Command

getservicereplicationselectors <service-id>
  Description
    Get the replication selectors for a service

Example

To check the current replication selectors for a service:

$ ./rhino-console getservicereplicationselectors name=service1,vendor=OpenCloud,version=1.0
Service ServiceID[name=service1,vendor=OpenCloud,version=1.0] current replication selectors are: [KEYVALUESTORE]
setservicereplicationselectors

Command

setservicereplicationselectors <service-id> -none|selector*
  Description
    Set the replication selectors for a service, valid selectors are: [ALWAYS,
    SAVANNA, KEYVALUESTORE]

Example

The change the replication selectors for a service:

$ ./rhino-console setservicereplicationselectors name=service1,vendor=OpenCloud,version=1.0 SAVANNA KEYVALUESTORE
Service ServiceID[name=service1,vendor=OpenCloud,version=1.0] replication selectors set to [SAVANNA, KEYVALUESTORE]

MBean operations: getReplicationSelectors and setReplicationSelectors

MBean

Rhino extension

Get the current replication selectors for a service.
public ReplicationSelector[] getReplicationSelectors(ServiceID id)
    throws NullPointerException, UnrecognizedServiceException, ManagementException;
Set the replication selectors for a service.
    public void setReplicationSelectors(ServiceID id, ReplicationSelector[] selectors)
        throws NullPointerException, UnrecognizedServiceException, InvalidStateException, ManagementException;

Resource Adaptor Entities

As well as an overview of resource adaptor entities, this section includes instructions for performing the following Rhino SLEE procedures with explanations, examples and links to related javadocs:

Procedure rhino-console command MBean → Operation
listraconfigproperties
Resource Management → getConfigurationProperties
createraentity
Resource Management → createResourceAdaptorEntity
removeraentity
Resource Management → removeResourceAdaptorEntity
listraentityconfigproperties
Resource Management → getConfigurationProperties
updateraentityconfigproperties
Resource Management → updateConfigurationProperties
activateraentity
Resource Management → activateResourceAdaptorEntity
deactivateraentity
Resource Management → deactivateResourceAdaptorEntity
reassignactivities
Resource Management → reassignActivities
getraentitystate
Resource Management → getState
listraentitiesbystate
Resource Management → getResourceAdaptorEntities
bindralinkname
Resource Management → bindLinkName
unbindralinkname
Resource Management → unbindLinkName
listralinknames
Resource Management → getLinkNames

About Resource Adaptor Entities

Resource adaptors (RAs) are SLEE components which let particular network protocols or APIs be used in the SLEE.

They typically include a set of configurable properties (such as address information of network endpoints, URLs to external systems, or internal timer-timeout values). These properties may include default values. A resource adaptor entity is a particular configured instance of a resource adaptor, with defined values for all of that RA’s configuration properties.

The resource adaptor entity lifecycle

The SLEE specification presents the operational lifecycle of a resource adaptor entity — illustrated, defined, and summarised below.

RA lifecycle

Resource adaptor entity lifecycle states

The SLEE lifecycle states are:

State Definition
INACTIVE

The resource adaptor entity has been configured and initialised. It is ready to be activated, but may not yet create activities or fire events to the SLEE. Typically, it is not connected to network resources.

ACTIVE

The resource adaptor entity is connected to the resources it needs to function (assuming they are available), and may create activities and fire events to the SLEE.

STOPPING

The resource adaptor entity may not create new activities in the SLEE, but may fire events to the SLEE on already existing activities. A resource adaptor entity transitions out of the STOPPING state, returning to the INACTIVE state, when all activities it owns have either ended or been assigned to another node for continued processing.

Note
Creating activities in the STOPPING state

By default, Rhino 2.7 prevents a resource adaptor from creating an activity in the STOPPING state.

This behaviour is controlled by the rhino.skip_lifecycle_checks system property, which defaults to false.

When set to true, Rhino does not enforce this restriction. Resource adaptors should check the state before creating an activity, to avoid a situation where a resource adaptor entity never deactivates because new activities are being created.

The default value in earlier versions of Rhino was true.

Independent lifecycle state machines

As explained in About SLEE Operational States, each event-router node in a Rhino cluster maintains its own lifecycle state machine, independent of other nodes in the cluster. This is also true for each resource adaptor entity: one resource adaptor entity might be INACTIVE on one node in a cluster, ACTIVE on another, and STOPPING on a third. The operational state of a resource adaptor entity on each cluster node also persists to the disk-based database.

A resource adaptor entity will enter the INACTIVE state, after node bootup and initialisation completes, if the database’s persistent operational state information for that resource adaptor entity is missing, or is set to INACTIVE or STOPPING.

And, like node operational states, you can change the operational state of a resource adaptor entity at any time, as long as least one node in the cluster is available to perform the management operation (regardless of whether or not the node whose operational state being changed is a current cluster member). For example, you might activate a resource adaptor entity on node 103 before node 103 is booted — then, when node 103 boots, and after it completes initialisation, that resource adaptor entity will transition to the ACTIVE state.

Creating and Removing Resource Adaptor Entities

Finding RA Configuration Properties

To determine resource adaptor configuration properties (which you need to know when Creating a Resource Adaptor Entity) use the following rhino-console command or related MBean operation.

Console command: listraconfigproperties

Command

listraconfigproperties <resource-adaptor-id>
  Description
    List the configuration properties (and any default values) for a resource
    adaptor

Example

To list the configuration properties of the OpenCloud SIP Resource Adaptor:

$ ./rhino-console listraconfigproperties name=OCSIP,vendor=OpenCloud,version=2.1
Configuration properties for resource adaptor name=OCSIP,vendor=OpenCloud,version=2.1:
  Automatic100TryingSupport (java.lang.Boolean): true
  CRLLoadFailureRetryTimeout (java.lang.Integer): 900
  CRLNoCRLLoadFailureRetryTimeout (java.lang.Integer): 60
  CRLRefreshTimeout (java.lang.Integer): 86400
  CRLURL (java.lang.String):
  ...

MBean operation: getConfigurationProperties

MBean

SLEE-defined

public ConfigProperties getConfigurationProperties(ResourceAdaptorID id)
    throws NullPointerException, UnrecognizedResourceAdaptorException,
        ManagementException

Output

This operation returns a ConfigProperties object. A ConfigProperties object contains a set of ConfigProperty.Property objects, each of which identifies one configuration property defined by the RA. If the RA has defined a default value for the configuration property, the ConfigProperty.Property object will include it.

Creating a Resource Adaptor Entity

To create a resource adaptor entity use the following rhino-console command or related MBean operation.

Console command: createrantity

Command

createraentity <resource-adaptor-id> <entity-name>
[<config-params>|(<property-name> <property-value)*]
  Description
    Create a resource adaptor entity with the given name.  Optionally configuration
    properties can be specified, either as a single comma-separated string of
    name=value pairs, or as a series of separate name and value argument pairs

Example

To create an instance of the OpenCloud SIP resource adaptor, called sipra, with the following configuration property values replacing the defaults (if any) for the IPAddress (192.168.0.100), Port (5160) and SecurePort (5161) :

$ ./rhino-console createraentity name=OCSIP,vendor=OpenCloud,version=2.1 sipra \
    IPAddress=192.168.0.100,Port=5160,SecurePort=5161
Created resource adaptor entity sipra

Notes

Entering configuration properties

When creating a resource adaptor entity, determine its configuration properties and then enter them in rhino-console as a comma-separated list of property-name=value pairs.


Warning
White space, commas, quotes

If a configuration-property value contains white space or a comma, you must quote the value. For example:

$ ./rhino-console createraentity name=MyRA,vendor=Me,version=1.0 myra Value="The quick brown fox",Colour=brown

If the value requires quotes, you must escape them using a backslash ``' (to avoid them being removed by the parser). For example:

$ ./rhino-console createraentity name=MyRA,vendor=Me,version=1.0 myra Value="\"The quick brown fox\"",Colour=brown

MBean operation: createResourceAdaptorEntity

MBean

SLEE-defined

public void createResourceAdaptorEntity(ResourceAdaptorID id, String entityName, ConfigProperties properties)
    throws NullPointerException, InvalidArgumentException,
          UnrecognizedResourceAdaptorException,
          ResourceAdaptorEntityAlreadyExistsException,
          InvalidConfigurationException, ManagementException;

Arguments

This operation requires that you specify the resource adaptor entity’s:

  • ResourceAdaptorID — identifier of the resource adaptor from which to create the resource adaptor entity

  • entityName — an assigned name

  • ConfigProperties — configuration properties.


Note You only need to specify configuration properties that have no defined default, or have a default other than what the resource adaptor entity requires. (Rhino uses the default value if it is not specified within the properties argument.)

Tip
Rhino-defined configuration property

When creating a resource adaptor entity, you may specify the Rhino-defined configuration property: slee-vendor:com.opencloud.rhino_replicate_activities. This property describes the resource adaptor entity’s activity-replication behaviour (assuming it has been specifically designed to support activity-state replication in Rhino). Possible values are:

  • none — the resource adaptor entity will not generate replicated activities

  • mixed — the resource adaptor entity will generate a mix of replicated and non-replicated activities

  • all — all activities generated by the resource adaptor entity will be replicated.

The default value is none. (You can specify an alternative default by defining a configuration property in the deployment descriptor with this name but with a different default value.)

Removing a Resource Adaptor Entity

To remove a resource adaptor entity use the following rhino-console command or related MBean operation.

Note You can only remove a resource adaptor entity from the SLEE when it is in the INACTIVE state on all event-router nodes currently in the primary component.

Console command: removeraentity

Command

removeraentity <entity-name>
  Description
    Remove a resource adaptor entity

Example

To remove the resource adaptor entity named sipra:

$ ./rhino-console removeraentity sipra
Removed resource adaptor entity sipra

MBean operation: removeResourceAdaptorEntity

MBean

SLEE-defined

public void removeResourceAdaptorEntity(String entityName)
    throws NullPointerException,
          UnrecognizedResourceAdaptorEntityException,
          InvalidStateException, DependencyException, ManagementException;

Configuring Resource Adaptor Entities

Listing configuration properties for a Resource Adaptor Entity

To list the configuration properties for a resource adaptor entity use the following rhino-console command or related MBean operation.

Console command: listraentityconfigproperties

Command

listraentityconfigproperties <entity-name>
  Description
    List the configuration property values for a resource adaptor entity

Example

To list the resource adaptor entity called sipra:

$ ./rhino-console listraentityconfigproperties sipra
Configuration properties for resource adaptor entity sipra:
 Automatic100TryingSupport (java.lang.Boolean): true
 AutomaticOptionsResponses (java.lang.Boolean): true
 CRLLoadFailureRetryTimeout (java.lang.Integer): 900
 CRLNoCRLLoadFailureRetryTimeout (java.lang.Integer): 60
 CRLRefreshTimeout (java.lang.Integer): 86400
 CRLURL (java.lang.String):
 ClientAuthentication (java.lang.String): NEED
 EnableDialogActivityTests (java.lang.Boolean): false
 EnabledCipherSuites (java.lang.String):
 ExtensionMethods (java.lang.String):
 IPAddress (java.lang.String): AUTO
 Keystore (java.lang.String): sip-ra-ssl.keystore
 KeystorePassword (java.lang.String):
 KeystoreType (java.lang.String): jks
 MaxContentLength (java.lang.Integer): 131072
 OffsetPorts (java.lang.Boolean): false
 Port (java.lang.Integer): 5060
 PortOffset (java.lang.Integer): 101
 ReplicatedDialogSupport (java.lang.Boolean): false
 RetryAfterInterval (java.lang.Integer): 5
 SecurePort (java.lang.Integer): 5061
 TCPIOThreads (java.lang.Integer): 1
 Transports (java.lang.String): udp,tcp
 Truststore (java.lang.String): sip-ra-ssl.truststore
 TruststorePassword (java.lang.String):
 TruststoreType (java.lang.String): jks
 UseVirtualAddressInURIs (java.lang.Boolean): true
 ViaSentByAddress (java.lang.String):
 VirtualAddresses (java.lang.String):
 WorkerPoolSize (java.lang.Integer): 4
 WorkerQueueSize (java.lang.Integer): 50
 slee-vendor:com.opencloud.rhino_max_activities (java.lang.Integer): 0
 slee-vendor:com.opencloud.rhino_replicate_activities (java.lang.String): mixed

MBean operation: getConfigurationProperties

MBean

SLEE-defined

public ConfigProperties getConfigurationProperties(String entityName)
    throws NullPointerException, UnrecognizedResourceAdaptorEntityException, ManagementException;

Output

This operation returns a ConfigProperties object. A ConfigProperties object contains a set of ConfigProperty.Property objects, each of which identifies one configuration property defined by the RA. If the RA has defined a default value for the configuration property, the ConfigProperty.Property object will include it.

Updating configuration properties for a Resource Adaptor Entity

To update configuration properties for a resource adaptor entity use the following rhino-console command or related MBean operation.

Note
When is it appropriate to update configuration properties?

A resource adaptor may elect to support reconfiguration when its resource adaptor entities are active using the supports-active-reconfiguration attribute of the <resource-adaptor-class> deployment descriptor element.

If the value of the supports-active-reconfiguration attribute is False, the updateraentityconfigproperties command and related MBean operation may only be invoked to reconfigure a resource adaptor entity when it is in the Inactive state, or when the SLEE is in the Stopped state.

If the value of the supports-active-reconfiguration attribute is True, then a resource adaptor entity may be reconfigured when it, and the SLEE, are in any state, i.e. reconfiguration is possible while the resource adaptor entity is creating activities and firing events in the SLEE.

Console command: updateraentityconfigproperties

Command

updateraentityconfigproperties <entity-name> [<config-params>|(<property-name>
<property-value)*]
  Description
    Update configuration properties for a resource adaptor entity. Properties can be
    specified either as a single comma-separated string of name=value pairs or as a
    series of separate name and value argument pairs

Example

To update the Port and SecurePort in resource adaptor entity called sipra:

$ ./rhino-console updateraentityconfigproperties sipra Port 5061 SecurePort 5062
Updated configuration parameters for resource adaptor entity sipra

MBean operation: updateConfigurationProperties

MBean

SLEE-defined

public void updateConfigurationProperties(String entityName, ConfigProperties properties)
    throws NullPointerException, UnrecognizedResourceAdaptorEntityException,
           InvalidStateException, InvalidConfigurationException,
           ManagementException;

Input

This operation requires a ConfigProperties object. A ConfigProperties object contains a set of ConfigProperty.Property objects, each of which identifies one configuration property defined by the RA.

Activating and Deactivating Resource Adaptor Entities

Activating a Resource Adaptor Entity

To activate a resource adaptor entity on one or more nodes use the following rhino-console command or related MBean operation.

Console command: activateraentity

Command

activateraentity <entity-name> [-nodes node1,node2,...] [-ifneeded]
  Description
    Activate a resource adaptor entity (on the specified nodes)

Example

To activate the resource adaptor entity called sipra on nodes 101 and 102:

$ ./rhino-console activateraentity sipra -nodes 101,102
Activating resource adaptor entity sipra on node(s) [101,102]
Resource adaptor entity transitioned to the Active state on node 101
Resource adaptor entity transitioned to the Active state on node 102

MBean operation: activateResourceAdaptorEntity

MBean

SLEE-defined

Activate on all nodes
public void activateResourceAdaptorEntity(String entityName)
    throws NullPointerException, UnrecognizedResourceAdaptorEntityException,
          InvalidStateException, ManagementException;

Rhino’s implementation of the SLEE-defined activateResourceAdaptorEntity operation attempts to activate a resource adaptor entity on all current event-router nodes in the primary component. For this to work, the resource adaptor entity must be in the INACTIVE state on those nodes.

Rhino extension

Activate on specific nodes
public void activateResourceAdaptorEntity(String entityName, int[] nodeIDs)
    throws NullPointerException, InvalidArgumentException,
          UnrecognizedResourceAdaptorEntityException,
          InvalidStateException, ManagementException;

Rhino provides an extension that adds an argument that lets you control the nodes on which to activate the resource adaptor entity (by specifying node IDs). For this to work, the resource adaptor entity must be in the INACTIVE state on the specified nodes.

Deactivating a Resource Adaptor Entity

To deactivate a resource adaptor entity on one or more nodes use the following rhino-console command or related MBean operation.

Tip See also Reassigning a Resource Adaptor Entity’s Activities to Other Nodes, particularly the Requirements tab.

Console command: deactivateraentity

Command

deactivateraentity <entity-name> [-nodes node1,node2,... [-reassignto
node3,node4,...]] [-ifneeded]
  Description
    Deactivate a resource adaptor entity (on the specified nodes (reassigning
    replicated activities to the specified nodes))

Examples

To deactivate the resource adaptor entity named sipra on nodes 101 and 102:

$ ./rhino-console deactivateraentity sipra -nodes 101,102
Deactivating resource adaptor entity sipra on node(s) [101,102]
Resource adaptor entity transitioned to the Stopping state on node 101
Resource adaptor entity transitioned to the Stopping state on node 102

To deactivate the resource adaptor entity named sipra on node 101, and reassign replicated activities to node 102:

$ ./rhino-console deactivateraentity sipra -nodes 101 -reassignto 102
Deactivating resource adaptor entity sipra on node(s) [101]
Resource adaptor entity transitioned to the Stopping state on node 101
Replicated activities reassigned to node(s) [102]

To deactivate the resource adaptor entity named sipra on node 101, and distribute replicated activities equally among all other eligible nodes (those on which the resource adaptor entity is in the ACTIVE state and the SLEE is in the RUNNING state), specify an empty (zero-length) argument for the -reassignto option:

$ ./rhino-console deactivateraentity sipra -nodes 101 -reassignto ""
Deactivating resource adaptor entity sipra on node(s) [101]
Resource adaptor entity transitioned to the Stopping state on node 101
Replicated activities reassigned to node(s) [102,103]

MBean operation: deactivateResourceAdaptorEntity

MBean

SLEE-defined

Deactivate on all nodes
public void deactivateResourceAdaptorEntity(String entityName)
    throws NullPointerException, UnrecognizedResourceAdaptorEntityException,
          InvalidStateException, ManagementException;

Rhino’s implementation of the SLEE-defined deactivateResourceAdaptorEntity operation attempts to deactivate a resource adaptor entity on all current event-router nodes in the primary component. For this to work, the resource adaptor entity must be in the ACTIVE state on those nodes.

Rhino extensions

Deactivate on specific nodes
public void deactivateResourceAdaptorEntity(String entityName, int[] nodeIDs)
    throws NullPointerException, InvalidArgumentException,
        UnrecognizedResourceAdaptorEntityException, InvalidStateException,
        ManagementException;

Rhino provides an extension that adds an argument that lets you control the nodes on which to deactivate the resource adaptor entity (by specifying node IDs). For this to work, the resource adaptor entity must be in the ACTIVE state on the specified nodes.


Reassign deactivating activities to other nodes
public void deactivateResourceAdaptorEntity(String entityName, int[] nodeIDs, int[] reassignActivitiesToNodeIDs)
    throws NullPointerException, InvalidArgumentException,
        UnrecognizedResourceAdaptorEntityException, InvalidStateException,
        ManagementException;

Rhino also provides an extension that adds another argument, that lets you reassign ownership of replicated activities (from a replicating resource adaptor entity), distributing them equally among other available event-router nodes. This reduces the set of activities on the nodes with the deactivating resource adaptor entity, so the resource adaptor entity can return to the INACTIVE state on those nodes quicker. This only works for resource adaptor entities that are replicating activity state (see the description of the "Rhino-defined configuration property" for the MBean on Creating a Resource Adaptor Entity).

Reassigning a Resource Adaptor Entity’s Activities to Other Nodes

To reassign activities from a resource adaptor entity to a different node, use the following rhino-console command or related MBean operation, noting the requirements.

Note
Why reassign replicating activities?

A resource adaptor entity in the STOPPING state cannot return to the INACTIVE state until all the activities that it owns have ended. You can let a deactivating resource adaptor entity return to the INACTIVE state quicker by reassigning its replicating activities to other eligible nodes.

Console command: reassignactivities

Command

reassignactivities <entity-name> -from node1,node2,... -to node3,node4,...
  Description
    Reassign replicated activities of a resource adaptor entity from the specified
    nodes to other nodes

Examples

To reassign activities owned by the resource adaptor entity named sipra from node 101 to node 102 and 103:

$ ./rhino-console reassignactivities sipra -from 101 -to 102,103
Replicated activities for sipra reassigned to node(s) [102,103]
Tip
Reassigning to all available nodes

You can also specify an empty (zero-length) argument for the -to option. This reassigns replicated activities, distributing them equally among all other nodes that can adopt them (nodes on which the resource adaptor entity is in the ACTIVE state and the SLEE is in the RUNNING state).


To reassign activities owned by the resource adaptor entity named sipra from node 101 to all other eligible nodes:

$ ./rhino-console reassignactivities sipra -from 101 -to ""
Replicated activities for sipra reassigned to node(s) [102,103]

MBean operation: reassignActivities

MBean

Rhino extension

public void reassignActivities(String entityName, int[] fromNodeIDs, int[] toNodeIDs)
      throws NullPointerException, InvalidArgumentException,
            UnrecognizedResourceAdaptorEntityException,
            InvalidStateException, ManagementException;

This operation reassigns replicated activities owned by the named resource adaptor entity, on the nodes specified, using Rhino’s standard failover algorithm, to the nodes specified by the toNodeIDs argument. (If toNodeIDs is a zero-length array, the operation reassigns activities to any remaining eligible nodes.)

Requirements for reassigning activities

You can only reassign replicated activities from a resource adaptor entity to other nodes if the all the following conditions are satisfied:

  • The node is a current member of the primary component.

  • The node is an event-router node (not a quorum node).

  • The operational state of the SLEE on the node is RUNNING or STOPPING.

  • The operational state of the resource adaptor entity on the node is ACTIVE or STOPPING.

Further, a node can only take ownership of replicated activities if it satisfies all the following conditions:

  • The node is a current member of the primary component.

  • The node is an event-router node (not a quorum node).

  • The operational state of the SLEE on the node is RUNNING.

  • The operational state of the resource adaptor entity on the node is ACTIVE.

Also, non-replicated activities cannot be reassigned to other nodes, and a resource adaptor entity must end any non-replicated activities it created itself.

Tip You can choose to forcefully remove activities if a resource adaptor entity fails to end them in a timely manner.

Retrieving the State of Resource Adaptor Entities

Retrieving a Resource Adaptor Entity’s State

To retrieve the operational state of a resource adaptor entity, use the following rhino-console command or related MBean operation.

Console command: getraentitystate

Command

getraentitystate <entity-name> [-nodes node1,node2,...]
  Description
    Get the state of a resource adaptor entity (on the specified nodes)

Output

The rhino-console client displays the operational state of the specified node(s), or every event-router node in the primary component if none are specified.

Examples

To display the state of the resource adaptor entity with the name sipra on every event-router node:

$ ./rhino-console getraentitystate sipra
Resource adaptor entity is Inactive on node 101
Resource adaptor entity is Active on node 102

To display the state of the resource adaptor entity on only node 101:

$ ./rhino-console getraentitystate sipra -nodes 101
Resource adaptor entity is Inactive on node 101

MBean operation: getState

MBean

SLEE-defined

Return state of resource adaptor entity on current node
public ResourceAdaptorEntityState getState(String entityName)
    throws NullPointerException,
    UnrecognizedResourceAdaptorEntityException,
    ManagementException;

Rhino’s implementation of the SLEE-defined getState operation returns the state of a resource adaptor entity on the node where you invoke the operation.

Rhino extension

Return state of resource adaptor entity on specified node(s)
public ResourceAdaptorEntityState[] getState(String entityName, int[] nodeIDs)
    throws NullPointerException, InvalidArgumentException,
    UnrecognizedResourceAdaptorEntityException, ManagementException;

Rhino provides an extension that adds an argument which lets you control the nodes on which to return the state of the resource adaptor entity (by specifying node IDs).

Listing Resource Adaptor Entities by State

To list resource adaptor entities in a particular operational state, use the following rhino-console command or related MBean operation.

Console command: listraentitiesbystate

Command

listraentitiesbystate <state> [-node node]
  Description
    List the resource adaptor entities that are in the specified state (on the
    specified node)

Examples

To list the resource adaptor entities on the node where rhino-console is connected:

$ ./rhino-console listraentitiesbystate Active
No resource adaptor entities in Active state on node 101

To list the resource adaptor entities that are active on node 102:

$ ./rhino-console listraentitiesbystate Active -node 102
Resource adaptor entities in Active state on node 102:
sipra

MBean operation: getResourceAdaptorEntities

MBean

SLEE-defined

Return names of resource adaptor entities in specified state on current node
public String[] getResourceAdaptorEntities(ResourceAdaptorEntityState state)
    throws NullPointerException, ManagementException;

Rhino’s implementation of the SLEE-defined getResourceAdaptorEntities operation returns the names of resource adaptor entities in a specified state on the node where you invoke the operation.

Rhino extension

Return names of resource adaptor entities in specified state on specified node
public String[] getResourceAdaptorEntities(ResourceAdaptorEntityState state, int nodeID)
    throws NullPointerException, InvalidArgumentException,
    ManagementException;

Rhino provides an extension that lets you specify the nodes (by specifying node IDs) on which to return the names of resource adaptor entities in the specified state.

Note
What are resource adaptor entity link name bindings?

When an SBB needs access to a resource adaptor entity, it uses JNDI to get references to Java objects that implement the resource adaptor interface (provided by the resource adaptor entity). The SBB declares (in its deployment descriptor) the resource adaptor type it expects, and an arbitrary link name. Before activating a service using the SBB, an administrator must bind a resource adaptor entity (of the type expected) to the specified link name.

Rhino includes procedures for:

To bind a resource adaptor entity to a link name, use the following rhino-console command or related MBean operation.

Warning Only one resource adaptor entity can be bound to a link name at any time.

Command

bindralinkname <entity-name> <link-name>
  Description
    Bind a resource adaptor entity to a link name

Example

To bind the resource adaptor entity with the name sipra to the link name sip:

$ ./rhino-console bindralinkname sipra sip
Bound sipra to link name sip

MBean

SLEE-defined

public void bindLinkName(String entityName, String linkName)
    throws NullPointerException, InvalidArgumentException,
            UnrecognizedResourceAdaptorEntityException,
            LinkNameAlreadyBoundException, ManagementException;

To unbind a resource adaptor entity from a link name, use the following rhino-console command or related MBean operation.

Command

unbindralinkname <link-name>
  Description
    Unbind a resource adaptor entity from a link name

Example

To unbind the link name sip:

$ ./rhino-console unbindralinkname sip
Unbound link name sip

MBean

SLEE-defined

public void unbindLinkName(String linkName)
    throws NullPointerException, UnrecognizedLinkNameException,
            DependencyException,ManagementException;

To list resource adaptor entity link names that have been bound in the SLEE, use the following rhino-console command or related MBean operation.

Command

listralinknames [entity name]
  Description
    List the bound link names (for the specified resource adaptor entity)

Examples

To list all resource adaptor entity link name bindings:

$ ./rhino-console listralinknames
slee/resources/cdr -> cdrra
slee/resources/map -> mapra

To list all link name bindings for the resource adaptor entity named mapra:

$ ./rhino-console listralinknames mapra
slee/resources/map

MBean

SLEE-defined

List all bound link names
public String[] getLinkNames()
    throws ManagementException;

Rhino’s implementation of the SLEE-defined getLinkNames operation returns an array of all link names that have been bound in the SLEE.


List link names to which a specific resource adaptor entity has been bound
public String[] getLinkNames(String entityName)
    throws NullPointerException,
            UnrecognizedResourceAdaptorEntityException,
            ManagementException;

The SLEE-defined operation also includes an argument for returning just link names to which a specified resource adaptor entity has been bound. If the resource adaptor entity has not been bound to any link names, the returned array is zero-length.

Profile Tables and Profiles

As well as an overview of SLEE profiles, this section includes instructions for performing the following Rhino SLEE procedures with explanations, examples and links to related javadocs:

Procedure rhino-console command(s) MBean(s) → Operation
createprofiletable
Profile Provisioning → createProfileTable
createprofile
Profile Provisioning → createProfile
listprofiletables
Profile Provisioning → getProfileTables
listprofiles
Profile Provisioning → getProfiles
listprofileattributes
Profile Provisioning, Profile → getProfile
setprofileattributes
Profile Provisioning, Profile → getProfile
listprofilesbyattribute
listprofilesbyindexedattribute
Profile Provisioning → getProfilesByAttribute
Profile Provisioning → getProfilesByIndexedAttribute
Profile Provisioning → getProfilesByStaticQuery
Profile Provisioning → getProfilesByDynamicQuery
exportall
importprofiles
Profile Provisioning → exportProfiles
Profile Provisioning → importProfiles
Tip See also the New SLEE 1.1 Profile Features How-to Guide on the OpenCloud Developer Portal.

About Profiles

Note
What are profiles? profile tables? profile specifications?

A profile is an entry in a profile table. It has a name, may have values (called "attributes") and may have indexed fields. It’s like a row in SQL, but may also include business and management logic.

A profile table is a "container" for profiles. Its specification schema, the profile specification deployment descriptor, may define queries for the profile table. The SLEE specification defines the format and structure of profile specification schemas.

A profile table’s default profile is the initial set of profile attribute values for newly created profiles within that table (if not specified explicitly with the profile-creation command).

Before deploying a profile into the SLEE, an administrator can configure its profile specification. You do this by modifying values in the profile’s profile-spec-jar.xml deployment descriptor (in its deployable unit). For example, you can specify:

  • static queries available to SLEE components, and administrators using the management interface

  • profile specification environment entries

  • indexing hints for profile attributes.

Tip For more on profile static queries, environment entires and indexing, see the SLEE 1.1 specification.

Creating Profile Tables

To create a new profile table based on an already-deployed profile specification, use the following rhino-console command or related MBean operation.

Warning
Name character restriction

The profile table name cannot include the / character.

Console command: createprofiletable

Command

createprofiletable <profile-spec-id> <table-name>
  Description
    Create a profile table

Example

$ ./rhino-console createprofiletable name=AddressProfileSpec,vendor=javax.slee,version=1.1 testtable
Created profile table testtable

MBean operation: createProfileTable

MBean

SLEE-defined

public void createProfileTable(javax.slee.profile.ProfileSpecificationID id, String newProfileTableName)
    throws NullPointerException, UnrecognizedProfileSpecificationException,
          InvalidArgumentException, ProfileTableAlreadyExistsException,
          ManagementException;

Arguments

This operation requires that you specify the profile table’s:

  • id — component identifier of the profile specification from which to create the profile table

  • newProfileTableName —  name of the profile table to create.

Creating Profiles

To create a profile in an existing profile table, use the following rhino-console command or related MBean operation.

Console command createprofile

Command

createprofile <table-name> <profile-name> (<attr-name> <attr-value>)*
  Description
    Add a profile to a table, optionally setting attributes (see
    -setProfileAttributes option)

Add a profile to a table, optionally setting attributes (See Setting Profile attributes)

 
            

Example

$ ./rhino-console createprofile testtable testprofile
Profile testtable/testprofile created

Notes

Setting profile attributes

When creating a profile, decide the profile’s attribute names and then enter them in rhino-console as a space-separated list of property-name value pairs.


White space, commas, quotes

If a profile or profile table name or an attribute name or value contains white space or a comma, you must quote the string. For example:

$ ./rhino-console createprofile "testtable 2" "testprofile 2" SubscriberAddress "my address" forwarding true

If the value requires quotes, you must escape them using a backslash "\" (to avoid them being removed by the parser). For example:

$ ./rhino-console createprofile testtable testprofile attrib "\"The quick brown fox\""

Name uniqueness

The profile name must be unique within the scope of the profile table.

MBean operation: createProfile

MBean

SLEE-defined

public javax.management.ObjectName createProfile(String profileTableName, String newProfileName)
    throws NullPointerException, UnrecognizedProfileTableNameException,
          InvalidArgumentException, ProfileAlreadyExistsException,
          ManagementException;

Arguments

This operation requires that you specify the profile’s:

  • profileTableName — name of the profile table to create the profile in

  • newProfileName — name of the new profile.

Notes

Profile MBean commit state

This operation returns an ObjectName, which the management client can use to access a Profile MBean for the new profile. This MBean will be in the read-write state, so the management client can configure initial values for profile attributes before the SLEE adds the profile to the profile table. You cannot see the new profile in the profile table until you commit the Profile MBean’s state, using the ProfileMBean.commitProfile() operation.


Name uniqueness

The profile name must be unique within the scope of the profile table.

Listing Profile Tables

To list all profile tables in a SLEE, use the following rhino-console command or related MBean operation.

Console command: listprofiletables

Command

listprofiletables
  Description
    List the current created profile tables

Example

$ ./rhino-console listprofiletables
callbarring
callforwarding

MBean operation: getProfileTables

MBean

SLEE-defined

public Collection getProfileTables()
    throws ManagementException;

Listing Profiles

To list all profiles of a specific profile table, use the following rhino-console command or related MBean operation.

Console command: listprofiles

Command

listprofiles <table-name>
  Description
    List the profiles in a table

Example

$ ./rhino-console listprofiles testtable
testprofile

MBean operation: getProfiles

MBean

SLEE-defined

public Collection getProfiles(String profileTableName)
    throws NullPointerException, UnrecognizedProfileTableNameException,
          ManagementException;

Arguments

This operation requires that you specify the profile table’s:

  • profileTableName — name of the profile table.

Listing Profile Attributes

To list a profile’s attributes (names and current values), use the following rhino-console command or related MBean operation.

Console command: listprofileattributes

Command

listprofileattributes <table-name> [profile-name]
  Description
    List the current values of a profile, or if no profile is specified the current
    values of the default profile are listed

Example

$ ./rhino-console listprofileattributes testtable testprofile
Address={null}

MBean operation: getProfile

MBean

SLEE-defined

public javax.management.ObjectName getProfile(String profileTableName,String profileName)
    throws NullPointerException, UnrecognizedProfileTableNameException,
          UnrecognizedProfileNameException, ManagementException;

Arguments

This operation requires that you specify the profile table’s:

  • profileTableName — name of the profile table to get the profile from.

  • profileName — name of the profile.

Notes

Profile MBean state

This operation returns an ObjectName, which the management client can use to access a Profile MBean for this specific profile. This MBean will be in the read-only state, so the management client can only read the profile attributes. (To change profile attributes, see Setting Profile Attributes.)

Note For more about Profile MBeans, their requirements and restrictions, please see chapter 10.26 "Profile MBean" in the SLEE 1.1 Specification.

Setting Profile Attributes

To set a profile’s attribute values, use the following rhino-console command or related MBean operation.

Console command: setprofileattributes

Command

setprofileattributes <table-name> <profile-name> (<attr-name> <attr-value>)*
  Description
    Set the current values of a profile (use "" for default profile). The
    implementation supports only a limited set of attribute types that it can
    convert from strings to objects

Example

$ ./rhino-console setprofileattributes testtable testprofile Address IP:192.168.0.1
Set attributes in profile testtable/testprofile

Notes

White space, commas, quotes

If a profile or profile table name or an attribute name or value contains white space or a comma, you must quote the string. For example:

$ ./rhino-console setprofileattributes "testtable 2" "testprofile 2" SubscriberAddress "my address" forwarding true

If the value requires quotes, you must escape them using a backslash "\" (to avoid them being removed by the parser). For example:

$ ./rhino-console setprofileattributes testtable testprofile attrib "\"The quick brown fox\""

MBean operation: getProfile

MBean

SLEE-defined

public javax.management.ObjectName getProfile(String profileTableName,String profileName)
    throws NullPointerException, UnrecognizedProfileTableNameException,
          UnrecognizedProfileNameException, ManagementException;

Arguments

This operation requires that you specify the profile table’s:

  • profileTableName — name of the profile table to get the profile from.

  • profileName — name of the profile.

Notes

Profile MBean state

This operation returns an ObjectName, which the management client can use to access a Profile MBean for this specific profile. This MBean will be in the read-only state, so the management client can only read the profile attributes.

To put the MBean into the read-write state, invoke ProfileMBean.editProfile(). This will give you access to the profile’s attributes using the MBean’s getter and setter methods. You cannot see the profile’s new values until you commit the Profile MBean’s state, using the ProfileMBean.commitProfile() operation.

Note For more about Profile MBeans, their requirements and restrictions, please see chapter 10.26 "Profile MBean" in the SLEE 1.1 Specification.

Finding Profiles

Finding Profiles by Attribute Value

To retrieve all profiles with a specific attribute value, use the following rhino-console commands or related MBean operations:

Console command: listprofilesbyattribute

Command

listprofilesbyattribute <table-name> <attr-name> <attr-value>
[display-attributes (true/false)]
  Description
    List the profile which have an attribute <attr-name> equal to <attr-value>. The
    implementation supports only a limited set of attribute types that it can
    convert from strings to objects

Example

$ ./rhino-console listprofilesbyattribute testtable Address IP:192.168.0.1
1 profiles returned
ProfileID[table=testtable,profile=testprofile]

Notes

SLEE 1.1- & SLEE 1.0-specific commands

Between SLEE 1.0 and SLEE 1.1, the underlying profile specification schema changed significantly. According to the SLEE 1.1 Specification, profile attributes no longer have to be indexed to be legally used by a find-by-attribute-value query. Therefore, the listprofilesbyattribute command can only be used for profiles and profile tables that are based on a SLEE 1.1-compliant profile specification. For running a find-by-attribute-value search on a SLEE 1.0-compliant profile table, use the listprofilesbyindexedattribute command.


Backwards compatibility

SLEE 1.1 demands backwards compatibility for SLEE 1.0-compliant profiles, which means a SLEE 1.0 -compliant profile specification can be deployed into the SLEE; and profile tables and profiles can be successfully created and managed.

Console command: listprofilesbyindexedattribute

Command

listprofilesbyindexedattribute <table-name> <attr-name> <attr-value>
[display-attributes (true/false)]
  Description
    List the profiles which have an indexed attribute <attr-name> equal to
    <attr-value>. The implementation supports only a limited set of attribute types
    that it can convert from strings to objects

Example

$ ./rhino-console listprofilesbyindexedattribute testtable indexedAttrib someValue
1 profiles returned
ProfileID[table=testtable,profile=testprofile]

MBean operation: getProfilesByAttribute

MBean

SLEE-defined

public Collection getProfilesByAttribute(String profileTableName, String attributeName, Object attributeValue)
    throws NullPointerException, UnrecognizedProfileTableNameException,
          UnrecognizedAttributeException, InvalidArgumentException,
          AttributeTypeMismatchException, ManagementException;

Arguments

This operation requires that you specify the:

  • profileTableName — name of the profile table

  • attributeName — name of the profile’s attribute to check

  • attributeValue — value to compare the attribute with.

Notes

SLEE 1.1- & SLEE 1.0-specific commands

Between SLEE 1.0 and SLEE 1.1, the underlying profile specification schema changed significantly. According to the SLEE 1.1 Specification, profile attributes no longer have to be indexed to be legally used by a find-by-attribute-value query. Therefore, the getProfilesByAttribute operation can only be used for profiles and profile tables that are based on a SLEE 1.1-compliant profile specification. For running a find-by-attribute-value search on a SLEE 1.0-compliant profile table, use the getProfilesByIndexedAttribute operation.


Backwards compatibility

SLEE 1.1 demands backwards compatibility for SLEE 1.0-compliant profiles, which means a SLEE 1.0 compliant profile specification can be deployed into the SLEE; and profile tables and profiles can be successfully created and managed.

MBean operation: getProfilesByIndexedAttribute

MBean

SLEE-defined

public Collection getProfilesByIndexedAttribute(String profileTableName, String attributeName, Object attributeValue)
    throws NullPointerException, UnrecognizedProfileTableNameException,
          UnrecognizedAttributeException, AttributeNotIndexedException,
          AttributeTypeMismatchException, ManagementException;

Arguments

This operation requires that you specify the:

  • profileTableName — name of the profile table

  • attributeName — name of the profile’s attribute to check

  • attributeValue — value to compare the attribute with.

Finding Profiles Using Static Queries

To retrieve all profiles match a static query (pre-defined in a profile table’s profile specification schema), use the following MBean operation.

Note The Rhino SLEE does not use a rhino-console command for this function.

MBean operation: getProfilesByStaticQuery

MBean

SLEE-defined

public Collection getProfilesByStaticQuery(String profileTableName, String queryName, Object[] parameters)
    throws NullPointerException, UnrecognizedProfileTableNameException,
          UnrecognizedQueryNameException, InvalidArgumentException,
          AttributeTypeMismatchException, ManagementException;

Arguments

This operation requires that you specify the:

  • profileTableName — name of the profile table

  • queryName — name of a static query defined in the profile table’s profile specification deployment descriptor

  • parameters — an array of parameter values, to apply to parameters in the query (may only be null if the static query takes no arguments).

Tip For more about static query methods, please see chapter 10.8.2 "Static query methods" in the SLEE 1.1 specification.

Finding Profiles Using Dynamic Queries

To retrieve all profiles match a dynamic query (an expression the administrator constructs at runtime) , use the following MBean operation.

Note The Rhino SLEE does not use a rhino-console command for this function.

MBean operation: getProfilesByDynamicQuery

MBean

SLEE-defined

public Collection getProfilesByDynamicQuery(String profileTableName, QueryExpression expr)
    throws NullPointerException, UnrecognizedProfileTableNameException,
        UnrecognizedAttributeException, AttributeTypeMismatchException,
        ManagementException;

Arguments

This operation requires that you specify the:

  • profileTableName — name of the profile table

  • expr — query expression to apply to profiles in the profile table.

Tip For more about dynamic query methods, please see chapter 10.20.3 "Dynamic Profile queries" in the SLEE 1.1 specification.

Export and Import

Rhino includes procedures for:

Exporting Profiles

To export SLEE profiles, use the following rhino-console command or related MBean operation.

Console command: exportall

Note The Rhino command console currently does not have a command specific to profile exports. Instead you use a more general export function, which (apart from SLEE profiles) also exports deployable units for services and RAs currently installed in the SLEE.

Command

exportall <target directory>
  Description
    Export the internal state of the SLEE including deployable units, profile
    tables, and other component state. Uses JMX to export profiles and writes XML.
    Use the standalone rhino-export utility to export profile snapshots

Example

$ ./rhino-console exportall /home/userXY/myexport
Exporting file:jars/incc-callbarring-service.jar...
Exporting file:jars/incc-callforwarding-service.jar...
Taking snapshot for callforwarding
Saving callforwarding.jar (183kb)
Streaming profile table 'callforwarding' snapshot to callforwarding.data (2 entries)
[################################################################################] 2/2 entries

Taking snapshot for callbarring
Saving callbarring.jar (177kb)
Streaming profile table 'callbarring' snapshot to callbarring.data (2 entries)
[################################################################################] 2/2 entries

Extracted 4 of 4 entries (157 bytes)
Snapshot timestamp 2008-05-07 15:17:42.325 (1210130262325)
   Critical region time     : 0.002 s
   Request preparation time : 0.053 s
   Data extraction time     : 0.302 s
   Total time               : 0.355 s

Converting 2 profile table snapshots...
Converting callforwarding...
bean class=class com.opencloud.deployed.Profile_Table_2.ProfileOCBB_Bean
[###########################################################################] converted 2 of 2
[###########################################################################] converted 2 of 2
Converted 2 records

Converting callbarring...
bean class=class com.opencloud.deployed.Profile_Table_1.ProfileOCBB_Bean
[###########################################################################] converted 2 of 2
[###########################################################################] converted 2 of 2
Converted 2 records
Export complete
Tip
Exported profile files

After the export, you will find the exported profiles as .xml files in the profiles subfolder of the chosen export directory (in the above example, /home/userXY/myexport/profiles).

Exporting "snapshots"

See also Profile Snapshots, to export profile snapshots in binary format and convert them into xml format for later imports.

Exporting a SLEE

See also Exporting a SLEE, to export all deployed components and configuration of a Rhino SLEE.

MBean operation: exportProfiles

MBean

Rhino extension

com.opencloud.rhino.management.profile.ProfileDataCollection exportProfiles(String profileTableName, String[] profileNames)
    throws NullPointerException, UnrecognizedProfileTableNameException,
    ManagementException;

Arguments

This operation requires that you specify the profile table’s:

  • profileTableName — name of the profile table to export from

  • profileNames — an array listing the profile names to export (elements corresponding to unknown profile names are ignored).

Tip
Exporting the default profile

To export the default profile, enter a null element in the profileNames array.

Importing Profiles

To import SLEE profiles, use the following rhino-console command or related MBean operation.

Console command: importprofiles

Tip Use the importprofiles command to import profile data from an xml file that has previously been created (for example, using the exportall command).

Command

importprofiles <filename.xml> [-table table-name] [-replace] [-max
profiles-per-transaction] [-noverify]
  Description
    Import profiles from xml data

Example

$ ./rhino-console exportall /home/userXY/myexport
...
./rhino-console importprofiles /home/userXY/myexport/profiles/testtable.xml
Importing profiles into profile table: testtable
2 profile(s) processed: 1 created, 0 replaced, 0 removed, 1 skipped

Notes

Referenced profile table must exist

For the profile import to run successfully, the profile table the xml data refers to must exist before invoking the importprofiles command. (The importprofiles command will not create the profile table if it does not exist. Instead it will complete successfully — but without importing anything.)

MBean operation: importProfiles

MBean

Rhino extension

com.opencloud.rhino.management.profile.ProfileImportResult importProfiles(com.opencloud.rhino.management.profile.ProfileDataCollection profileData)
    throws NullPointerException, UnrecognizedProfileTableNameException,
          InvalidArgumentException, ProfileAlreadyExistsException,
          UnrecognizedProfileNameException, ManagementException;

Arguments

This operation requires that you specify the profile table’s:

  • profileData — the profile data collection containing the exported profiles.

Tip
Importing the default profile

To import the default profile, include a profile with a null name in the profile data collection.

Alarms

As well as an overview and list of alarms, this section includes instructions for performing the following Rhino SLEE procedures, with explanations, examples and links to related javadocs.

Procedure rhino-console command MbBean → Operations
listactivealarms
Alarm → getAlarms
Alarm → getDescriptors
clearalarm
Alarm → clearAlarm
clearalarms
Alarm → clearAlarms
setalarmlogperiod
getalarmlogperiod
Logging Management → SetAlarmLogPeriod
Logging Management → GetAlarmLogPeriod
createthresholdrule
removethresholdrule
Threshold Rule Management → createRule
Threshold Rule Management → removeRule
listthresholdrules
Threshold Rule Management → getRules
  • Viewing a current threshold-alarm rule

  • Saving a threshold-alarm rule configuration to a file for editing

  • Importing a modified threshold-alarm rule

  • Configuring trigger conditions for a threshold-alarm rule (adding, getting, removing, getting and setting operators and periods)

  • Configuring reset conditions for a threshold-alarm rule (adding, getting, removing, getting and setting operators and periods)

  • Setting a threshold rule alarm

  • Getting a threshold rule alarm’s level, type and message

getconfig
exportconfig
importconfig
Threshold Rule → addTriggerCondition
Threshold Rule → getTriggerConditions
Threshold Rule → removeTriggerCondition
Threshold Rule → getTriggerConditionsOperator
Threshold Rule → setTriggerConditionsOperator
Threshold Rule → getTriggerPeriod
Threshold Rule → setTriggerPeriod
Threshold Rule → addResetCondition
Threshold Rule → getResetConditions
Threshold Rule → removeResetCondition
Threshold Rule → getResetConditionsOperator
Threshold Rule → setResetConditionsOperator
Threshold Rule → getResetPeriod
Threshold Rule → setResetPeriod
Threshold Rule → setAlarm
Threshold Rule → getAlarmLevel
Threshold Rule → getAlarmType
Threshold Rule → getAlarmMessage
activatethresholdrule
Threshold Rule → activateRule
Threshold Rule → deactivateRule
getthresholdrulescanperiod
setthresholdrulescanperiod
Threshold Rule Management → getScanPeriod
Threshold Rule Management → setScanPeriod

About Alarms

Alarms in Rhino alert the SLEE administrator to exceptional conditions.

Application components in the SLEE raise them, as does Rhino itself (upon detecting an error condition). Rhino clears some alarms automatically when the error conditions are resolved. The SLEE administrator must clear others manually.

When an alarm is raised or cleared, Rhino generates a JMX notification from the Alarm MBean. Management clients may attach a notification listener to the Alarm MBean, to receive alarm notifications. Rhino logs all alarm notifications.

What’s new in SLEE 1.1?

While only SBBs could generate alarms in SLEE 1.0, other types of application components can also generate alarms in SLEE 1.1.

In SLEE 1.1, alarms are stateful — between being raised and cleared, an alarm persists in the SLEE, where an administrator may examine it. (In SLEE 1.0, alarms could be generated with a severity level that indicated a cleared alarm, but the fact that an error condition had occurred did not persist in the SLEE beyond the initial alarm generation.)

Sample log file messages

SLEE 1.1

Alarm1 1

SLEE 1.0

Alarm1 0
Note For both SLEE 1.1 and 1.0, if the cause of an alarm is an Java exception, the log includes the exception and its stack trace (following the alarm description message).
Tip See also the How Do I Use Stateful Alarms in SLEE 1.1 on the OpenCloud Developer Portal.

Configuring alarm log period

To set and get the interval between periodic active alarm logs, use the following rhino-console commands or related MBean operations.

Rhino periodically logs active alarms and the default interval is 60 seconds.

setalarmlogperiod

Command

setalarmlogperiod <seconds>
  Description
    Sets the interval between periodic active alarm logs.
  Required Arguments
    seconds  The interval between periodic alarm logs. Setting to 0 will disable
    logging of periodic alarms.

Example

To set log period to 30 seconds:

$ ./rhino-console setalarmlogperiod 30
  Active alarm logging period set to 30 seconds.

getalarmlogperiod

Command

getalarmlogperiod
  Description
    Returns the interval between periodic active alarm logs.

Example

To get alarm log period:

$ ./rhino-console getalarmlogperiod
  Active alarm logging period is currently 30 seconds.

MBean operations: setAlarmLogPeriod

MBean

SLEE-defined

Set the interval between periodic active alarm logs
public void setAlarmLogPeriod(int period) throws IllegalArgumentException, ConfigurationException;

Sets the interval between periodic active alarm logs. Setting the period to 0 will disable periodic alarm logging.

Get the interval between periodic active alarm logs
public int getAlarmLogPeriod() throws ConfigurationException;

Returns the interval between periodic active alarm logs.

Viewing Active Alarms

To view active alarms, use the following rhino-console command or related MBean operation.

Console command: listactivealarms

Command

listactivealarms [<type> <notif-source>] [-stack]
  Description
    List the alarms currently active in the SLEE (for a specific notification if
    provided).  Use -stack to display stack traces for alarm cause exceptions.

Example

To list all active alarms in the SLEE:

$ ./rhino-console listactivealarms
1 alarm:

Alarm 101:193215480667648 [diameter.peer.connectiondown]
  Level      : Warning
  InstanceID : diameter.peer.hss-instance
  Source     : (RA Entity) sh-cache-ra
  Timestamp  : 20161019 14:02:58 (active 15m 30s)
  Message    : Connection to hss-instance:3868 is down

The number value on the first line "101:193215480667648" is the alarmid.

The value in the square brackets "diameter.peer.connectiondown" is the alarm-type.

MBean operations: getAlarms and getDescriptors

MBean

SLEE-defined

Get identifiers of all active alarms in the SLEE
public String[] getAlarms()
    throws ManagementException;

Rhino’s implementation of the SLEE-defined getAlarms operation returns an array containing the identifiers of all alarms currently raised in the SLEE, regardless of which cluster node the alarm was raised on.


Get identifiers of active alarms raised by a specific notification source
public String[] getAlarms(NotificationSource notificationSource)
    throws NullPointerException, UnrecognizedNotificationSourceException,
           ManagementException;

This variant of getAlarms returns an array containing the identifiers of the current alarms that were raised by the specified notification source, on any node in the cluster. If there are currently no active alarms raised by this notification source, the operation returns a zero-length array.


Get alarm descriptor for an alarm identifier
public Alarm[] getDescriptors(String[] alarmIDs)
    throws NullPointerException, ManagementException;

This operation returns the alarm descriptor for each given alarm identifier.

Clearing Alarms

Clear Individual Alarms

To clear an alarm using its alarm identifier, use the following rhino-console command or related MBean operation.

Console command: clearalarm console command

Command

clearalarm <alarmid>
  Description
    Clear the specified alarm.

Example

To clear the alarm with the identifier 101:102916243593:1:

$ ./rhino-console clearalarm 101:102916243593:1
Alarm 101:102916243593:1 cleared

MBean operation: clearAlarm

MBean

SLEE-defined

public boolean clearAlarm(String alarmID)
  throws NullPointerException, ManagementException;

Rhino’s implementation of the SLEE-defined clearAlarm operation clears the alarm with the given identifier, regardless of the cluster node the alarm was raised on. It returns a value of either true or false, depending on whether or not the SLEE found and cleared the alarm.

Clear Alarms Raised by a Particular Notification Source

To clear alarms raised by a particular notification source, use the following rhino-console command or related MBean operation.

Console command: clearalarms

Command

clearalarms <type> <notification-source> [<alarm type>]
  Description
    Clear all alarms raised by the notification source (of the specified alarm type)

This command clears all alarms of the specified alarm type (or all alarms if no alarm-type is specified), that have been raised by the specified notification source.

Example

To clear all alarms raised by a resource adaptor entity named insis-cap:

$ ./rhino-console clearalarms resourceadaptorentity insis-cap
2 alarms cleared

To clear only "noconnection" alarms raised by the resource adaptor entity named insis-cap:

$ ./rhino-console clearalarms resourceadaptorentity insis-cap noconnection
1 alarm cleared

MBean operation: clearAlarms

MBean

SLEE-defined

Clear all active alarms raised by a notification source
public int clearAlarms(NotificationSource notificationSource)
    throws NullPointerException, UnrecognizedNotificationSourceException,
        ManagementException

Rhino’s implementation of the SLEE-defined clearAlarms operation clears all active alarms that were raised by the given notification source on any cluster node. It returns the number of alarms that were cleared.


Clear active alarms of a specified type raised by a notification source
public int clearAlarms(NotificationSource notificationSource, String alarmType)
    throws NullPointerException, UnrecognizedNotificationSourceException,
        ManagementException;

This variant of clearAlarms clears only active alarms of the given alarm type raised by the given notification source on any cluster node. It also returns the number of alarms that were cleared.

Threshold Alarms

To supplement standard alarms (which Rhino and installed components raise), an administrator may configure custom alarms (which Rhino will raise or clear automatically based on SLEE Statistics.

These are known as threshold alarms, and you manage them using the Threshold Rule Management MBean.

Threshold rules

You configure the threshold rules governing each threshold alarm using a Threshold Rule MBean.

Each threshold rule consists of:

  • a unique name identifying the rule

  • one or more trigger conditions

  • an alarm level, type and message text

  • and optionally:

    • one or more reset conditions

    • how long (in milliseconds) the trigger conditions must remain before Rhino raises the alarm

    • how long (in milliseconds) the reset conditions must remain before Rhino clears the alarm.

Tip You can combine condition sets using either an AND or an OR operator. (AND means all conditions must be satisfied, whereas OR means any one of the conditions may be satisfied — to raise or clear the alarm.)

Parameter sets

Threshold rules use the same parameter sets as the statistics client. You can discover them either by using the statistics client graphically or by using its command-line mode from a command shell as shown below.

To list all available parameter sets:
$ ./rhino-stats -l
The following root parameter sets are available for monitoring:
Activities, ActivityHandler, ByteArrayBuffers, CGIN, DatabaseQuery, Diameter,
EndpointLimiting, EventRouter, Events, HTTP, JDBCDatasource, JVM, LicenseAccounting,
Limiters, LockManagers, MemDB-Local, MemDB-Replicated, MemDB-Timestamp, Metrics,
ObjectPools, SIP, SIS-SIP, SLEE-Usage, Services, StagingThreads, StagingThreads-Misc,
TimerFacility, TransactionManager

For parameter set type descriptions and a list of available parameter sets use the
-l <root parameter set name> option
To list the statistics collected by the JVM parameter set:
$ ./rhino-stats -l JVM
Connecting to localhost:1199
Parameter Set: JVM
Parameter Set Type: JVM
Description: JVM Statistics

Counter type statistics:
  Id: Name:                 Label:      Description:
  0   heapUsed              husd        Used heap memory
  1   heapCommitted         hcomm       Committed heap memory
  2   heapInitial           hinit       Initial heap memory
  3   heapMaximum           hmax        Maximum heap memory
  4   nonHeapUsed           nhusd       Used non-heap memory
  5   nonHeapCommitted      nhcomm      Committed non-heap memory
  6   nonHeapInitial        nhinit      Initial non-heap memory
  7   nonHeapMaximum        nhmax       Maximum non-heap memory
  8   classesCurrentLoaded  cLoad       Number of classes currently loaded
  9   classesTotalLoaded    cTotLoad    Total number of classes loaded since JVM start
  10  classesTotalUnloaded  cTotUnload  Total number of classes unloaded since JVM start

Sample type statistics: (none defined)

Found 1 parameter sets under 'JVM':
    ->  "JVM"

How Rhino evaluates threshold rules

Rhino periodically evaluates the trigger conditions of each configured rule. When a trigger condition is satisfied and its trigger period has been met or exceeded, Rhino raises the corresponding alarm. If the rule has reset conditions, Rhino evaluates those too, and when the reset condition is satisfied and the reset trigger period has been met or exceeded, clears the alarm. If the rule does not have reset conditions, an administrator must clear the alarm manually.

You can configure the frequency of threshold alarm rule evaluation, using the Threshold Rule Management MBean. An administrator can specify a polling frequency in milliseconds, or enter 0 to disable rule evaluation. The Rhino default is 0 (which must be changed to enable threshold-rule evaluation). Ideal polling frequency is highly dependent on the nature of alarms configured.

Simple and relative rule conditions

There are two types of threshold rule conditions, explained in the tables below.

Simple rule conditions

What it compares Operators for comparison Conditions Example

The value of a counter-type Rhino statistic against a constant value.

>, >=, <, ⇐, ==, !=

The constant value to compare against may be any floating-point number. The condition can either compare against the absolute value of the statistic (suitable for gauge-type statistics), or against the observed difference between successive samples (suitable for pure counter-type statistics).

A condition that selects the statistic rolledBack from the Transactions parameter set, and evaluates to true when the number of transactions rolled back is > 100.

Relative rule conditions

What it compares Operators for comparison Conditions Example

The ratio between two monitored statistics against a constant value.

>, >=, <, ⇐, ==, !=

The constant value to compare against may be any floating-point number.

A condition that selects the statistics freeMemory and totalMemory from the SystemInfo parameter set, and evaluates to true when free heap space is less than 20% of total heap space. (Using the < operator and a constant value of 0.2, the condition would evaluate to true when the value of freeMemory / totalMemory is less than 0.2.)

Note For definitions of counter, guage and sample type statistics, see About Rhino Statistics.

Creating and Removing Rules

To create or remove a threshold-alarm rule, use the following rhino-console commands or related MBean operations.

Console command: createthresholdrule

Command

createthresholdrule <name>
  Description
    Create a threshold alarm rule

Example

To create a rule named "low memory":

$ ./rhino-console createthresholdrule "low memory"
Threshold rule low memory created

MBean operation: createRule

MBean

Rhino operation

public ObjectName createRule(String ruleName)
    throws ConfigurationException, ValidationException;

This operation creates a rule with the name given, and returns the JMX object name of a Threshold Rule MBean (which you can use to configure that rule).

Console command: removethresholdrule

Command

removethresholdrule <name>
  Description
    Remove a threshold alarm rule

Example

To remove a rule named "low memory":

$ ./rhino-console removethresholdrule "low memory"
Threshold rule low memory removed

MBean operation: removeRule

MBean

Example

public void removeRule(String ruleName)
    throws ConfigurationException, ValidationException;

This operation removes the rule with the name given.

Listing Rules

To list all threshold alarm rules, use the following rhino-console command or related MBean operation.

Console command: listthresholdrules

Command

listthresholdrules
  Description
    List threshold alarm rules

Example

To list all threshold alarm rules, with their activation states:

$ ./rhino-console listthresholdrules
Current threshold rules:
    low memory (active)
    low disk (inactive)
    testrule (inactive)

MBean operation: getRules

MBean

Rhino operation

public String[] getRules()
    throws ConfigurationException;

Configuring Rules

To configure a threshold alarm rule:

View rules

To view a current threshold alarm rule., use the getconfig console command:

Command

getconfig [-namespace] <configuration type> [configuration key]
  Description
    Extract and display content of a container configuration key.  The optional
    -namespace argument must be used to get the config of a namespace-specific key.
    If no key is specified the configs of all keys of the given type are shown

Example

To display the threshold alarm rule named "low_memory":

$ ./rhino-console getconfig threshold-rules "rule/low_memory"
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE rhino-threshold-rules-config PUBLIC "-//Open Cloud Ltd.//DTD Rhino Threshold Rules Config 2.3//EN" "rhino-threshold-rules-config-2.3.dtd">
<rhino-threshold-rules-config config-version="2.3" rhino-version="Rhino (version='2.5', release='1.0', build=xxx, revision=xxx)" timestamp="xxx">
    <!-- Generated Rhino configuration file: xxxx-xx-xx xx:xx:xx.xxx -->
    <threshold-rules active="false" name="low_memory">
        <trigger-conditions name="Trigger conditions" operator="OR" period="0">
            <relative-threshold operator="&lt;=" value="0.2">
                <first-statistic calculate-delta="false" parameter-set="JVM.OperatingSystem" statistic="freePhysicalMemorySize"/>
                <second-statistic calculate-delta="false" parameter-set="JVM.OperatingSystem" statistic="totalPhysicalMemorySize"/>
            </relative-threshold>
        </trigger-conditions>
        <reset-conditions name="Reset conditions" operator="OR" period="0"/>
        <trigger-actions>
            <raise-alarm-action level="Major" message="Low on memory" type="MEMORY"/>
        </trigger-actions>
        <reset-actions>
            <clear-raised-alarm-action/>
        </reset-actions>
    </threshold-rules>
</rhino-threshold-rules-config>

Export rules

To save a threshold rule configuration to a file for editing, use the exportconfig console command:

Command

exportconfig [-namespace] <configuration type> [configuration key] <filename>
  Description
    Extract content of a container configuration key and save it to a file.  The
    optional -namespace argument must be used to export the config of a
    namespace-specific key

Example

To export the threshold alarm rule named "low memory" to the file rule_low_memory.xml:

$ ./rhino-console exportconfig threshold-rules "rule/low memory" rule_low_memory.xml
Export threshold-rules: (rule/low memory) to rule_low_memory.xml
Wrote rule_low_memory.xml
Note The structure of the exported data in the XML file is identical to that displayed by the getconfig command.

Edit rules

You can modify a rule using a text editor. In the following example, a reset condition has been added to a rule previously exported, so that the alarm raised will automatically clear when free memory becomes greater than 30%. (Previously the reset-conditions element in this rule had no conditions.)

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE rhino-threshold-rule PUBLIC "-//Open Cloud Ltd.//DTD Rhino Threshold Rule 2.0//EN"
  "http://www.opencloud.com/dtd/rhino-config-threshold-rules_2_0.dtd">
<rhino-threshold-rule config-version="2.3" rhino-version="Rhino (version='2.5', release='00',
  build=xxx, revision=xxx)" timestamp=xxx>
    <!-- Generated Rhino configuration file: xxxx-xx-xx xx:xx:xx.xxx -->
    <threshold-rules active="false" name="low memory">
        <trigger-conditions name="Trigger conditions" operator="OR" period="0">
            <relative-threshold operator="&lt;=" value="0.2">
                <first-statistic calculate-delta="false" parameter-set="JVM.OperatingSystem" statistic="freePhysicalMemorySize"/>
                <second-statistic calculate-delta="false" parameter-set="JVM.OperatingSystem" statistic="totalPhysicalMemorySize"/>
            </relative-threshold>
        </trigger-conditions>
        <reset-conditions name="Reset conditions" operator="OR" period="0">
            <relative-threshold operator="&gt;" value="0.3">
                <first-statistic calculate-delta="false" parameter-set="JVM.OperatingSystem" statistic="freePhysicalMemorySize"/>
                <second-statistic calculate-delta="false" parameter-set="JVM.OperatingSystem" statistic="totalPhysicalMemorySize"/>
            </relative-threshold>
        </reset-conditions>
        <trigger-actions>
            <raise-alarm-action level="Major" message="Low on memory" type="MEMORY"/>
        </trigger-actions>
        <reset-actions>
            <clear-raised-alarm-action/>
        </reset-actions>
    </threshold-rules>
</rhino-threshold-rule>

Import rules

To import the modified threshold alarm rule file, use the importconfig console command:

Command

importconfig [-namespace] <configuration type> <filename> [-replace]
  Description
    Import a container configuration key.  The optional -namespace argument must be
    used to import a config for a namespace-specific key

Example

To import the threshold alarm rule from the file rule_low_memory.xml:

$ ./rhino-console importconfig threshold-rules rule_low_memory.xml -replace
Configuration successfully imported.
Warning The -replace option is required when importing a rule with the same name as an existing rule, as there can be only one rule configuration with a given name present at any one time.

Threshold Rule MBean Operations

To configure a threshold alarm rule, use the following MBean operations (defined on the Threshold Rule MBean interface), for:

  • adding, removing and getting trigger conditions, and getting and setting their operators and periods

  • adding, removing and getting reset conditions, and getting and setting their operators and periods

  • setting the alarm

  • getting an alarm’s level, type, and message.

Tip See also Configuring Rules.

Trigger conditions

To add, remove and get threshold alarm trigger conditions, and get and set their operators and periods, use the following MBean operations:

Operations Usage

addTriggerCondition
getTriggerConditions
removeTriggerCondition
getTriggerConditionsOperator
setTriggerConditionsOperator
getTriggerPeriod
setTriggerPeriod

To add a trigger condition to the rule:
public void addTriggerCondition(String parameterSetName, String statistic, String operator, double value)
    throws ConfigurationException, UnknownStatsParameterSetException,
          UnrecognizedStatisticException, ValidationException;
public void addTriggerCondition(String parameterSetName1, String statistic1, String parameterSetName2,
              String statistic2, String operator, double value
    throws ConfigurationException, UnknownStatsParameterSetException,
          UnrecognizedStatisticException, ValidationException;

The first operation adds a simple trigger condition to the rule. The second operation adds a relative condition between two parameter set statistics (see Simple and relative rule conditions).


To get the current trigger conditions:
public String[] getTriggerConditions()
    throws ConfigurationException;

To remove a trigger condition:
public void removeTriggerCondition(String key)
    throws ConfigurationException, ValidationException;

To get or set the trigger condition operator:
public String getTriggerConditionsOperator()
    throws ConfigurationException;
public void setTriggerConditionsOperator(String operator)
    throws ConfigurationException, ValidationException;

The operator must be one of the logical operators AND or OR (the operator is ignored if the rule has only one trigger condition).


To get or set the trigger condition period:
public long getTriggerPeriod()
    throws ConfigurationException;
public void setTriggerPeriod(long period)
    throws ConfigurationException, ValidationException;

The trigger period is measured in milliseconds. If it is 0, the SLEE raises the alarm whenever the trigger conditions are true (and the alarm is not already raised). Otherwise, the SLEE raises the alarm once the trigger conditions have held true for at least the amount of time specified.

Reset conditions

To add, remove and get threshold alarm reset conditions, and get and set their operators and periods, use the following MBean operations:

Operations Usage

addResetCondition
getResetConditions
removeResetCondition
getResetConditionsOperator
setResetConditionsOperator
getResetPeriod
setResetPeriod

To add a reset condition to the rule:
public void addResetCondition(String parameterSetName, String statistic, String operator, double value)
    throws ConfigurationException, UnknownStatsParameterSetException,
           UnrecognizedStatisticException, ValidationException;
public void addResetCondition(String parameterSetName1, String statistic1, String parameterSetName2,
                              String statistic2, String operator, double value)
    throws ConfigurationException, UnknownStatsParameterSetException,
           UnrecognizedStatisticException, ValidationException;

The first operation adds a simple reset condition to the rule. The second operation adds a relative condition between two parameter set statistics (see bxfref:threshold-alarms[Simple and relative rule conditions]).


To get the current reset conditions:
public String[] getResetConditions()
    throws ConfigurationException;

To remove a reset condition:
public void removeResetCondition(String key)
    throws ConfigurationException, ValidationException;

To get or set the reset condition operator:
public String getResetConditionsOperator()
    throws ConfigurationException;
public void setResetConditionsOperator(String operator)
    throws ConfigurationException, ValidationException;

The operator must be one of the logical operators AND or OR (the operator is ignored if the rule has only one reset condition).


To get or set the reset condition period:
public long getResetPeriod()
    throws ConfigurationException;
public void setResetPeriod(long period)
    throws ConfigurationException, ValidationException;

The reset period is measured in milliseconds. If it is 0, the SLEE clears the alarm whenever the reset conditions are true (and the alarm is raised). Otherwise, the SLEE clears the alarm once the reset conditions have held true for at least the amount of time specified.

Setting alarms

To set the alarm to be raised by a threshold rule, use the following MBean operation:

Operations Usage

setAlarm

public void setAlarm(AlarmLevel level, String type, String message)
    throws ConfigurationException, ValidationException;

The alarm level may be any level other than AlarmLevel.CLEAR

Getting alarm information

To get a threshold alarm’s level, type, and message, use the following MBean operations:

Operations Usage

getAlarmLevel
getAlarmType
getAlarmMessage

public AlarmLevel getAlarmLevel()
    throws ConfigurationException;
public String getAlarmType()
    throws ConfigurationException;
public String getAlarmMessage()
    throws ConfigurationException;

Activating and Deactivating Rules

To activate or deactivate a threshold-alarm rule, use the following rhino-console commands or related MBean operations.

Activate Rules

Console command: activatethresholdrule

Command

activatethresholdrule <name>
  Description
    Activate a threshold alarm rule

Example

To activate the rule with the name "low memory":

$ ./rhino-console activatethresholdrule "low memory"
Threshold rule low memory activated
Tip You can also activate a rule by exporting it, modifying the XML, and then reimporting it (assuming the active parameter in the rule is set to true — see Configuring Rules).

MBean operation: activateRule

MBean

Rhino operation

public void activateRule()
    throws ConfigurationException;

This operation activates the threshold-alarm rule represented by the ThresholdRuleMBean.

Warning threshold rule scan period must be configured to a non-zero value before Rhino will evaluate active threshold-alarm rules.

Deactivate rules

Console command: deactivatethresholdrule

Command

deactivatethresholdrule <name>
  Description
    Deactivate a threshold alarm rule

Example

To deactivate the rule with the name "low memory":

$ ./rhino-console deactivatethresholdrule "low memory"
Threshold rule low memory deactivated

MBean operation: deactivateRule

MBean

Rhino operation

public void deactivateRule()
    throws ConfigurationException;

This operation deactivates the threshold-alarm rule represented by the ThresholdRuleMBean.

Setting and Getting Rule-Scan Periods

To set or get the threshold rule scan period, use the following rhino-console commands or MBean operations.

Note
What is a rule-scan period?

A threshold-alarm rule-scan period determines when Rhino’s threshold-rule scanner evaluates active threshold-alarm rules.

The scan period must be set to a valid non-zero value for Rhino to evaluate the rules. At the beginning of each scan period, Rhino evaluates each active threshold-alarm rule as follows:

  • If the rule’s trigger condition is true and the trigger period is 0, the rule triggers and raises its alarm.

  • The first time the threshold-rule scanner finds a rule’s trigger condition to be true, with a trigger period greater than 0, it records the time. Thereafter, when it evaluates the rule, if the trigger condition continues to be true, when the accumulated time exceeds the rule’s trigger period, the rule triggers and raises its alarm. (If the rule evaluates to false at any time, the rule scanner discards any accumulated time from while it was true.)

(The same process applies to the reset conditions once a rule has been triggered.)

Console command: setthresholdrulescanperiod

Command

setthresholdrulescanperiod <period>
  Description
    Set the threshold alarm rule scan period, measured in ms.  Must be > 500 or 0 to
    disable rule checking

Example

To set the threshold rule scan period to 30000ms (30s):

$ ./rhino-console  setthresholdrulescanperiod 30000
Threshold rule scan period set to 30000ms

To disable threshold rule scanning:

$ ./rhino-console  setthresholdrulescanperiod 0
Threshold rule scanning disabled

MBean operation: setScanPeriod

MBean

Rhino operation

public void setScanPeriod(int scanPeriod)
    throws ConfigurationException, ValidationException;

The scan period is measured in milliseconds.

Console command: getthresholdrulescanperiod

Command

getthresholdrulescanperiod
  Description
    Get the threshold alarm rule scan period

Example

$ ./rhino-console  getthresholdrulescanperiod
Threshold rule scan period set to 30000ms

MBean operation: getScanPeriod

MBean

Rhino operation

public int getScanPeriod()
  throws ConfigurationException;

The scan period is measured in milliseconds.

Runtime Alarm List

To list all alarms that may be raised by Rhino and installed components (including their messages, and when raised and cleared), use the following rhino-console command.

Console command: alarmcatalog

Command

alarmcatalog [-v]
  Description
    List the alarms that may be raised by Rhino and installed components. Using the
    -v flag will display more detail.

Example

$ ./rhino-console alarmcatalog

  Rhino Alarms
  ============

    Source                 Category                  Level     Alarm Type and Message
    ------                 --------                  -----     ----------------------
    Abnormal Execution     AbnormalExecution         WARNING   rhino.uncaught-exception  "Uncaught exception thrown by thread %s: %s"
    Activity Handler       Activity Handler          WARNING   rhino.ah.snapshot-age  "Oldest activity handler snapshot is older than %s, snapshot is %s (from %d), creating thread: %s"
    Cluster State          Clustering                MAJOR     rhino.node-failure  "Node %d has left the cluster"

... edited for brevity ...

And this displays more detail:

$ ./rhino-console alarmcatalog -v
Rhino Alarms
============

Source: Abnormal Execution

  Category: AbnormalExecution (Alarms raised as a result of an abnormal execution condition being detected)

    Alarm Type:  rhino.uncaught-exception
    Level:       WARNING
    Message:     "Uncaught exception thrown by thread %s: %s"
    Description: An uncaught exception has been detected.
    Raised:      When an uncaught exception has been thrown.
    Cleared:     Never, must be cleared manually or Rhino restarted with the source of the uncaught exception corrected.


Source: Activity Handler

  Category: Activity Handler (Alarms raised by Rhino activity handler)

    Alarm Type:  rhino.ah.snapshot-age
    Level:       WARNING
    Message:     "Oldest activity handler snapshot is older than %s, snapshot is %s (from %d), creating thread: %s"
    Description: The oldest activity handler snapshot is too old.
    Raised:      When the age of the oldest activity handler snapshot is greater than the threshold set by the rhino.ah.snapshot_age_warn system property (30s default).
    Cleared:     When the age of the oldest snapshot is less than or equal to the threshold.


Source: Cluster State

  Category: Clustering (Alarms raised by Rhino cluster state changes)

    Alarm Type:  rhino.node-failure
    Level:       MAJOR
    Message:     "Node %d has left the cluster"
    Description: A node left the cluster for some reason other than a management-initiated shutdown.
    Raised:      When the cluster state listener detects a node has left the cluster unexpectedly.
    Cleared:     When the failed node returns to the cluster.

... edited for brevity ...

Rhino Alarm List

This is a list of all alarms raised by this version of Rhino. For the management command that lists all alarms that may be raised by Rhino and installed components see Runtime Alarm List.

Alarm Type Description

Category: AbnormalExecution (Alarms raised as a result of an abnormal execution condition being detected)

rhino.uncaught-exception

An uncaught exception has been detected.

Category: Activity Handler (Alarms raised by Rhino activity handler)

rhino.ah.snapshot-age

The oldest activity handler snapshot is too old.

Category: Cluster Clock Synchronisation (Alarms raised by the cluster clock synchronisation monitor)

rhino.monitoring.clocksync

Another cluster node is reporting a system clock deviation relative to the local node beyond the maximum permitted threshold. The status of external processes maintaining the system clock on that node (eg. NTP) should be checked.

Category: Clustering (Alarms raised by Rhino cluster state changes)

rhino.node-failure

A node left the cluster for some reason other than a management-initiated shutdown.

Category: Configuration Management (Alarms raised by the Rhino configuration manager)

rhino.config.save-error

An error occurred while trying to write the file-based configuration for the configuration type specified in the alarm instance.

rhino.config.read-error

An error occurred while trying to read the file-based configuration for the configuration type specified in the alarm instance. Rhino will use defaults from defaults.xml, move the broken configuration aside, and overwrite the config file.

rhino.config.activation-failure

An error occurred while trying to activate the file-based configuration for the configuration type specified in the alarm instance. Rhino will use defaults from defaults.xml, move the broken configuration aside, and overwrite the config file.

Category: Database (Alarms raised during database communications)

rhino.database.no-persistence-config

A persistence resource configuration referenced in rhino-config.xml has been removed at runtime.

rhino.database.no-persistence-instances

A persistence resource configuration referenced in rhino-config.xml has no persistence instances configured, or no configured persistence instances could be instantiated.

rhino.database.persistence-instance-instantiation-failure

Rhino requires a backing database for persistence of state for failure recovery purposes. A persistent instance defines a connection to a database backend. If the persistent instance cannot be instantiated then that connection cannot be made and state cannot be persisted to that instance.

rhino.database.connection-lost

Rhino requires a backing database for persistence of state for failure recovery purposes. If no connection to the database backend is available, state cannot be persisted.

rhino.jdbc.persistence-instance-instantiation-failure

A persistent instance defines the connection to the database backend. If the persistent instance cannot be instantiated then JDBC connections cannot be made.

Category: Event Router State (Alarms raised by event router state management)

rhino.state.unlicensed-service

A licensing problem was detected during service activation at startup.

rhino.state.unlicensed-raentity

A licensing problem was detected during resource adaptor entity activation.

Category: GroupRMI (Alarms raised by the GroupRMI server)

rhino.group-rmi.dangling-transaction

A group RMI invocation completed without committing or rolling back a transaction that it started. The dangling transaction will be automatically rolled back by the group RMI server to prevent future issues but these occurrences are software bugs that should be reported.

Category: Key/Value Store (Alarms raised by key/value store persistence resource managers)

rhino.kv-store.no-persistence-config

A persistence resource configuration referenced in rhino-config.xml has been removed at runtime.

rhino.kv-store.no-persistence-instances

A persistence resource configuration referenced in rhino-config.xml has no persistence instances configured, or no configured persistence instances could be instantiated.

rhino.kv-store.persistence-instance-instantiation-failure

A persistence instance used by a key/value store cannot be instantiated. If the persistent instance cannot be instantiated then that connection cannot be made and state cannot be persisted to that instance.

Category: Licensing (Alarms raised by Rhino licensing)

rhino.license.over-limit

Rate limiter throttling is active. This throttling and hence this alarm only happens in SDK versions of Rhino, not production versions.

rhino.license.expired

A license installed in Rhino has passed its expiry time.

rhino.license.pending-expiry

A license installed in Rhino is within seven days of its expiry time.

rhino.license.partially-licensed-host

The hardware addresses listed in a host-based license only partially match those on the host.

rhino.license.unlicensed-host

The hardware addresses listed in a host-based license do not match those on the host.

rhino.license.unlicensed-rhino

Rhino does not have a valid license installed.

rhino.license.over-licensed-capacity

The work done by a function exceeds licensed capacity.

rhino.license.unlicensed-function

A particular function is not licensed.

Category: Limiting (Alarms raised by Rhino limiting)

rhino.limiting.below-negative-capacity

A rate limiter is below negative capacity.

Category: Logging (Alarms raised by Rhino logging)

rhino.logging.appender-error

An appender has thrown an exception when attempting to pass log messages from a logger to it.

Category: M-lets Startup (Alarms raised by the M-let starter)

rhino.mlet.loader-failure

The M-Let starter component could not register itself with the platform MBean server. This normally indicates a serious JVM misconfiguration.

rhino.mlet.registration-failure

The M-Let starter component could not register an MBean for a configured m-let. This normally indicates an error in the m-let configuration file.

Category: REM Startup (Alarms raised by embedded REM starter)

rhino.rem.missing

This version of Rhino is supposed to contain an embedded instance of REM but it was not found, most likely due to a packaging error.

rhino.rem.startup

There was an unexpected problem while starting the embedded REM. This could be because of a port conflict or packaging problem.

rhino.rem.insufficient-java-version

Rhino Element Manager requires Java 1.8, but Rhino was started using Java 1.7

Category: Remote Timer Server (Alarms raised by the remote timer server)

rhino.remote-timer-server.bind-error

The remote timer server is unable to bind a socket listener within the configured range of ports. The Rhino configuration may need to be checked and an alternate or wider range of ports allowed.

Category: Runtime Environment (Alarms related to the runtime environment)

rhino.runtime.unsupported.jvm

This JVM is not a Sun/Oracle JVM. The Rhino SDK will raise this alarm but a Rhino Production instance will refuse to start.

rhino.runtime.unsupported.javamajorversion

This Java version is not a supported major version. The Rhino SDK will raise this alarm but a Rhino Production instance will refuse to start.

rhino.runtime.unsupported.javaupdateversion

This Java version is older than the minimum recommended update. A Rhino instance will start, but will always raise this alarm.

rhino.runtime.slee

SLEE event-routing functions failed to start after node restart

rhino.runtime.long-filenames-unsupported

Filenames with the maximum length expected by Rhino are unsupported on this filesystem. Unexpected deployment errors may occur as a result

Category: SAS facility (Alarms raised by Rhino SAS Facility)

rhino.sas.connection.lost

Attempting to reconect to SAS server

rhino.sas.queue.full

SAS message queue is full. Some events have not been reported to SAS

Category: SNMP (Alarms raised by Rhino SNMP)

rhino.snmp.no-bind-addresses

The SNMP agent listens for requests received on all network interfaces that match the requested SNMP configuration. If no suitable interfaces can be found that match the requested configuration, then the SNMP agent cannot process any SNMP requests.

rhino.snmp.bind-failure

The SNMP agent attempts to bind a UDP port on each configured SNMP interface to receive requests. If no ports could be bound, the SNMP agent cannot process any SNMP requests.

rhino.snmp.partial-failure

The SNMP agent attempts to bind a UDP port on each configured SNMP interface to receive requests. If this succeeds on some (but not all) interfaces, the SNMP agent can only process requests received via the interfaces that succeeded.

rhino.snmp.general-failure

This is a catchall alarm for unexpected failures during agent startup. If an unexpected failure occurs, the state of the SNMP agent is unpredictable and requests may not be successfully processed.

rhino.snmp.notification-address-failure

This alarm represents a failure to determine an address from the notification target configuration. This can occur if the notification hostname is not resolvable, or if the specified hostname is not parseable.

rhino.snmp.duplicate-oid-mapping

Multiple parameter set type configurations for in-use parameter set types map to the same OID. All parameter set type mappings will remain inactive until the conflict is resolved.

rhino.snmp.duplicate-counter-mapping

Multiple counters in the parameter set type configuration map to the same index. The parameter set type mappings will remain inactive until the conflict is resolved.

Category: Scattercast Management (Alarms raised by Rhino scattercast management operations)

rhino.scattercast.update-reboot-required

Reboot needed to make scattercast update active.

Category: Service State (Alarms raised by service state management)

rhino.state.service-activation

The service threw an exception during service activation at startup.

Category: Session Ownership Store (Alarms raised by session ownership store persistence resource managers)

rhino.session-ownership-store.no-persistence-config

The persistence resource configuration referenced in rhino-config.xml has been removed at runtime.

rhino.session-ownership-store.no-persistence-instances

The persistence resource configuration referenced in rhino-config.xml has no persistence instances configured, or no configured persistence instances could be instantiated.

rhino.session-ownership-store.persistence-instance-instantiation-failure

A persistence instance used by the session ownership store cannot be instantiated. If the persistent instance cannot be instantiated then that connection cannot be made and state cannot be persisted to that instance.

Category: Threshold Rules (Alarms raised by the threshold alarm rule processor)

rhino.threshold-rules.rule-failure

A threshold rule trigger or reset rule failed.

rhino.threshold-rules.unknown-parameter-set

A threshold rule trigger or reset rule refers to an unknown statistics parameter set.

Category: Watchdog (Alarms raised by the watchdog)

rhino.watchdog.no-exit

The system property watchdog.no_exit is set, enabling override of default node termination behaviour on failed watchdog conditions. This can cause catastrophic results and should never be used.

rhino.watchdog.forward-timewarp

A forward timewarp was detected.

rhino.watchdog.reverse-timewarp

A reverse timewarp was detected.


Category: AbnormalExecution

Alarms raised as a result of an abnormal execution condition being detected

rhino.uncaught-exception

Alarm Type

rhino.uncaught-exception

Level

WARNING

Message

Uncaught exception thrown by thread %s: %s

Description

An uncaught exception has been detected.

Raised

When an uncaught exception has been thrown.

Cleared

Never, must be cleared manually or Rhino restarted with the source of the uncaught exception corrected.


Category: Activity Handler

Alarms raised by Rhino activity handler

rhino.ah.snapshot-age

Alarm Type

rhino.ah.snapshot-age

Level

WARNING

Message

Oldest activity handler snapshot is older than %s, snapshot is %s (from %d), creating thread: %s

Description

The oldest activity handler snapshot is too old.

Raised

When the age of the oldest activity handler snapshot is greater than the threshold set by the rhino.ah.snapshot_age_warn system property (30s default).

Cleared

When the age of the oldest snapshot is less than or equal to the threshold.


Category: Cluster Clock Synchronisation

Alarms raised by the cluster clock synchronisation monitor

rhino.monitoring.clocksync

Alarm Type

rhino.monitoring.clocksync

Level

WARNING

Message

Node %d is reporting a local clock time deviation beyond the maximum expected threshold of %dms

Description

Another cluster node is reporting a system clock deviation relative to the local node beyond the maximum permitted threshold. The status of external processes maintaining the system clock on that node (eg. NTP) should be checked.

Raised

When a cluster node reports a local clock time deviation relative to the local node beyond the maximum permitted threshold.

Cleared

When the clock deviation returns to a value at or below the threshold.


Category: Clustering

Alarms raised by Rhino cluster state changes

rhino.node-failure

Alarm Type

rhino.node-failure

Level

MAJOR

Message

Node %d has left the cluster

Description

A node left the cluster for some reason other than a management-initiated shutdown.

Raised

When the cluster state listener detects a node has left the cluster unexpectedly.

Cleared

When the failed node returns to the cluster.


Category: Configuration Management

Alarms raised by the Rhino configuration manager

rhino.config.activation-failure

Alarm Type

rhino.config.activation-failure

Level

MAJOR

Message

Error activating configuration from file %s. Configuration was replaced with defaults and old configuration file was moved to %s.

Description

An error occurred while trying to activate the file-based configuration for the configuration type specified in the alarm instance. Rhino will use defaults from defaults.xml, move the broken configuration aside, and overwrite the config file.

Raised

When an exception occurs while activating a file-based configuration.

Cleared

Never, must be cleared manually.

rhino.config.read-error

Alarm Type

rhino.config.read-error

Level

MAJOR

Message

Error reading configuration from file %s. Configuration was replaced with defaults and old configuration file was moved to %s.

Description

An error occurred while trying to read the file-based configuration for the configuration type specified in the alarm instance. Rhino will use defaults from defaults.xml, move the broken configuration aside, and overwrite the config file.

Raised

When an exception occurs while reading a configuration file.

Cleared

Never, must be cleared manually.

rhino.config.save-error

Alarm Type

rhino.config.save-error

Level

MAJOR

Message

Error saving file based configuration: %s

Description

An error occurred while trying to write the file-based configuration for the configuration type specified in the alarm instance.

Raised

When an exception occurs while writing to a configuration file.

Cleared

Never, must be cleared manually.


Category: Database

Alarms raised during database communications

rhino.database.connection-lost

Alarm Type

rhino.database.connection-lost

Level

MAJOR

Message

Connection to %s database failed: %s

Description

Rhino requires a backing database for persistence of state for failure recovery purposes. If no connection to the database backend is available, state cannot be persisted.

Raised

When the connection to a database backend is lost.

Cleared

When the connection is restored.

rhino.database.no-persistence-config

Alarm Type

rhino.database.no-persistence-config

Level

CRITICAL

Message

Persistence resource config for %s has been removed

Description

A persistence resource configuration referenced in rhino-config.xml has been removed at runtime.

Raised

When an in-use persistence resource configuration is removed by a configuration update.

Cleared

When the persistence resource configuration is restored.

rhino.database.no-persistence-instances

Alarm Type

rhino.database.no-persistence-instances

Level

CRITICAL

Message

Persistence resource config for %s has no active persistence instances

Description

A persistence resource configuration referenced in rhino-config.xml has no persistence instances configured, or no configured persistence instances could be instantiated.

Raised

When an in-use persistence resource configuration has no active persistence instances.

Cleared

When at least one active persistence instance exists for the persistence resource configuration.

rhino.database.persistence-instance-instantiation-failure

Alarm Type

rhino.database.persistence-instance-instantiation-failure

Level

MAJOR

Message

Unable to instantiate persistence instance %s for database %s

Description

Rhino requires a backing database for persistence of state for failure recovery purposes. A persistent instance defines a connection to a database backend. If the persistent instance cannot be instantiated then that connection cannot be made and state cannot be persisted to that instance.

Raised

When a persistent instance configuration change occurs but instantiation of that persistent instance fails.

Cleared

When a correct configuration is installed.

rhino.jdbc.persistence-instance-instantiation-failure

Alarm Type

rhino.jdbc.persistence-instance-instantiation-failure

Level

MAJOR

Message

Unable to instantiate persistence instance %s for JDBC configuration with JNDI name %s

Description

A persistent instance defines the connection to the database backend. If the persistent instance cannot be instantiated then JDBC connections cannot be made.

Raised

When a persistent instance configuration change occurs but instantiation of that persistent instance fails.

Cleared

When a correct configuration is installed.


Category: Event Router State

Alarms raised by event router state management

rhino.state.unlicensed-raentity

Alarm Type

rhino.state.unlicensed-raentity

Level

MAJOR

Message

No valid license for resource adaptor entity "%s" found. The resource adaptor entity has not been activated.

Description

A licensing problem was detected during resource adaptor entity activation.

Raised

During Rhino startup if a resource adaptor entity is configured to be in the active state but there is no valid license for it.

Cleared

Never, must be cleared manually.

rhino.state.unlicensed-service

Alarm Type

rhino.state.unlicensed-service

Level

MAJOR

Message

No valid license for service "%s" found. The service has not been activated.

Description

A licensing problem was detected during service activation at startup.

Raised

During Rhino startup if an service is configured to be in the active state but there is no valid license for it.

Cleared

Never, must be cleared manually.


Category: GroupRMI

Alarms raised by the GroupRMI server

rhino.group-rmi.dangling-transaction

Alarm Type

rhino.group-rmi.dangling-transaction

Level

WARNING

Message

Group RMI invocation %s completed leaving an active transaction dangling: %s. Please report this bug to Metaswitch support.

Description

A group RMI invocation completed without committing or rolling back a transaction that it started. The dangling transaction will be automatically rolled back by the group RMI server to prevent future issues but these occurrences are software bugs that should be reported.

Raised

When a group RMI invocation completes leaving an active transaction dangling.

Cleared

Never, must be cleared manually.


Category: Key/Value Store

Alarms raised by key/value store persistence resource managers

rhino.kv-store.no-persistence-config

Alarm Type

rhino.kv-store.no-persistence-config

Level

CRITICAL

Message

Persistence resource config for %s has been removed

Description

A persistence resource configuration referenced in rhino-config.xml has been removed at runtime.

Raised

When an in-use persistence resource configuration is removed by a configuration update.

Cleared

When the persistence resource configuration is restored.

rhino.kv-store.no-persistence-instances

Alarm Type

rhino.kv-store.no-persistence-instances

Level

CRITICAL

Message

Persistence resource config for %s has no active persistence instances

Description

A persistence resource configuration referenced in rhino-config.xml has no persistence instances configured, or no configured persistence instances could be instantiated.

Raised

When an in-use persistence resource configuration has no active persistence instances.

Cleared

When at least one active persistence instance exists for the persistence resource configuration.

rhino.kv-store.persistence-instance-instantiation-failure

Alarm Type

rhino.kv-store.persistence-instance-instantiation-failure

Level

MAJOR

Message

Unable to instantiate persistence instance %s for key/value store %s

Description

A persistence instance used by a key/value store cannot be instantiated. If the persistent instance cannot be instantiated then that connection cannot be made and state cannot be persisted to that instance.

Raised

When a persistent instance configuration change occurs but instantiation of that persistent instance fails.

Cleared

When a correct configuration is installed.


Category: Licensing

Alarms raised by Rhino licensing

rhino.license.expired

Alarm Type

rhino.license.expired

Level

MAJOR

Message

License with serial "%s" has expired

Description

A license installed in Rhino has passed its expiry time.

Raised

When a license expires and there is no superseding license installed.

Cleared

When the license is removed or a superseding license is installed.

rhino.license.over-licensed-capacity

Alarm Type

rhino.license.over-licensed-capacity

Level

MAJOR

Message

Over licensed capacity for function "%s".

Description

The work done by a function exceeds licensed capacity.

Raised

When the amount of work processed by the named function exceeds the licensed capacity.

Cleared

When the amount of work processed by the function becomes less than or equal to the licensed capacity.

rhino.license.over-limit

Alarm Type

rhino.license.over-limit

Level

MAJOR

Message

Rate limiter throttling active, throttled to %d events/second

Description

Rate limiter throttling is active. This throttling and hence this alarm only happens in SDK versions of Rhino, not production versions.

Raised

When there is more incoming work than allowed by the licensed limit so Rhino starts rejecting some.

Cleared

When the total input rate (both accepted and rejected work) drops below the licensed limit.

rhino.license.partially-licensed-host

Alarm Type

rhino.license.partially-licensed-host

Level

MINOR

Message

Host "%s" is not fully licensed. Not all hardware addresses on this host match those licensed. Please request a new license for host "%s".

Description

The hardware addresses listed in a host-based license only partially match those on the host.

Raised

When a host-based license with invalid host addresses is installed.

Cleared

When the license is removed, or a superseding license is installed.

rhino.license.pending-expiry

Alarm Type

rhino.license.pending-expiry

Level

MAJOR

Message

License with serial "%s" is due to expire on %s

Description

A license installed in Rhino is within seven days of its expiry time.

Raised

Seven days before a license will expire and there is no superseding license installed.

Cleared

When the license expires, the license is removed, or a superseding license is installed.

rhino.license.unlicensed-function

Alarm Type

rhino.license.unlicensed-function

Level

MAJOR

Message

There are no valid licenses installed for function "%s" and version "%s".

Description

A particular function is not licensed.

Raised

When a unit of an unlicensed function is requested.

Cleared

When a license is installed that licenses a particular function, and another unit is requested.

rhino.license.unlicensed-host

Alarm Type

rhino.license.unlicensed-host

Level

MINOR

Message

"%s" is not licensed. Hardware addresses on this host did not match those licensed, or hostname has changed. Please request a new license for host "%s".

Description

The hardware addresses listed in a host-based license do not match those on the host.

Raised

When a host-based license with invalid host addresses is installed.

Cleared

When the license is removed, or a superseding license is installed.

rhino.license.unlicensed-rhino

Alarm Type

rhino.license.unlicensed-rhino

Level

MAJOR

Message

Rhino platform is no longer licensed

Description

Rhino does not have a valid license installed.

Raised

When a license expires or is removed leaving Rhino in an unlicensed state.

Cleared

When an appropriate license is installed.


Category: Limiting

Alarms raised by Rhino limiting

rhino.limiting.below-negative-capacity

Alarm Type

rhino.limiting.below-negative-capacity

Level

WARNING

Message

Token count in rate limiter "%s" capped at negative saturation point on node %d. Too much work has been forced. Alarm will clear once token count >= 0.

Description

A rate limiter is below negative capacity.

Raised

By a rate limiter when a very large number of units have been forcibly used and the internal token counter has reached the biggest possible negative number (-2,147,483,648).

Cleared

When the token count becomes greater than or equal to zero.


Category: Logging

Alarms raised by Rhino logging

rhino.logging.appender-error

Alarm Type

rhino.logging.appender-error

Level

MAJOR

Message

An error occurred logging to an appender: %s

Description

An appender has thrown an exception when attempting to pass log messages from a logger to it.

Raised

When an appender throws an AppenderLoggingException when a logger tries to log to it.

Cleared

When the problem with the given appender has been resolved and the logging configuration is updated.


Category: M-lets Startup

Alarms raised by the M-let starter

rhino.mlet.loader-failure

Alarm Type

rhino.mlet.loader-failure

Level

MAJOR

Message

Error registering MLetLoader MBean

Description

The M-Let starter component could not register itself with the platform MBean server. This normally indicates a serious JVM misconfiguration.

Raised

During Rhino startup if an error occurred registering the m-let loader component with the MBean server.

Cleared

Never, must be cleared manually or Rhino restarted.

rhino.mlet.registration-failure

Alarm Type

rhino.mlet.registration-failure

Level

MINOR

Message

Could not create or register MLet: %s

Description

The M-Let starter component could not register an MBean for a configured m-let. This normally indicates an error in the m-let configuration file.

Raised

During Rhino startup if an error occurred starting a m-let configured.

Cleared

Never, must be cleared manually or Rhino restarted with updated configuration.


Category: REM Startup

Alarms raised by embedded REM starter

rhino.rem.insufficient-java-version

Alarm Type

rhino.rem.insufficient-java-version

Level

MINOR

Message

This Java version (%s) is insufficient for starting the embedded Rhino Element Manager. REM requires Java 1.8.

Description

Rhino Element Manager requires Java 1.8, but Rhino was started using Java 1.7

Raised

During Rhino startup if running on Java 1.7 and embedded REM is enabled.

Cleared

Never, must be cleared manually, Rhino restarted using Java 1.8, or embedded REM disabled.

rhino.rem.missing

Alarm Type

rhino.rem.missing

Level

MINOR

Message

Rhino Element Manager classes not found, embedded REM is disabled.

Description

This version of Rhino is supposed to contain an embedded instance of REM but it was not found, most likely due to a packaging error.

Raised

During Rhino startup if the classes could not be found to start the embedded REM.

Cleared

Never, must be cleared manually.

rhino.rem.startup

Alarm Type

rhino.rem.startup

Level

MINOR

Message

Could not start embedded Rhino Element Manager

Description

There was an unexpected problem while starting the embedded REM. This could be because of a port conflict or packaging problem.

Raised

During Rhino startup if an error occurred starting the embedded REM.

Cleared

Never, must be cleared manually or Rhino restarted with updated configuration.


Category: Remote Timer Server

Alarms raised by the remote timer server

rhino.remote-timer-server.bind-error

Alarm Type

rhino.remote-timer-server.bind-error

Level

CRITICAL

Message

Unable to bind remote timer server to %s %s

Description

The remote timer server is unable to bind a socket listener within the configured range of ports. The Rhino configuration may need to be checked and an alternate or wider range of ports allowed.

Raised

If the remote timer server cannot bind a socket listener within the configured range of ports.

Cleared

Never, must be cleared manually.


Category: Runtime Environment

Alarms related to the runtime environment

rhino.runtime.long-filenames-unsupported

Alarm Type

rhino.runtime.long-filenames-unsupported

Level

WARNING

Message

Filenames with a length of %s characters are unsupported on this filesystem. Unexpected deployment errors may occur as a result

Description

Filenames with the maximum length expected by Rhino are unsupported on this filesystem. Unexpected deployment errors may occur as a result

Raised

During Rhino startup if the long filename check fails.

Cleared

Never, must be cleared manually or Rhino restarted after being installed on a filesystem supporting long filenames.

rhino.runtime.slee

Alarm Type

rhino.runtime.slee

Level

CRITICAL

Message

SLEE event-routing functions failed to start after node restart

Description

SLEE event-routing functions failed to start after node restart

Raised

During Rhino startup if SLEE event-routing functions fail to restart.

Cleared

Never, must be cleared manually or the node restarted.

rhino.runtime.unsupported.javamajorversion

Alarm Type

rhino.runtime.unsupported.javamajorversion

Level

WARNING

Message

This Java version (%s) is not supported for Rhino production instances. Supported versions are: %s

Description

This Java version is not a supported major version. The Rhino SDK will raise this alarm but a Rhino Production instance will refuse to start.

Raised

During Rhino SDK startup if an unsupported JVM was detected.

Cleared

Never, must be cleared manually or Rhino restarted with a supported Java version.

rhino.runtime.unsupported.javaupdateversion

Alarm Type

rhino.runtime.unsupported.javaupdateversion

Level

MINOR

Message

This Java version (%s) is older than the minimum recommended update (%s)

Description

This Java version is older than the minimum recommended update. A Rhino instance will start, but will always raise this alarm.

Raised

During Rhino startup if an old Java version was detected.

Cleared

Never, must be cleared manually or Rhino restarted with a supported Java version.

rhino.runtime.unsupported.jvm

Alarm Type

rhino.runtime.unsupported.jvm

Level

WARNING

Message

This JVM (%s) is not supported for Rhino production instances. Supported JVMs are: %s

Description

This JVM is not a Sun/Oracle JVM. The Rhino SDK will raise this alarm but a Rhino Production instance will refuse to start.

Raised

During Rhino SDK startup if an unsupported JVM was detected.

Cleared

Never, must be cleared manually or Rhino restarted with a supported JVM.


Category: SAS facility

Alarms raised by Rhino SAS Facility

rhino.sas.connection.lost

Alarm Type

rhino.sas.connection.lost

Level

MAJOR

Message

Connection to SAS server at %s:%d is down

Description

Attempting to reconect to SAS server

Raised

When SAS client loses connection to server

Cleared

On reconnect

rhino.sas.queue.full

Alarm Type

rhino.sas.queue.full

Level

WARNING

Message

SAS message queue is full

Description

SAS message queue is full. Some events have not been reported to SAS

Raised

When SAS facility outgoing message queue is full

Cleared

When the queue is not full for at least sas.queue_full_interval


Category: SNMP

Alarms raised by Rhino SNMP

rhino.snmp.bind-failure

Alarm Type

rhino.snmp.bind-failure

Level

MAJOR

Message

The SNMP agent could not be started on node %d: no addresses were successfully bound.

Description

The SNMP agent attempts to bind a UDP port on each configured SNMP interface to receive requests. If no ports could be bound, the SNMP agent cannot process any SNMP requests.

Raised

When the SNMP Agent attempts to start listening for requests, but no port in the configured range on any configured interface could be used.

Cleared

When the SNMP Agent is stopped.

rhino.snmp.duplicate-counter-mapping

Alarm Type

rhino.snmp.duplicate-counter-mapping

Level

WARNING

Message

Duplicate counter mappings in parameter set type %s

Description

Multiple counters in the parameter set type configuration map to the same index. The parameter set type mappings will remain inactive until the conflict is resolved.

Raised

When a in-use parameter set type has a configuration with duplicate counter mappings.

Cleared

When the conflict is resolved, either by changing the relevant counter mappings, or if the parameter set type is removed from use.

rhino.snmp.duplicate-oid-mapping

Alarm Type

rhino.snmp.duplicate-oid-mapping

Level

WARNING

Message

Duplicate parameter set type mapping configurations for OID %s

Description

Multiple parameter set type configurations for in-use parameter set types map to the same OID. All parameter set type mappings will remain inactive until the conflict is resolved.

Raised

When multiple in-use parameter set types have a configuration that map to the same OID.

Cleared

When the conflict is resolved, either by changing the OID mappings in the relevant parameter set type configurations, or if a parameter set type in conflict is removed from use.

rhino.snmp.general-failure

Alarm Type

rhino.snmp.general-failure

Level

MINOR

Message

The SNMP agent encountered an error during startup: %s

Description

This is a catchall alarm for unexpected failures during agent startup. If an unexpected failure occurs, the state of the SNMP agent is unpredictable and requests may not be successfully processed.

Raised

When the SNMP Agent attempts to start listening for requests, but there is an unexpected failure not covered by other alarms.

Cleared

When the SNMP Agent is stopped.

rhino.snmp.no-bind-addresses

Alarm Type

rhino.snmp.no-bind-addresses

Level

MAJOR

Message

The SNMP agent could not be started on node %d: no suitable bind addresses available.

Description

The SNMP agent listens for requests received on all network interfaces that match the requested SNMP configuration. If no suitable interfaces can be found that match the requested configuration, then the SNMP agent cannot process any SNMP requests.

Raised

When the SNMP Agent attempts to start listening for requests, but no suitable network interface addresses can be found to bind to.

Cleared

When the SNMP Agent is stopped.

rhino.snmp.notification-address-failure

Alarm Type

rhino.snmp.notification-address-failure

Level

MAJOR

Message

Failed to create notification target for address "%s".

Description

This alarm represents a failure to determine an address from the notification target configuration. This can occur if the notification hostname is not resolvable, or if the specified hostname is not parseable.

Raised

During SNMP agent start if a notification target address cannot be determined (e.g. due to a hostname resolution failing).

Cleared

When the SNMP Agent is stopped.

rhino.snmp.partial-failure

Alarm Type

rhino.snmp.partial-failure

Level

MINOR

Message

The SNMP agent failed to bind to the following addresses: %s

Description

The SNMP agent attempts to bind a UDP port on each configured SNMP interface to receive requests. If this succeeds on some (but not all) interfaces, the SNMP agent can only process requests received via the interfaces that succeeded.

Raised

When the SNMP Agent attempts to start listening for requests, and only some of the configured interfaces successfully bound a UDP port.

Cleared

When the SNMP Agent is stopped.


Category: Scattercast Management

Alarms raised by Rhino scattercast management operations

rhino.scattercast.update-reboot-required

Alarm Type

rhino.scattercast.update-reboot-required

Level

CRITICAL

Message

Scattercast endpoints have been updated. A cluster reboot is required to apply the update. An automatic reboot has been triggered, Manual intervention required if the reboot fails.

Description

Reboot needed to make scattercast update active.

Raised

When scattercast endpoints are updated.

Cleared

On node reboot.


Category: Service State

Alarms raised by service state management

rhino.state.service-activation

Alarm Type

rhino.state.service-activation

Level

MAJOR

Message

Service "%s" failed to reactivate successfully.

Description

The service threw an exception during service activation at startup.

Raised

During Rhino startup if a service is configured to be in the active state but throws an exception while handling the activation request.

Cleared

If the service is manually reactivated successfully, or uninstalled.


Category: Session Ownership Store

Alarms raised by session ownership store persistence resource managers

rhino.session-ownership-store.no-persistence-config

Alarm Type

rhino.session-ownership-store.no-persistence-config

Level

CRITICAL

Message

Persistence resource config has been removed

Description

The persistence resource configuration referenced in rhino-config.xml has been removed at runtime.

Raised

When an in-use persistence resource configuration is removed by a configuration update.

Cleared

When the persistence resource configuration is restored.

rhino.session-ownership-store.no-persistence-instances

Alarm Type

rhino.session-ownership-store.no-persistence-instances

Level

CRITICAL

Message

Persistence resource config has no active persistence instances

Description

The persistence resource configuration referenced in rhino-config.xml has no persistence instances configured, or no configured persistence instances could be instantiated.

Raised

When an in-use persistence resource configuration has no active persistence instances.

Cleared

When at least one active persistence instance exists for the persistence resource configuration.

rhino.session-ownership-store.persistence-instance-instantiation-failure

Alarm Type

rhino.session-ownership-store.persistence-instance-instantiation-failure

Level

MAJOR

Message

Unable to instantiate persistence instance %s

Description

A persistence instance used by the session ownership store cannot be instantiated. If the persistent instance cannot be instantiated then that connection cannot be made and state cannot be persisted to that instance.

Raised

When a persistent instance configuration change occurs but instantiation of that persistent instance fails.

Cleared

When a correct configuration is installed.


Category: Threshold Rules

Alarms raised by the threshold alarm rule processor

rhino.threshold-rules.rule-failure

Alarm Type

rhino.threshold-rules.rule-failure

Level

WARNING

Message

Threshold rule %s trigger or reset condition failed to run

Description

A threshold rule trigger or reset rule failed.

Raised

When a threshold rule condition cannot be evaluated, for example it refers to a statistic that does not exist.

Cleared

When the threshold rule condition is corrected.

rhino.threshold-rules.unknown-parameter-set

Alarm Type

rhino.threshold-rules.unknown-parameter-set

Level

WARNING

Message

Threshold rule %s refers to unknown statistics parameter set '%s'

Description

A threshold rule trigger or reset rule refers to an unknown statistics parameter set.

Raised

When a threshold rule condition cannot be evaluated because it refers to a statistics parameter set that does not exist.

Cleared

When the threshold rule condition is corrected.


Category: Watchdog

Alarms raised by the watchdog

rhino.watchdog.forward-timewarp

Alarm Type

rhino.watchdog.forward-timewarp

Level

WARNING

Message

Forward timewarp of %sms detected at %s

Description

A forward timewarp was detected.

Raised

When the system clock is detected to have progressed by an amount exceeding the sum of the watchdog check interval and the maximum pause margin.

Cleared

Never, must be cleared manually.

rhino.watchdog.no-exit

Alarm Type

rhino.watchdog.no-exit

Level

CRITICAL

Message

System property watchdog.no_exit is set, watchdog will be terminated rather than killing the node if a failed watchdog condition occurs

Description

The system property watchdog.no_exit is set, enabling override of default node termination behaviour on failed watchdog conditions. This can cause catastrophic results and should never be used.

Raised

When the watchdog.no_exit system property is set.

Cleared

Never, must be cleared manually.

rhino.watchdog.reverse-timewarp

Alarm Type

rhino.watchdog.reverse-timewarp

Level

WARNING

Message

Reverse timewarp of %sms detected at %s

Description

A reverse timewarp was detected.

Raised

When the system clock is detected to have progressed by an amount less than the difference between the watchdog check interval and the reverse timewarp margin.

Cleared

Never, must be cleared manually.

Usage

As well as an overview of usage, this section includes instructions for performing the following Rhino SLEE procedures, with explanations, examples and links to related javadocs:

Procedure rhino-console command MBean → Operations
dumpusagestats
Usage → get<usage-parameter-name>
setusagenotificationsenabled
UsageNotificationManager →
set<usage-parameter-name>
NotificationsEnabled
listusagenotificationsenabled
UsageNotificationManager →
get<usage-parameter-name>
NotificationsEnabled
createusageparameterset
ServiceUsage → createUsageParameterSet
ProfileTableUsage → createUsageParameterSet
ResourceUsage → createUsageParameterSet
listusageparametersets
ServiceUsage → getUsageParameterSets
ProfileTableUsage → getUsageParameterSets
ResourceUsage → getUsageParameterSets
removeusageparameterset
ServiceUsage → removeUsageParameterSet
ProfileTableUsage → removeUsageParameterSet
ResourceUsage → removeUsageParameterSet

About Usage

A usage parameter is a parameter that an object in the SLEE can update, to provide usage information.

There are two types:

  • Counter-type usage parameters have values that can be incremented or decremented.

  • Sample-type usage parameters accumulate sample data.

Accessing usage parameters

Administrators can access usage parameters through the SLEE’s management interface.

Management clients can access usage parameters through the usage parameters interface declared in an SBB, resource adaptor or profile specification. Usage parameters cannot be created through the management interface. Instead, a usage parameters interface must be declared in the SLEE component. For example, an SBB declares an sbb-usage-parameters-interface element in the SBB deployment descriptor (similar procedures apply for resource adaptors and profile specifications).

You can also use notifications to output usage parameters to management clients.

Creating named usage parameter sets

By default, the SLEE creates unnamed usage parameter sets for a notification source. You can also create named usage parameter sets, for example to hold multiple values of usage parameters for the same notification source.

Rhino usage extensions

To alleviate the limitations of the SLEE-defined usage mechanism, Rhino provides a usage extension mechanism that allows an SBB or resource adaptor to declare multiple usage parameters interfaces, and defines a Usage facility with which SBBs and resource adaptors can manage and access their own usage parameter sets.

Viewing Usage Parameters

To view the current value of a usage parameter, use the following rhino-console command or related MBean operation.

Note Whereas the MBean operation below can only get individual usage parameter values, the console command outputs current values of all usage parameters for a specified notification source.

Console command: dumpusagestats

Command

dumpusagestats <type> <notif-source> [param-set-name] [reset]
  Description
    Dump the current values of the usage parameters for the specified notification
    source.  The usage parameter set name is optional and if not specified the
    values for the unnamed (or root) parameter set are returned.  If [reset] is
    specified, the values of the usage parameters are reset after being obtained

Example

$ ./rhino-console  dumpusagestats sbb \
  "service=ServiceID[name=VPN Service,vendor=OpenCloud,version=0.2],sbb=SbbID[name=VPN SBB,vendor=OpenCloud,version=0.2]"
parameter-name       counter-value   sample-stats   type
-------------------  --------------  -------------  --------
       callAttempts               0                  counter
  missingParameters               0                  counter
        offNetCalls               0                  counter
         onNetCalls               0                  counter
   unknownShortCode               0                  counter
 unknownSubscribers               0                  counter
6 rows

MBean operation: get<usage-parameter-name>

MBean

SLEE-defined

Counter-type usage parameters
public long get<usage-parameter-name>(boolean reset)
        throws ManagementException;

Sample-type usage parameters
public SampleStatistics get<usage-parameter-name>(boolean reset)
        throws ManagementException;

Arguments

This operation requires that you specify whether the values are to be reset after being read:

  • reset — boolean value to reset the usage parameter’s value after being read

Return value

Operations for counter-type usage parameters return the current value of the counter. Operations for sample-type usage parameters return a SampleStatistics object.

Usage Notifications

You can enable or disable usage notifications, and list which usage notifications are enabled:

Enabling and Disabling Usage Notifications

To enable or disable usage notifications, use the following rhino-console command or related MBean operation.

Note
The notifications-enabled flag

To enable notifications to output usage parameters to management clients, set the usage notifications-enabled flag, and an appropriate debug level for the SLEE component’s relevant tracer. To disable notifications, unset the notifications-enabled flag.

Console command: setusagenotificationsenabled

Command

setusagenotificationsenabled <type> <notif-source> [upi-type] <param-name>
<flag>
  Description
    Set the usage notifications-enabled flag for specified usage notification
    source's usage parameter.  The usage parameters interface type is optional and
    if not specified the root usage parameters interface type is used

Example

$ ./rhino-console setusagenotificationsenabled sbb \
    "service=ServiceID[name=VPN Service,vendor=OpenCloud,version=0.2],sbb=SbbID[name=VPN SBB,vendor=OpenCloud,version=0.2]" \
    callAttempts true
Usage notifications for usage parameter callAttempts for
SbbNotification[service=ServiceID[name=VPN Service,vendor=OpenCloud,version=0.2],sbb=SbbID[name=VPN SBB,vendor=OpenCloud,version=0.2]]
have been enabled

MBean operation: set<usage-parameter-name>NotificationsEnabled

MBean

SLEE-defined

public void set<usage-parameter-name>NotificationsEnabled(boolean enabled)
    throws ManagementException;

Arguments

  • enabled — a flag to enable or disable notifications for this usage parameter.

Notes

Enabling usage notification

Usage notifications are enabled or disabled on a per-usage-parameter basis for each notification source. That means that if usage notifications are enabled for a particular usage parameter, if that usage parameter is updated in any usage parameter set belonging to the notification source, a usage notification will be generated by the SLEE.

Viewing Usage Notification Status

To list usage parameter status, use the following rhino-console command or related MBean operation.

Note To see which usage parameters management clients are receiving through notifications, you can list usage parameter status.

Console command: listusagenotificationsenabled

Command

listusagenotificationsenabled <type> <notif-source> [upi-type]
  Description
    List the usage notification manager flags for the specified notification source.
     The usage parameters interface type is optional and if not specified the flags
    for the root usage parameters interface type are returned

Example

$ ./rhino-console listusagenotificationsenabled sbb \
    "service=ServiceID[name=VPN Service,vendor=OpenCloud,version=0.2],sbb=SbbID[name=VPN SBB,vendor=OpenCloud,version=0.2]"
parameter-name       notifications-enabled
-------------------  ----------------------
       callAttempts                    true
  missingParameters                   false
        offNetCalls                   false
         onNetCalls                   false
   unknownShortCode                   false
 unknownSubscribers                   false
6 rows

MBean operation: get<usage-parameter-name>NotificationsEnabled

MBean

SLEE-defined

public boolean get<usage-parameter-name>NotificationsEnabled()
        throws ManagementException;

Arguments

  • return — a flag to indicate whether notifications are enabled or disabled for this usage parameter.

Named Usage Parameter Sets

By default, the SLEE creates unnamed usage parameter sets for a notification source. You can also create named usage parameter sets, for example to hold multiple values of usage parameters for the same notification source.

Rhino includes facilities for creating, listing and removing named usage parameter sets for services, resource adaptor entities and profile tables.

This section includes the following procedures:

Warning
Usage parameter sets for internal subsystems (not listed using console command)

The SLEE specification also includes usage parameter sets for "internal subsystems". You can list these, but not create or remove them, since they are part of the SLEE implementation. However, Rhino uses its own statistics API to collect statistics from internal subsystems — so if you try to list usage parameter set names for an internal subsystem using rhino-console, it will always returns an empty list.

Creating Usage Parameter Sets

To create a named usage parameter set for services, resource adaptor entities or profile tables, use the following rhino-console or related MBean operations.

Services

Console command: createusageparameterset

Command

createusageparameterset <type> <notif-source> <param-set-name>
  Description
    Create a new usage parameter set with the specified name for the specified
    notification source

Example

$ ./rhino-console createusageparameterset sbb \
    "service=ServiceID[name=VPN Service,vendor=OpenCloud,version=0.2],sbb=SbbID[name=VPN SBB,vendor=OpenCloud,version=0.2]" \
    firstLook
created usage parameter set firstLook for
SbbNotification[service=ServiceID[name=VPN Service,vendor=OpenCloud,version=0.2],sbb=SbbID[name=VPN SBB,vendor=OpenCloud,version=0.2]]

MBean operation: createUsageParameterSet

MBean

SLEE-defined

public void createUsageParameterSet(SbbID id, String paramSetName)
        throws NullPointerException, UnrecognizedSbbException,
               InvalidArgumentException, UsageParameterSetNameAlreadyExistsException,
               ManagementException;

Arguments

  • id — the component identifier of an SBB, which must be used in a service whose usage information this MBean manages.

  • paramSetName — the usage parameter set name.

Resource adaptor entities

Console command: createusageparameterset

Command

createusageparameterset <type> <notif-source> <param-set-name>
  Description
    Create a new usage parameter set with the specified name for the specified
    notification source

Example

$ ./rhino-console createusageparameterset resourceadaptorentity \
    "entity=cdr" \
    cdr-usage
created usage parameter set cdr-usage for RAEntityNotification[entity=cdr]

MBean operation: createUsageParameterSet

MBean

SLEE-defined

public void createUsageParameterSet(String paramSetName)
        throws NullPointerException, InvalidArgumentException,
               UsageParameterSetNameAlreadyExistsException,
               ManagementException;

Arguments

  • paramSetName — the usage parameter set name.

Profile tables

Console command: createusageparameterset

Command

createusageparameterset <type> <notif-source> <param-set-name>
  Description
    Create a new usage parameter set with the specified name for the specified
    notification source

Example

$ ./rhino-console createusageparameterset profiletable \
    "table=PostpaidChargingPrefixTable" \
    ppprefix-usage
created usage parameter set ppprefix-usage for ProfileTableNotification[table=PostpaidChargingPrefixTable]

MBean operation: createUsageParameterSet

MBean

SLEE-defined

public void createUsageParameterSet(String paramSetName)
        throws NullPointerException, InvalidArgumentException,
               UsageParameterSetNameAlreadyExistsException,
               ManagementException;

Arguments

  • paramSetName — the usage parameter set name.

Listing Usage Parameter Sets

To list named usage parameter sets for services, resource adaptor entities or profile tables, use the following rhino-console or related MBean operations.

Services

Console command: listusageparametersets

Command

listusageparametersets <type> <notif-source>
  Description
    List the usage parameter sets for the specified notification source.  The
    unnamed (or root) parameter set is not included in this list

Example

$ ./rhino-console listusageparametersets sbb \
      "service=ServiceID[name=VPN Service,vendor=OpenCloud,version=0.2],sbb=SbbID[name=VPN SBB,vendor=OpenCloud,version=0.2]"
firstLook
secondLook

MBean operation: getUsageParameterSets

MBean{cth}

SLEE-defined

public String[] getUsageParameterSets(SbbID id)
        throws NullPointerException, UnrecognizedSbbException,
              InvalidArgumentException, ManagementException

Arguments

  • id — the component identifier of an SBB, which must be used in a service whose usage information this MBean manages.

Resource adaptor entities

Console command: listusageparametersets

Command

listusageparametersets <type> <notif-source>
  Description
    List the usage parameter sets for the specified notification source.  The
    unnamed (or root) parameter set is not included in this list

Example

$ ./rhino-console listusageparametersets resourceadaptorentity \
      "entity=cdr"
cdr-usage

MBean operation: getUsageParameterSets

MBean{cth}

SLEE-defined

public String[] getUsageParameterSets()
        throws ManagementException

Profile tables

Console command: listusageparametersets

Command

listusageparametersets <type> <notif-source>
  Description
    List the usage parameter sets for the specified notification source.  The
    unnamed (or root) parameter set is not included in this list

Example

$ ./rhino-console listusageparametersets profiletable \
      "table=PostpaidChargingPrefixTable"
ppprefix-usage

MBean operation: getUsageParameterSets

MBean{cth}

SLEE-defined

public String[] getUsageParameterSets()
        throws ManagementException

Removing Usage Parameter Sets

To removed a named usage parameter set for services, resource adaptor entities or profile tables, use the following rhino-console or related MBean operations.

Services

Console command: removeusageparameterset

Command

removeusageparameterset <type> <notif-source> <param-set-name>
  Description
    Remove the existing usage parameter set with the specified name from the
    specified notification source

Example

$ ./rhino-console  removeusageparameterset sbb \
      "service=ServiceID[name=VPN Service,vendor=OpenCloud,version=0.2],sbb=SbbID[name=VPN SBB,vendor=OpenCloud,version=0.2]" \
      secondLook
removed usage parameter set secondLook for
SbbNotification[service=ServiceID[name=VPN Service,vendor=OpenCloud,version=0.2],sbb=SbbID[name=VPN SBB,vendor=OpenCloud,version=0.2]]

MBean operation: removeUsageParameterSet

MBean

SLEE-defined

public void removeUsageParameterSet(SbbID id, String paramSetName)
        throws NullPointerException, UnrecognizedSbbException,
              InvalidArgumentException, UnrecognizedUsageParameterSetNameException,
              ManagementException;

Arguments

  • id — the component identifier of an SBB, which must be used in a service whose usage information this MBean manages.

  • paramSetName — the usage parameter set name.

Resource adaptor entities

Console command: removeusageparameterset

Command

removeusageparameterset <type> <notif-source> <param-set-name>
  Description
    Remove the existing usage parameter set with the specified name from the
    specified notification source

Example

$ ./rhino-console  removeusageparameterset resourceadaptorentity \
      "entity=cdr" \
      cdr-usage
removed usage parameter set cdr-usage for RAEntityNotification[entity=cdr]

MBean operation: removeUsageParameterSet

MBean

SLEE-defined

public void removeUsageParameterSet(String paramSetName)
        throws NullPointerException,
              InvalidArgumentException, UnrecognizedUsageParameterSetNameException,
              ManagementException;

Argument

  • paramSetName — the usage parameter set name.

Profile tables

Console command: removeusageparameterset

Command

removeusageparameterset <type> <notif-source> <param-set-name>
  Description
    Remove the existing usage parameter set with the specified name from the
    specified notification source

Example

$ ./rhino-console removeusageparameterset profiletable \
      "table=PostpaidChargingPrefixTable" \
      ppprefix-usage
removed usage parameter set ppprefix-usage for ProfileTableNotification[table=PostpaidChargingPrefixTable]

MBean operation: removeUsageParameterSet

MBean

SLEE-defined

public void removeUsageParameterSet(String paramSetName)
        throws NullPointerException,
                InvalidArgumentException, UnrecognizedUsageParameterSetNameException,
                ManagementException;

Argument

  • paramSetName — the usage parameter set name.

User Transactions

As well as an overview of user transactions, this section includes instructions for performing the following Rhino SLEE procedures with explanations, examples and links to related javadocs:

Procedure rhino-console command(s) MBean(s) → Operation
startusertransaction
User Transaction Management → startUserTransaction
commitusertransaction
User Transaction Management → commitUserTransaction
rollbackusertransaction
User Transaction Management → rollbackUserTransaction

About User Transactions

Using the User Transaction Management MBean, a client can demarcate transaction boundaries for a subset of profile-management operations, by:

  • starting a user transaction

  • performing some profile-management operations, across a number of different profiles (in the context of that transaction)

  • then committing the transaction — resulting in an atomic update of profile state.

Binding user transactions with authenticated subjects

The SLEE binds user transactions to the java.security.auth.Subject associated with the invoking thread. For all user-transaction management, the thread invoking the management operation must therefore be associated with an authenticated subject. The command console interface handles this task as part of the client-login process. (Other user-provided m-lets installed in the Rhino SLEE will need to take care of this requirement in their own way.)

Executing Profile Provisioning operations in a user transaction

The following operations on the Profile Provisioning MBean support execution in a user transaction: createProfile, createProfiles, removeProfile, getDefaultProfile, getProfile, and importProfiles

Furthermore, accessing a Profile MBean while a user transaction is active:

  • enlists that MBean into that user transaction

  • changes that MBean to the read/write state

  • puts any changes to the profile in context of the user transaction.

Note
Committing or rolling back profiles enlisted in user transactions

You cannot invoke the ProfileMBean.commitProfile() or ProfileMBean.restoreProfile() operations on a Profile MBean enlisted in a user transaction. Any changes made to such a profile will be committed or rolled back when the user transaction is committed or rolled back (respectively).

Starting User Transactions

To start a user transaction, use the following rhino-console command or related MBean operation.

Console command: startusertransaction

Command

startusertransaction
  Description
    Start a client-demarcated transaction.  Note that only a limited set of Rhino
    management operations support user transactions

Example

$ ./rhino-console startusertransaction

MBean operation: startUserTransaction

MBean

Rhino extension

void startUserTransaction()
    throws com.opencloud.rhino.management.usertx.NoAuthenticatedSubjectException,
          NotSupportedException, ManagementException;

Committing User Transactions

To commit a user transaction, use the following rhino-console command or related MBean operation.

Console command: commitusertransaction

Command

commitusertransaction
  Description
    Commit a client-demarcated transaction

Example

$ ./rhino-console commitusertransaction

MBean operation: commitUserTransaction

MBean

Rhino extension

void commitUserTransaction()
    throws com.opencloud.rhino.management.usertx.NoAuthenticatedSubjectException,
           InvalidStateException, ProfileVerificationException,
           HeuristicMixedException, HeuristicRollbackException,
           RollbackException, ManagementException;

Rolling Back User Transactions

To rollback a user transaction, use the following rhino-console command or related MBean operation.

Console command: rollbackusertransaction

Command

rollbackusertransaction
  Description
    Roll back a client-demarcated transaction

Example

$ ./rhino-console rollbackusertransaction

MBean operation: rollbackUserTransaction

MBean

Rhino extension

void rollbackUserTransaction()
    throws com.opencloud.rhino.management.usertx.NoAuthenticatedSubjectException,
           InvalidStateException, ManagementException;

Auditing Management Operations

Rhino logs all management operations to two log files in the working directory of each Rhino node (work/logs by default):

  • management.csv, a plain text CSV file

  • encrypted.management.csv, a second, encrypted copy of the logs.

Tip You can use the encrypted version to detect tampering with the plain text copy — decode with the decrypt-management-log script, in the client/bin directory.
Note The management audit logs roll over once they reach 100MB, with an unlimited number of backup files. This logging configuration is currently hard-coded.
Note The format of management audit log can be chosen via system property rhino.audit.log_format. See more detail in system property.

Below are descriptions of:

and two examples:

What’s in the log file?

Rhino management operations logs include the following fields:

Field Description
date

A timestamp in the form 2010-05-11 14:55:33.692.

uniqueID

An identifier used to correlate a set of log lines for a single management operation. All of the log lines from the same operation will have the same uniqueID.

opcode

Uniquely identifies the type of operation.

user

The name of the user invoking the management operation, or unknown1 if there is no authenticated user.

roles

Any roles associated with the user.

access

Identifies whether the operation results in a state change of some sort. May be read or write. 2

client address

The IP address of the client invoking the management operation.

namespace

The namespace where the management operation invoked. Empty if it is the default namespace.

MBean name

ObjectName of the MBean invoked.

operation type

The general type of operation.

operation name

The name of the invoked method or get/set attribute.

arguments

The contents of all arguments passed to the management operation. Byte array arguments display converted to a length and a hash.

duration

How long (in milliseconds) the operation took.

result

Either ok or failed.3 4

failure reason

A text string indicating why an operation failed. (Only present for failed results.) 2

Note All management operations except for AUTHENTICATION type operations come in pairs with the first entry indicating the start of an operation, and the second entry indicating success or failure, as well as how long the operation took. Only the result lines make use of the duration, result, and failure reason fields.
Tip For a list of all operations currently recognised by the auditing subsystem, run the getopcodexml command from the command-line console. It will return the complete XML representation of all known management operations.

1 This usually only happens if unauthenticated access has been enabled in Rhino.
2 By default, users with the view permission may only perform read operations.
3 This field is only set for operation results.
4 A failed management operation is one which did not return successfully.

Operation types

The operation type field may contain one of the following values:

Type Result type Description
AUTHENTICATION

n/a

A successful or failed authentication attempt.

INVOKE
INVOKE (RESULT)

An MBean invoke operation.

GET
GET (RESULT)

An MBean attribute get operation.

SET
SET (RESULT)

An MBean attribute set operation.

GET-ATTRIBUTES
GET-ATTRIBUTES (RESULT)

An MBean bulk-attributes GET operation. Log lines with these markers denote a series of related GET requests.

SET-ATTRIBUTES
SET-ATTRIBUTES (RESULT)

An MBean bulk-attributes SET operation. Log lines with these markers denote a series of related SET requests.

Managing the audit level

The auditing subsystem provides two console commands to manage what gets logged to the management audit log:

getmanagementauditlevel
  Description
    Returns the current level of management operation auditing.
setmanagementauditlevel <none \| writes \| all>
  Description
    Sets the current level of management operation auditing.
Tip Writes is useful, for example, to avoid receiving excessive messages from an automated management client that continually polls Rhino state using JMX.
Note Rhino always logs changes to the audit level (irrespective of the current level).

Example 1: Resource adaptor deployment and activation

The following example shows management logs from deploying a resource adaptor, creating a resource adaptor entity for it, and activating that resource adaptor entity.

Note The log shows the resource adaptor activated twice in a row, the second operation failing (because the RA was already activated) — see the result and failure fields.
date uniqueID opcode user roles access client address MBean name operation type operation name arguments duration result failure reason
2010-06-08 14:22:06.850
101:176452077447:22

          
admin

          

          
192.168.0.7

          
AUTHENTICATION

          

          

          
ok

          
2010-06-08 14:22:35.622
101:176452077447:29
19000
admin
admin
write
192.168.0.7
javax.slee.management:
 name=Deployment
INVOKE
install
[file:/home/alex/simple/simple-ra-ha.jar,
[byte array, length=65164,
  md5sum=96322071e6128333bdee3364a224b48c]

          

          

          
2010-06-08 14:22:38.961
101:176452077447:29
19000
admin
admin
write
192.168.0.7
javax.slee.management:
 name=Deployment
INVOKE (RESULT)
install
[file:/home/alex/simple/simple-ra-ha.jar,
[byte array, length=65164,
  md5sum=96322071e6128333bdee3364a224b48c]
]
3339ms
ok

          
2010-06-08 14:22:53.356
101:176452077447:36
22014
admin
admin
write
192.168.0.7
javax.slee.management:
 name=ResourceManagement
INVOKE
getConfigurationProperties
[ResourceAdaptorID
[name=Simple,vendor=OpenCloud,version=1.0]
]

          

          

          
2010-06-08 14:22:53.359
101:176452077447:36
22014
admin
admin
write
192.168.0.7
javax.slee.management:
 name=ResourceManagement
INVOKE (RESULT)
getConfigurationProperties
[ResourceAdaptorID
[name=Simple,vendor=OpenCloud,version=1.0]
]
3ms
ok

          
2010-06-08 14:22:53.369
101:176452077447:39
22016
admin
admin
write
192.168.0.7
javax.slee.management:
 name=ResourceManagement
INVOKE
createResourceAdaptorEntity
[ResourceAdaptorID
[name=Simple,vendor=OpenCloud,version=1.0],
 simplera,
[(Host:java.lang.String=localhost),
  (Port:java.lang.Integer=14477),
  (slee-vendor:
    com.opencloud.rhino_replicate_activities:
    java.lang.String=none)
 ]
]

          

          

          
2010-06-08 14:22:53.536
101:176452077447:39
22016
admin
admin
write
192.168.0.7
javax.slee.management:
 name=ResourceManagement
INVOKE (RESULT)
createResourceAdaptorEntity
[ResourceAdaptorID
[name=Simple,vendor=OpenCloud,version=1.0],
 simplera,
[(Host:java.lang.String=localhost),
  (Port:java.lang.Integer=14477),
  (slee-vendor:
    com.opencloud.rhino_replicate_activities:
    java.lang.String=none)
 ]
]
167ms
ok

          
2010-06-08 14:23:11.987
101:176452077447:47
22004
admin
admin
write
192.168.0.7
javax.slee.management:
 name=ResourceManagement
INVOKE
activateResourceAdaptorEntity
[simplera,[101]]

          

          

          
2010-06-08 14:23:12.029
101:176452077447:47
22004
admin
admin
write
192.168.0.7
javax.slee.management:
 name=ResourceManagement
INVOKE (RESULT)
activateResourceAdaptorEntity
[simplera,[101]]
42ms
ok

          
2010-06-08 14:23:30.802
101:176452077447:52
22004
admin
admin
write
192.168.0.7
javax.slee.management:
 name=ResourceManagement
INVOKE
activateResourceAdaptorEntity
[simplera,[101]]

          

          

          
2010-06-08 14:23:30.820
101:176452077447:52
22004
admin
admin
write
192.168.0.7
javax.slee.management:
 name=ResourceManagement
INVOKE (RESULT)
activateResourceAdaptorEntity
[simplera,[101]]
18ms
failed
simplera not in INACTIVE state on node(s)[101]

Example 2: Bulk GET operation on Licensing MBean

The example below shows a GET-ATTRIBUTES operation called on the Licensing MBean. It includes queries on four separate attributes: LicenseSummary, LicensedFunctions, LicensedVersions, and Licenses. The result of the bulk-attribute query operation are in the last line.

Note Note that the uniqueID field is the same for all lines representing the GET-ATTRIBUTES operation.
date uniqueID opcode user roles access client address MBean name operation type operation name arguments duration result failure reason
2010-05-28 14:07:11.223
101:175500674962:292

          
admin
admin

          
192.168.0.7
com.opencloud.rhino:
 type=Licensing
GET-ATTRIBUTES

          

          

          

          

          
2010-05-28 14:07:11.223
101:175500674962:292
2008
admin
admin
read
192.168.0.7
com.opencloud.rhino:
 type=Licensing
GET
LicenseSummary

          

          

          

          
2010-05-28 14:07:11.223
101:175500674962:292
2005
admin
admin
read
192.168.0.7
com.opencloud.rhino:
 type=Licensing
GET
LicensedFunctions

          

          

          

          
2010-05-28 14:07:11.223
101:175500674962:292
2006
admin
admin
read
192.168.0.7
com.opencloud.rhino:
 type=Licensing
GET
LicensedVersions

          

          

          

          
2010-05-28 14:07:11.223
101:175500674962:292
2004
admin
admin
read
192.168.0.7
com.opencloud.rhino:
 type=Licensing
GET
Licenses

          

          

          

          
2010-05-28 14:07:11.226
101:175500674962:292
2008
admin
admin
read
192.168.0.7
com.opencloud.rhino:
 type=Licensing
GET (RESULT)
LicenseSummary

          
3ms
ok

          
2010-05-28 14:07:11.226
101:175500674962:292
2005
admin
admin
read
192.168.0.7
com.opencloud.rhino:
 type=Licensing
GET (RESULT)
LicensedFunctions

          
3ms
ok

          
2010-05-28 14:07:11.226
101:175500674962:292
2006
admin
admin
read
192.168.0.7
com.opencloud.rhino:
 type=Licensing
GET (RESULT)
LicensedVersions

          
3ms
ok

          
2010-05-28 14:07:11.226
101:175500674962:292
2004
admin
admin
read
192.168.0.7
com.opencloud.rhino:
 type=Licensing
GET (RESULT)
Licenses

          
3ms
ok

          
2010-05-28 14:07:11.226
101:175500674962:292

          
admin
admin

          
192.168.0.7
com.opencloud.rhino:
 type=Licensing
GET-ATTRIBUTES (RESULT) 

          

          
3ms
ok

          
Note The durations listed for the individual GET (RESULT) lines correspond to the duration of the entire GET-ATTRIBUTES operation and not the individual GET components. In the example above, the entire GET-ATTRIBUTES operation took 3ms.

Linked and Shadowed Components

There can be times when creating component dependencies in a deployable unit where a specific dependency target may not be known. For example, the particular version of a dependent library may be variable. At other times, some already installed component may need to be replaced with another, possibly a new version with a bug fix, and reinstalling all dependent components with updated deployment descriptors is undesirable.

Bindings can help with this problem, to some degree, however bindings can introduce other issues. Bindings always operate on virtual copies of the original components, and keeping track of copied components can be difficult if many binding operations are made.

Rhino provides a solution to these problems with support for linked and shadowed components.

Linked components

A linked component is a virtual component that provides an alias for some other component. Incoming references to the linked component are redirected to the link target. A linked component’s component type, for example SBB, profile specification, library, and so on, is the same as the component that it is linked to; and, like all other components, has a unique identity represented by the (name, vendor, version) tuple.

A linked component identifier can be used anywhere where a regular component identifier is required.

Shadowed components

A shadowed component is an existing component that has been "shadowed" or replaced by a link to another component of the same type. Incoming references to the shadowed component are redirected to the link target rather than using the original component.

Conceptually, linked and shadowed component perform the same function: to redirect an incoming reference to another component. The difference is that a linked component is a new virtual component with a unique identity, whereas a shadow replaces a component that is already installed in the SLEE.

Note
Components supporting links and shadows

The following types of components currently support links and shadows:

  • services

  • SBBs

  • SBB parts

  • profile specifications

  • resource adaptor types

  • resource adaptors

  • event types

  • libraries.

Managing linked components

Below are overviews of the procedures to create, remove, and view the metadata for linked components.

Creating a linked component

You create linked components using the createLinkedComponent management operation. For example, using rhino-console:

[Rhino@localhost:2199 (#0)] createlinkedcomponent sbb name=MySBB,vendor=OpenCloud,version=1.0 MySBBLink OpenCloud 1.0
Component SbbID[name=MySBBLink,vendor=OpenCloud,version=1.0] linked to SbbID[name=MySBB,vendor=OpenCloud,version=1.0]

The first two arguments identify the component type and identifier of the link target. The target component must already exist in the SLEE. The last three arguments define the name, vendor, and version strings for the new linked component identifier.

Removing a linked component

You remove a linked component using the removeLinkedComponent management operation. For example, using rhino-console:

[Rhino@localhost:2199 (#0)] removelinkedcomponent sbb name=MySBBLink,vendor=OpenCloud,version=1.0
Linked component SbbID[name=MySBBLink,vendor=OpenCloud,version=1.0] removed

A linked component cannot be removed if:

  • another component with an install level of VERIFIED or DEPLOYED references it;

  • another linked component specifies this linked component as its target; or

  • another component is shadowed by this linked component.

Viewing linked component metadata

The getDescriptor management operation returns a SLEE ComponentDescriptor object for any component that exists in the SLEE. A ComponentDescriptor object for a linked component has the following properties:

  • its deployable unit is the same as the deployable unit of the link target

  • its source component jar is the same as the source component jar of the link target

  • it contains a vendor-specific data object of type LinkedComponentDescriptorExtensions.

Linked component descriptor extensions

The LinkedComponentDescriptorExtensions class defines Rhino-specific component metadata extensions for linked components. Here’s what it looks like:

package com.opencloud.rhino.management.deployment;

import java.io.Serializable;
import java.util.Date;
import javax.slee.ComponentID;

public class LinkedComponentDescriptorExtensions implements Serializable {
    public LinkedComponentDescriptorExtensions(...) { ... }

    public ComponentID getLinkTarget() { ... }

    public Date getLinkDate() { ... }

    public InstallLevel getInstallLevel() { ... }

    public ComponentID[] getIncomingLinks() { ... }

    public ComponentID[] getShadowing() { ... }

    ...
}
  • The getLinkTarget method returns the component identifier of the link target.

  • The getLinkDate method returns a Date object that specifies the date and time the linked component was created.

  • The getInstallLevel method returns the current install level of the linked component. The install level of a linked component is immaterial, and changing it has no effect on the linked component itself; however, since an install level is a property of all components installed in Rhino, a linked component must have one by definition.

  • The getIncomingLinks method returns the component identifiers of any other linked components that have this linked component as a target.

  • The getShadowing method returns the component identifiers of any other component that has been shadowed by this linked component.

Managing component shadows

Shadowing or unshadowing a component effectively changes the definition of the component; therefore a component can only undergo these transitions if it has an install level of INSTALLED. This ensures that any components that depend on the affected component also have an install level of INSTALLED, and thus will need (re)verifying against the updated component before further use. Rhino will allow a component with an install level of VERIFIED to be shadowed or unshadowed, but will automatically transition the component (and any upstream dependencies) to the INSTALLED install level first. A component with an install level of DEPLOYED must be manually undeployed before a shadow can be created or removed.

Below are overviews of the procedures to shadow, unshadow, and view the shadow metadata for a component.

Shadowing a component

You shadow one component with another using the shadowComponent management operation. For example, using rhino-console:

[Rhino@localhost:2199 (#0)] shadowcomponent sbb name=MySBB,vendor=OpenCloud,version=1.0 name=MySBB,vendor=OpenCloud,version=1.0.2
Component SbbID[name=MySBB,vendor=OpenCloud,version=1.0] shadowed by SbbID[name=MySBB,vendor=OpenCloud,version=1.0.2]

The first two arguments identify the component type and identifier of the component to be shadowed. The last argument identifies the component that this component will be shadowed by. Both the shadowed and shadowing components must already exist in the SLEE.

Warning
Link cycles won’t work

Using shadows, you might try to create a link cycle. For example, if component A is a link to component B, component B is a link to component C, and component C is shadowed by component A, then a link cycle would exist which cannot be resolved to any concrete component. Rhino forbids such cycles to be created. An attempt to shadow a component with another component that would result in a link cycle will fail with an appropriate error.

Unshadowing a component

You unshadow a component using the unshadowComponent management operation. For example, using rhino-console:

[Rhino@localhost:2199 (#0)] unshadow sbb name=MySBB,vendor=OpenCloud,version=1.0
Shadow removed from component SbbID[name=MySBB,vendor=OpenCloud,version=1.0]

Viewing shadowed component metadata

The getDescriptor management operation returns a SLEE ComponentDescriptor object for any component that exists in the SLEE. The component descriptor for a shadowed component continues to describe the original unshadowed component, but contains a vendor-specific data object of type com.opencloud.rhino.management.deployment.ComponentDescriptorExtensions that includes the following information relevant to shadowing:

  • The getShadowedBy method returns the component identifier of the component that shadows this component. This target component will be used in place of the described component.

  • The getShadowDate method returns a Date object that specifies the date and time the shadow was established.

  • The getShadowing method returns the component identifiers of any other component that has in turn been shadowed by this shadowed component.

Linked and shadowed component resolution

In most cases where a component identifier is specified, Rhino will follow a chain of links and shadows to resolve the component identifier to a concrete target component. Typical cases where this occurs are as follows:

  • wherever a component references another component in its deployment descriptor or in a binding descriptor

  • if a service component is activated or deactivated

  • when a profile table is created from a profile specification
    (though Rhino will report that the profile table was created from the specified component rather than the resolved target)

  • when a resource adaptor entity is created from a resource adaptor
    (though again Rhino will report that the resource adaptor entity was created from the specified component rather than the resolved target)

  • when interrogating or updating a component’s security policy.

Specific cases where a management operation applies directly to a linked or shadowed component rather than its resolved target are as follows:

  • when requesting a component’s metadata descriptor

  • when copying a shadowed component
    (The shadowed component itself is copied, rather than the shadowing component. Linked components are still resolved though when determining the actual component to copy; so an attempt to copy a linked component will result in a copy of the resolved target component being copied.)

Additional notes

  • Creating a link to a service component automatically adds a clone of the resolved target service’s statistics with the linked component identifier to the stats manager. For example, if service component A is linked to service component B, then the stats for B can be accessed from the stats manager using either component identifier A or B. The same result will be obtained in each case. Listing the available stats parameter sets will include both A and B.

  • The activation state reported for a linked or shadowed service component is the state of the service component that the link or shadow resolves to. Activating or deactivating the linked or shadowed component has the same effect as activating or deactivating the resolved component.

  • If a resource adaptor entity generates events that may be consumed by a given service component, and a link to that service component is created, then the resource adaptor entity will also be notified about a change to the lifecycle state for the linked component when the state of the target service component changes.

  • A resource adaptor entity may fire an event targeted at a linked service component, and Rhino will deliver the event to the resolved target service component. If an SBB in the service invokes a resource adaptor interface API method while handling that event, then the value returned by the ResourceAdaptorContext.getInvokingService() method will equal the target service component identifier specified by the resource adaptor entity when the event was fired; that is, it will be the linked component identifier. However if an SBB in the service invokes a resource adaptor interface API method while handling an event that had no specific service target, then the value returned by the same getInvokingService() method will be the service component identifier of the resolved service that is actually processing the event.

Component Activation Priorities

Rhino versions 2.4 and above allow configuration of the activation order of SLEE components. This ordering is controlled separately for activating and deactivating components.

Introduction to priorities

In Rhino 2.3.1 and older, RAs and services started in effectively random order. The startup order was based on the indexing hash order in the system.

The priority system added in Rhino 2.4 allows operator control of this order.

Priorities are values between -128 and 127. If a component (service or resource adaptor entity), X, has a numerically higher priority value than another component, Y, then X will be started before Y. Components with the same priority may be started in an arbitrary order, or may be started concurrently. The same rule applies for component stopping priorities; i.e., highest priority stops first.

If you have assigned startup priorities to; RAs A=100, B=20, C=10; and service S=15, they will start up in the following order:

  1. activate RA entity A

  2. activate RA entity B

  3. activate service S

  4. activate RA entity C

Note that a service can still potentially receive an event from an RA before it receives a ServiceStartedEvent on the ServiceActivity. That’s a completely different problem to activation ordering, and given the asynchronous nature of event delivery not something we can readily do anything about. A service that depends on the ServiceStartedEvent may be able to use the service activation callbacks in Rhino 2.4 instead. You may notice that services of the same priority level as RA entities start before the RA entities and stop after them. This ordering is not part of the priority system definition. It is possible that they will be started concurrently in the future, so always use different priorities if you need a specific order.

Managing priorities

Below are overviews of the procedures to manage service priorities, manage RA entity priorities, and list priorities.

Managing service priorities

You get priorities for services using the getStartingPriority and getStoppingPriority management operations.

You set priorities for services using the setStartingPriority and setStoppingPriority management operations.

For example, using rhino-console:

[Rhino@localhost:2199 (#0)] setservicestartingpriority name=MyService,vendor=OpenCloud,version=1.0 10
Service ServiceID[name=MyService,vendor=OpenCloud,version=1.0] activation priority set to 10

Managing RA entity priorities

You get priorities for RA entities using the getStartingPriority and getStoppingPriority management operations.

You set priorities for RA entities using the setStartingPriority and setStoppingPriority management operations.

For example, using rhino-console:

[Rhino@localhost:2199 (#0)] setraentitystartingpriority sipra 80
Resource adaptor entity sipra activation priority set to 80

Listing priorities

You list priorities for services using the getStartingPriorities and getStoppingPriorities management operations.

You list priorities for RA entities using the getStartingPriorities and getStoppingPriorities management operations.

You get a full combined listing using the liststartingpriorities and liststoppingpriorities commands in rhino-console.

For example:

[Rhino@localhost:2199 (#0)] liststartingpriorities
Starting priorities of installed services and resource adaptor entities:
  80 : resource adaptor entity sipra
  20 : ServiceID[name=SIP Presence Service,vendor=OpenCloud,version=1.1]
  10 : ServiceID[name=SIP Proxy Service,vendor=OpenCloud,version=1.8]
   0 : ServiceID[name=SIP Notification Service,vendor=OpenCloud,version=1.1]
       ServiceID[name=SIP Profile Location Service,vendor=OpenCloud,version=1.0]
       ServiceID[name=SIP Publish Service,vendor=OpenCloud,version=1.0]
  -5 : ServiceID[name=SIP Registrar Service,vendor=OpenCloud,version=1.8]
Note: Components with the same priority may be started in any order

Rhino Configuration

This section covers procedures for configuring Rhino upon installation, and as needed (for example to tune performance).

This includes configuring:

Tip See also Management Tools.

Logging

Rhino supports logging to multiple different locations and offers granular configuration of loggers and output. The most common configuration used is of log levels and output appenders. Log appenders are used to direct logging output for display and storage, typically to files or the console terminal. Rhino provides management interfaces and commands for configuring the logging framework. It also provides access to the logging framework for deployed components as extensions to the SLEE specification.

This section includes the following topics:

Note JMX clients can access logging management operations via the Logging Management MBean.

About Logging

The Rhino SLEE uses the Apache Log4j 2 logging framework to provide logging facilities for SLEE components and deployed services.

Tip
The Logging Management MBean

Rhino SLEE allows changes to logging configuration at runtime. This is useful for capturing log information to diagnose a problem, without having to restart the SLEE. You configure logging using the Logging Management MBean, through the command console. This MBean lets you query the log configuration, and for most subsystems effect immediate changes (some require a node restart for performance reasons).

Rhino’s logging system includes logger names, log levels, log appenders, filters, and tracers.

Asynchronous Logging

The Log4j 2 logging architecture provides a new approach to asynchronous logging. It uses asynchronous loggers, which submit log events to a work queue for later handling by the appropriate appenders.

More details can be found in the Log4j 2 async loggers documentation

Rhino offers support for mixed synchronous and asynchronous logging through logger configuration commands. Correctly configuring asynchronous logging has some complexity, discussed in how to Configure a Logger.

Mapped Diagnostic Context

Rhino 2.6 introduces access to the Mapped Diagnostic Context (MDC) as a tool to tag and correlate log messages throughout an activity’s life cycle. This tagging can be combined with the new filters to allow very fine grained control of logging and tracing.

A simple SIP example of useful context would be including the P-charging-vector header. As this uniquely identifies a single call, it becomes trivial to identify all log messages related to handling an individual call. Identification (or filtering) remains simple even under load, with multiple calls handled in parallel.

The Logging Context Facility discusses MDC in greater detail.

Logger names

Subsystems within the Rhino SLEE send log messages to specific loggers. For example, the rhino.facility.alarm logger periodically receives messages about which alarms are currently active within the Rhino SLEE.

Examples of logger names include:

  • root — the root logger, from which all loggers are derived (can be used to change the log level for all loggers at once)

  • rhino — main Rhino logger

  • rhino.management — for log messages related to Rhino management systems

  • trace.<namespace>.<deployable_type>.<notification_source>.<tracer name> — loggers used by deployed SLEE components that use tracers. By default these keys appear abbreviated in console and file logs. Details of tracer abbreviation can be found at Tracer pattern converter.

Log levels

Log levels can be assigned to individual loggers to filter how much information the SLEE produces:

Log level Information sent
OFF

No messages sent to logs (not recommended).

FATAL

Error messages for unrecoverable errors only (not recommended).

ERROR

Error messages (not recommended).

WARN

Warning messages.

INFO

Informational messages (especially during node startup or deployment of new resource adaptors or services). The default.

DEBUG

Detailed log messages. Used for debugging by OpenCloud Rhino SLEE developers.

TRACE

Finest level. Not currently used.

ALL

All of the above.

Each log level will log all messages for that log level and above. For example, if a logger is set to the INFO level (the default), all of the log messages logged at the INFO, WARN, ERROR, and FATAL levels will be logged as well.

If a logger is not assigned a log level, it inherits its parent’s. For example, if the rhino.management logger has not been assigned a log level, it will have the same effective log level as the rhino logger.

The root logger is a special logger which is considered the parent of all other loggers. By default, the root logger is configured with the INFO log level. In this way, all other logger will output log messages at the INFO log level or above unless explicitly configured otherwise.

Warning
Use INFO

A lot of useful or crucial information is output at the INFO log level. Because of this, setting log levels to WARN, ERROR or FATAL is not recommended.

Log appenders

System administrators can use the console to create some simple log appenders. Full appender creation is available through the Rhino Element Manager (REM). These append log messages to destinations such as the console, a log file, socket, or Unix syslog daemon. At runtime, when Rhino logs a message (as permitted by the log level of the associated logger), Rhino sends the message to the log appender for writing. Types of log appenders include:

  • file appenders — which append messages to files (and may be rolling file appenders)

  • console appenders — which send messages to the Rhino console

  • socket appenders — Append to a network socket. Either raw, or syslog formatted.

  • custom appenders — which can do a wide variety of things. Common "custom" apenders are used to append to various kinds of database.

Rolling file appenders

Typically, to manage disk usage, administrators are interested in sending log messages to a set of rolling files. They do this by setting up rolling file appenders which:

  • create new log files if the current one gets too large

  • rename old log files as numbered backups

  • delete old logs when a certain number of them have been archived.

Log files roll over when they exceed the configured size i.e. size is checked after logging each message, if the log file is larger than the maximum the next message will be written to a new file. Since Rhino 2.6.0 only the SDK rolls over log files on node restart. Production nodes use a size-based policy only.

You can configure the size and number of rolled-over log files and the rollover behaviour. Options include size-based, time-based and on node-restart. All configurations described for Log4j 2 are valid: https://logging.apache.org/log4j/2.x/manual/appenders.html#RollingFileAppender

An example logging config containing a complex rollover strategy that increments file numbers, retaining up to 4 historical files younger than 30 days:

        <appender name="RhinoLog" plugin-name="RollingFile">
            <layout name="RhinoLogLayout" plugin-name="PatternLayout">
                <property name="pattern" value="%d{yyyy-MM-dd HH:mm:ss.SSS} %-5level [%logger] <%threadName> %mdc : %msg%n%throwable"/>
                <property name="header" value="${rhinoVersionHeader}"/>
            </layout>
            <property name="filePattern" value="${logDir}/rhino.log.%i"/>
            <property name="fileName" value="${logDir}/rhino.log"/>
            <component name="RhinoLogPolicy" plugin-name="SizeBasedTriggeringPolicy">
                <property name="size" value="100MB"/>
            </component>
            <component name="RhinoLogStrategy" plugin-name="NotifyingRolloverStrategy">
                <property name="min" value="1"/>
                <property name="max" value="2147483647"/>
                <component name="deleteAction" plugin-name="Delete">
                    <property name="basePath" value="${logDir}"/>
                    <property name="maxDepth" value="1"/>
                    <component name="fileName" plugin-name="IfFileName">
                        <property name="glob" value="rhino.log.*"/>
                    </component>
                    <component name="any" plugin-name="IfAny">
                        <component name="lastmodified" plugin-name="IfLastModified">
                            <property name="age" value="30d"/>
                        </component>
                        <component name="fileCount" plugin-name="IfAccumulatedFileCount">
                            <property name="exceeds" value="4"/>
                        </component>
                    </component>
                </component>
            </component>
        </appender>

Default appenders

By default, the Rhino SLEE comes configured with the following appenders active:

Appender Where it sends messages Logger name Type of appender
RhinoLog

the Rhino logs directory (work/log/rhino.log)

root

a rolling file appender

STDERR

the Rhino console where a node is running (in a standard error stream)

root

a console appender

ConfigLog

work/log/config.log

rhino.config

a rolling file appender

Warning
New appenders won’t receive messages until associated with at least one logger

By default, a newly created log appender is not associated with any loggers, so will not receive any log messages.

Appender additivity

If a logger has its additivity flag set to true, all of the output of its log statements goes to all of its appenders and ancestors. If a specific ancestor has its additivity flag set to false, then the output goes to all appenders and ancestors up to and including that specific ancestor — but not to appenders in any of that ancestor’s ancestors. (By default, logger additivity flags are set to true.}

Note See Apache’s Log4j 2 Architecture page for details on additivity.

Filters

Filters can be applied to both loggers and appenders to restrict the set of log messages that are reported by a logger or through an appender. They provide a more flexible limiting approach than log level alone. Configuring filters can be performed using the Rhino Element Manager or by modifying an export of the logging configuration. A list of the filters available by default and their configuration properties can be found in the Log4j 2 filter documentation

An example filter configuration setting for limiting log levels to Finer in namespace volte and Info in all other namespaces is shown below:

                <component plugin-name="DynamicThresholdFilter">
                    <property name="defaultThreshold" value="Finer"/>
                    <property name="key" value="namespace"/>
                    <component plugin-name="KeyValuePair">
                        <property name="key" value="volte"/>
                        <property name="value" value="Warning"/>
                    </component>
                </component>