This document describes the sample SIP applications that come with Rhino and how to prepare, deploy, configure and run them.

Topics

About the Sample Applications

Descriptions and list of files and directories containing the sample resource adaptor, services, and SBBs included with the Rhino SLEE

Quickstart

Brief instructions for setting up the environment, running the build script, and configuring the services

Manual Installation

More detailed instructions for configuring and deploying the SIP RA installation; specifying a location service; installing the Registrar, Proxy, and Presence services; and modifying service source code.

Using the Services

How to configure and use a SIP user agent with the example services, and enable tracing SIP services.

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

About the Sample Applications

The Rhino SLEE comes with a SIP RA and sample SIP applications (services and components) that use Session Initiation Protocol — RFC3261 (SIP).

As well as implementing some basic SIP services, these examples also demonstrate many SLEE features, such as:

  • deploying and undeploying components such as resource adaptors and services

  • service building blocks (SBBs) and container managed persistence (CMP) state

  • child SBBs and SBB local interfaces

  • shared state using null activities and activity-context attributes

  • storing subscriber data using profiles.

Below are descriptions of the examples and related files and directories.

Resource adaptor, service, and SBB examples

The example SIP components included with the Rhino SLEE are:

Component What it does

SIP resource adaptor

Provides the interface between SIP user agents and the SLEE. The SIP RA is responsible for sending and receiving SIP messages over the network. The SIP RA processes messages from the network and converts them to SLEE activities and events, for use by SLEE applications. The SIP RA must be installed in the SLEE before the other SIP applications can be used.

SIP Registrar service

An implementation of a SIP registrar as defined in RFC3261 section 10. This service handles SIP REGISTER requests, which SIP user agents send to register a binding from a user’s public address to the physical network address of their user agent. The registrar service updates records in a location service, which other SIP applications use. The registrar service is implemented by a single SBB component, which uses a location service child SBB to query and update location service records.

SIP Stateful Proxy service

Implements a stateful proxy as described in RFC3261 section 16. This proxy is responsible for routing requests to their correct destination, as given by contact addresses that have been registered with the location service. The proxy service is implemented by a single SBB component, which uses a location service child SBB to query location service records.

SIP Find-me Follow-me service

Provides an intelligent SIP proxy service, which lets a user profile specify alternative SIP addresses to contact if their primary contact address is not available.

SIP Back-to-back User-Agent service

An example of a back-to-back user agent (B2BUA). Behaves like the proxy service, but maintains SIP dialog state (call state) using dialog activities.

AC-naming, Profile & JDBC Location-Service SBBs

Provide alternate implementations of a SIP location service, which the proxy and registrar services use. The AC-naming location service uses the SLEE’s ActivityContext Naming Facility to store location information. The profile location service uses SLEE profiles, and the JDBC location service stores location information in an external database.

SIP Presence service

An implementation of a SIP Presence service, as described in RFC3856, RFC3863, and RFC3903. Allows a user to subscribe to the presence information of another user, and to update his or her own presence information for other users to see. This enables the "buddy list" feature of many SIP clients, which in turn may also enable their instant-messaging features.

SIP example files and directories

The base directory for the SIP examples is $RHINO_HOME/rhino-connectivity/sip-2.3.0.0. It contains:

File or directory Description
build.xml

Ant build script for SIP sample applications. Manages building and deployment of the examples.

build.properties

Properties for the Ant build script.

sip.properties

Properties for the SIP services. When the Ant build script runs, it substitutes these properties into the application deployment descriptors.

README.txt

Text file containing "quick start" instructions.

CHANGELOG.txt

Text file describing recent changes to the SIP RA and examples.

docs/

Contains RA and API documentation.

src/

Contains source code for sample SIP services.

lib/

Contains SIP resource adaptor and RA-type jars, and required libraries.

classes/

Directory where the build script writes compiled class files.{ctd}

jars/

Directory where the build script writes jar files that are ready for deployment.

Quickstart

The default sample SIP services deployed with Rhino are: the Proxy, Registrar and Presence services. Together, these services provide basic SIP-server functionality, and are intended to work "out of the box" with minimal configuration.

To get the default SIP examples up and running straight away, follow the quick start instructions here. For more detailed information on building, installing and configuring the examples, see Manual Installation.

Below are instructions on configuring and deploying the sample services.

Note Files referred to in the instructions are in the directory $RHINO_HOME/rhino-connectivity/sip-2.3.1.0.

Configure sample SIP services

Before deploying the examples, you must first change the default configuration of the Proxy service to suit your environment. It is configured in the sip.properties file. Edit this file, changing the PROXY_DOMAINS property as follows:

# Proxy SBB configuration
# Add domains that the proxy is authoritative for
PROXY_DOMAINS=opencloud.com,opencloud.co.nz

The default domains opencloud.com and opencloud.co.nz are just examples — change this property to use the correct domains for your environment.

The PROXY_DOMAINS property contains the domains that the proxy SBB considers to be local. This means that if the proxy SBB receives a request addressed to a user in one of these domains (such as sip:bob@opencloud.com), it will use the location service to find the registered contact address of that user. If the user cannot be found, the Proxy service will return an error response.

If the Proxy service receives a request addressed to a user in an unknown domain, it will forward the request according to normal SIP routing rules.

Warning On a Windows installation, with user agents on separate PCs, the Windows firewall may block SIP messages sent over the network. You may need to re-configure the firewall to ensure that Rhino can receive SIP messages.

Deploy sample SIP services

By default, the Ant build script build.xml builds and deploys the Registrar, Proxy and Presence sample services with the components they need (including the SIP resource adaptor and location service), into Rhino.

To deploy the examples, run Ant with the deployexamples target:

$ ant deployexamples

If you don’t have Ant installed, you can use a copy that is bundled with Rhino: run the deployexamples.sh script (or deployexamples.bat on Windows).

Once you have deployed the sample Registrar, Proxy and Presence services, see Using the Services for instructions on how to test them with your SIP user agents.

Manual Installation

This page explains in more detail how to configure and deploy the SIP resource adaptor and examples services that come with Rhino.

Tip If you just want to get something up and running quickly, see the Quickstart page.

To manually install and configure the example SIP services:

1

Configure and deploy the SIP resource adaptor (RA).

2

3

5

Please experiment with the examples, and try implementing new features. The source code for all the example services can be found in src/com/opencloud/slee/services.

  • If you change the source code of any of the examples, you can easily recompile and deploy them using the Ant targets in build.xml.

  • If a service is already installed, remove it using the relevant undeploy Ant target (such as undeployregistrar), then rebuild and redeploy using the relevant deploy target (use ant -p to list the possible targets).

  • All the deploy targets are written so that they recompile, rebuild jars, and deploy any dependencies that are not already installed.

It pays to familiarise yourself with Ant and the deploy/undeploy targets in build.xml. This will make it easier to build, deploy and test your own projects.

Configure the SIP RA

The default configuration of the SIP resource adaptor (RA) should be suitable for most environments. However, you can easily reconfigure it to suit a particular requirement, such as using a different IP address or port number.

Each resource adaptor defines a default set of configuration properties that determine its behaviour. When an administrator creates a resource adaptor entity (an "instance" of the RA), they can specify configuration property values other than the defaults.

Below are instructions for editing SIP RA configuration properties and a full listing of Rhino’s default SIP RA configuration properties.

Editing SIP RA configuration properties

The Ant build script build.xml creates the SIP resource adaptor entity with the following properties (defined in the build.properties file):

sip.ra.properties=IPAddress=AUTO,Transports="udp,tcp",Port=5060,SecurePort=5061

To change these properties and specify others, edit the sip.ra.properties property. For example, to enable the SIP RA’s replicated-dialog support, you would add that property as follows (and then deploy the SIP RA):

sip.ra.properties=IPAddress=AUTO,Transports="udp,tcp",Port=5060,SecurePort=5061,ReplicatedDialogSupport=true

The Ant build.xml script will pass these properties to the createRAEntity management command.

SIP RA configuration properties

The complete set of configuration properties supported by the SIP RA are as follows.

Property Type Default Description
IPAddress
java.lang.String
AUTO

The IP address the SIP RA will listen on.

The value AUTO means the RA will listen on all interfaces and use the host’s primary IP address in outgoing headers. On Unix machines, the address returned is the IP address associated with the machine’s "hostname".

VirtualAddresses
java.lang.String
None

Hostnames and/or IP addresses that are local to the cluster. Required when a load balancer is providing a virtual IP address (VIP) for the Rhino cluster.

Port
java.lang.Integer
5060

Port used for unencrypted SIP transports (UDP, TCP).

SecurePort
java.lang.Integer
5061

Port used for encrypted SIP transports (TLS).

Transports
java.lang.String
UDP,TCP

Supported SIP transports: comma-separated list containing one or more of UDP, TCP or TLS.

OffsetPorts
java.lang.Boolean
False

Required when running multiple cluster nodes on the same host. If true, the RA will automatically add an offset to the SIP port number, so that each SIP RA instance gets a different port number. See PortOffset below.

PortOffset
java.lang.Integer
101

Required when running multiple cluster nodes on the same host. If OffsetPorts is enabled, the SIP RA’s port will be calculated as Port + (NodeID - PortOffset). Typically the PortOffset value used is the lowest NodeID in the cluster. So if Port is 5060, and the lowest NodeID is 101, and the cluster has nodes 101, 102 and 103, the SIP ports used will be 5060, 5061 and 5062 respectively.

Automatic100TryingSupport
java.lang.Boolean
True

If enabled, the RA will automatically generate 100 Trying responses for INVITEs.

WorkerPoolSize
java.lang.Integer
4

Number of worker threads the SIP RA will use to process incoming messages. If 0, the RA will receive and process messages in the same I/O thread. Otherwise the pool will be used so that incoming messages can be processed concurrently.

WorkerQueueSize
java.lang.Integer
50

Queue size for the worker thread pool. If the queue fills, then the RA will drop packets (UDP) or temporarily suspend reads (TCP).

TCPIOThreads
java.lang.Integer
1

Number of threads for handling TCP I/O. TCP connections will be divided between the I/O threads.

ReplicatedDialogSupport
java.lang.Boolean
false

Enables support for replicating SIP dialog state, so that dialog activities can continue on other cluster nodes after a node failure. Requires a clustered, production Rhino installation.

ExtensionMethods
java.lang.String
None

SIP methods that can initiate dialogs, in addition to the standard INVITE and SUBSCRIBE methods.

Keystore
java.lang.String
sip-ra-ssl.keystore

The keystore used to store the public certificates.

KeystoreType
java.lang.String
jks

The encryption type of the keystore.

KeystorePassword
java.lang.String
None

The keystore password.

Truststore
java.lang.String
sip-ra-ssl.truststore

The keystore containing a private certificate.

TruststoreType
java.lang.String
jks

The encryption type of the trust keystore.

TruststorePassword
java.lang.String
None

The trust keystore password.

CRLURL
java.lang.String
None

The certificate-revocation list location.

CRLRefreshTimeout
java.lang.Integer
86400

The certificate-revocation list refresh timeout (seconds).

CRLLoadFailureRetryTimeout
java.lang.Integer
900

The certificate-revocation list load-failure timeout (seconds).

CRLNoCRLLoadFailureRetryTimeout
java.lang.Integer
60

The certificate-revocation list load-failure retry timeout (seconds).

ClientAuthentication
java.lang.String
NEED

Indicates that clients need to be authenticated against certificates in the keystore.

EnabledCipherSuites
java.lang.String
None

Restrict the SSL cipher suites used by the RA to those set in this property. Valid values are a comma separated list of cipher suites installed in the JVM running Rhino.

Tip See Resource Adaptor Entities in the Rhino Administration and Deployment Guide for more information on creating and managing resource adaptor entities.

Deploy the SIP RA

After configuring default properties, you can deploy the SIP resource adaptor into the SLEE.

The Ant build script build.xml contains build targets for deploying and undeploying the SIP RA, as follows.

Deploy

To deploy the SIP RA, first ensure the SLEE is running, and then run build.xml with the target deploysipra. For example:

$ ant deploysipra

This script installs the SIP RA deployable unit and required libraries in the SLEE, and creates and activates the resource adaptor entity.

Undeploy

To undeploy the SIP RA, run build.xml with the target undeploysipra. For example:

$ ant undeploysipra

This script deactivates and removes the resource adaptor entity and uninstalls the SIP RA deployable unit.

Select and Deploy a Location Service

The sample SIP Registrar, Proxy, and Presence services require a location service, as defined by RFC3261 section 10. The location service stores SIP registrations, mapping a user’s public SIP address to actual contact addresses.

Tip If you don’t care how this is done, you can skip this step and use the default location service.

Below are instructions for selecting a location service, specifying an external database for the JDBC location service, and deploying the selected location service,

Selecting Activity Context Naming, JDBC, or Profile location services

Rhino’s SIP examples include three implementations of the location-service interface, which demonstrate different SLEE features:

  • Activity Context Naming (Default) — stores registration information in memory using null activities, looked up using the SLEE Activity Context Naming Facility. This is deployed by default.

  • JDBC — stores registrations in an external database.

  • Profile — stores registrations in a writeable SLEE 1.1 profile table.

Many other implementations are possible, such as LDAP.

The build.properties file specifies the type of location service that build.xml deploys. To select one of the three available implementations, edit build.properties, changing the locationservice property:

# The locationservice property should be set to one of "ac", "profile" or "jdbc".
# If undefined or a different value, defaults to "ac".
locationservice=ac

Using an external database for JDBC

If you select the JDBC location service, you’ll need to select a database other than the default, which uses Rhino’s embedded database (Apache Derby in the SDK and PostgreSQLin the production versions of Rhino).

To select an external database, you need to:

1

Create a table with the correct schema for the SIP Registrar

The SQL script fragment below demonstrates how to create the table. This works on PostgreSQL and may need to be adjusted to suit your particular database server.

create table registrations (
    sipaddress varchar(80) not null,
    contactaddress varchar(80) not null,
    expiry bigint,
    qvalue integer,
    cseq integer,
    callid varchar(80),
    flowid varchar(80),
    primary key (sipaddress, contactaddress)
);
COMMENT ON TABLE registrations IS 'SIP Location Service registrations';

2

Configure the JDBC data source in Rhino

Please see External Databases in the Rhino Administration and Deployment Guide for instructions on setting up an external data source.

3

Edit the JDBC location service’s deployment descriptor to refer to the new data source

Edit the extension deployment descriptor src/com/opencloud/slee/services/sip/location/jdbc/META-INF/oc-sbb-jar.xml. The data source is specified in the resource-ref element:

<resource-ref>
    <res-ref-name>jdbc/SipRegistry</res-ref-name>
    <res-type>javax.sql.DataSource</res-type>
    <res-auth>Container</res-auth>
    <res-sharing-scope>Shareable</res-sharing-scope>
    <res-jndi-name>jdbc/JDBCResource</res-jndi-name>
</resource-ref>
Note The res-jndi-name element must refer to a data source configured in rhino-config.xml (see External Databases).

Deploy the location service

Warning Normally you do not need to deploy the location service explicitly, since deploying the Registrar, Proxy, or Presence services will automatically deploy the location service as a dependency.

If necessary you can deploy a location service separately using the Ant target deploylocationservice. For example:

$ ant deploylocationservice

This will automatically deploy the location service that you specified in build.properties.

Deploy the Sample SIP Services

Below are instructions for preconfiguring the Proxy service (required before installing it), and then installing and uninstalling the Registrar, Proxy, and Presence services.

Preconfigure the Proxy service

Before you install the Proxy service, you must change one configuration item to suit your environment. Edit the sip.properties file, to change the PROXY_DOMAINS property as follows:

# Proxy SBB configuration
# Add domains that the proxy is authoritative for
PROXY_DOMAINS=opencloud.com,opencloud.co.nz
Warning The default domains opencloud.com and opencloud.co.nz are just examples — change this property to use the correct domains for your environment.

The PROXY_DOMAINS property contains the domains that the proxy SBB considers to be local. Depending on what domain the user to whom a request is addressed is in, the proxy SBB will do the following:

User’s domain What the proxy service does

One of the local domains (such as sip:bob@opencloud.com in our example).

Uses the location service to find the registered contact address of that user.

Local domain, but not registered in the location service.

Returns an error response.

Unknown domain.

Forwards the request according to normal SIP routing rules.

Install services

To install the SIP Registrar, Proxy or Presence service, first ensure the SLEE is running. Then go to the SIP examples directory and execute the Ant targets deployregistrar, deployproxy, or deploypresence. For example:

$ ant deployregistrar

These scripts:

  • compile the service source code

  • assemble jar files

  • deploy the service and its dependencies into the SLEE

  • activate the service.

Uninstall services

To deactivate and remove the services, use the Ant target undeployregistrar, undeployproxy, or undeploypresence. For example:

$ ant undeployregistrar

Using the Services

The following topics describe how to configure and use a SIP user agent with the sample Registrar, Proxy, and Presence services.

Note
What is a SIP user agent?

A "SIP user agent" means any SIP-capable device, such as a VoIP phone, softphone, or instant-messaging client. Some examples of user agents that have been used successfully with Rhino are:

The instructions in this section are intended to be generic and should apply to most user agents. Please see your user agent’s product documentation for specific installation and usage instructions.

Configure User Agents

Below are instructions for configuring typical network, SIP identity, and SIP server user-agent settings.

Warning
  • If you haven’t already, first deploy the sample SIP services on Rhino (see Quickstart or Manual Installation).

  • The following settings must be configured correctly before using the sample SIP services with Rhino (or any SIP server).

Default network port

A SIP user agent must listen on a network port, so that it can receive incoming calls or messages. The default port for SIP is 5060. Most user agents will attempt to use this port, and this is almost always the correct configuration.

However, if Rhino and a user agent are running on the same host, then there may be a conflict (because Rhino’s SIP resource adaptor defaults to port 5060 as well). If this is the case, you must change the port that either the SIP RA or the user agent uses. See Manual Installation for instructions on changing the port that the SIP RA uses.

If your user agent is running on a different host to Rhino, then no additional network configuration should be necessary.

SIP identity

Your SIP identity (sometimes called "address of record") is the public SIP address that you share with others so they can contact you. It is like your phone number or email address, and usually looks like sip:username@domain (for example, sip:bob@company.com).

When your user agent starts, it will register your SIP identity with the SIP server. The SIP server binds your SIP identity to the network address of your user agent (its contact address). This lets other users call you without knowing your user agent’s network address.

Unless you are integrating with an existing SIP network, the SIP identity you choose can be anything. However, the domain part of your identity (sip:bob@company.com) should be one of the domains known by the sample Proxy service (see the PROXY_DOMAINS property described in Quickstart). This is so the proxy service forwards requests to your user agent’s contact address.

SIP servers

You need to tell your user agent which SIP servers it will use. Depending on the particular user agent, you may have to configure several SIP server addresses, for different SIP services. (Often a user agent will just require a single server address that it uses for everything.)

The typical types of server that you may need to configure are:

Server What it does

Registrar

Receives registration and unregistration requests from your user agent, and updates a location service with your SIP identity and the user agent’s network address.

Proxy (or outbound proxy)

Receives messages or calls from the user agent, and figures out how to route them to their destination.

Presence

Provides the status of other users to the user agent (for example, for buddy lists), and lets it publish its own status information (such as "available", "busy", or "away").

Tip Some user agents may assume that the same server will provide all these services.

To configure your SIP servers, enter the address of your Rhino server in the appropriate fields. Often this will need to be in the form of a SIP URI. For example if Rhino is running on the machine rhino.company.com and using port 5060, then the SIP address of the server would be sip:rhino.company.com:5060.

Use the Registrar Service

Most SIP user agents will automatically try to register when they start up, by sending a REGISTER request.

This updates the Registrar with the user agent’s contact address. SIP registrations are not permanent, so the user agent will periodically refresh its registration with the Registrar. When the user agent shuts down, it will send another request to un-register its contact address.

The registration process is defined in RFC3261 section 10. When registering, refreshing or un-registering, the user agent sends a REGISTER request and expects to receive a 200 OK response, indicating that the operation succeeded:

User Agent          Registrar
    |                   |
    |      REGISTER     |
    |------------------>|
    |       200 OK      |
    |<------------------|
    |                   |
Tip You can enable tracing in Rhino to see the messages received by the Registrar service.

Use the Proxy Service

The role of the Proxy service is to route calls between user agents, so they do not need to know where the other user is located.

The Proxy service will obey SIP Route headers, and by default will insert Record-Route headers so that it stays on the path of a call. If a request does not contain any routing information, the Proxy will use RFC3263 DNS procedures to locate an appropriate server.

To test the Proxy service, you can have it set up a call between two user agents on the same network. The user agents should run on different hosts, so that their SIP ports do not conflict, nor their RTP ports (used for streaming audio or video during a call).

Below are instructions for using the Proxy service to place a call, along with a sample message flow.

Placing a call

The following procedure places a call between two user agents, routed through the Proxy service. We will assume the Rhino server is at the address sip:rhino.company.com:5060 and configured to use company.com as its domain. We will refer to the two user agents as A and B, with the SIP identities sip:alice@company.com and sip:bob@company.com respectively.

  1. Configure each user agent with server address sip:rhino.company.com:5060 and their SIP identities.

  2. Start the user agents and ensure they have registered successfully (the user agent should warn if registration failed).

  3. On user agent A, enter sip:bob@company.com as the destination address and place a call. This will send an INVITE message to the proxy.

  4. The proxy will lookup sip:bob@company.com in its location service, and route the call to user agent B.

  5. User agent B should indicate that it has a new incoming call.

  6. Answer the call on user agent B. This sends a SIP 200 OK response back to the proxy.

  7. The proxy forwards the response to user agent A.

  8. User agent A receives the response. A SIP dialog is now established and the users can talk to each other.

  9. Now one of the user agents can hang up the call. This sends a BYE message to the other user agent (through the proxy).

  10. The other user agent should send a 200 OK response back. The call is now terminated.

Message flow

The following diagram below shows the complete message flow for the test SIP call.

                  Proxy/
User A            Registrar             User B
  |      REGISTER     |                   |
  |------------------>|                   |
  |       200 OK      |                   |
  |<------------------|                   |
  |                   |      REGISTER     |
  |                   |<------------------|
  |                   |       200 OK      |
  |                   |------------------>|
  |       INVITE      |                   |
  |------------------>|                   |
  |                   |       INVITE      |
  |                   |------------------>|
  |                   |        1xx        |
  |                   |<------------------|
  |         1xx       |                   |
  |<------------------|                   |
  |                   |      200 OK       |
  |                   |<------------------|
  |       200 OK      |                   |
  |<------------------|                   |
  |        ACK        |                   |
  |------------------>|                   |
  |                   |        ACK        |
  |                   |------------------>|

          ... call established ...

  |        BYE        |                   |
  |------------------>|                   |
  |                   |        BYE        |
  |                   |------------------>|
  |                   |      200 OK       |
  |                   |<------------------|
  |       200 OK      |                   |
  |<------------------|                   |
Tip If at any point a message does not go through as expected, enable tracing on Rhino to see what the Proxy service is doing.

Use the Presence Service

You can use the SIP Presence service to enable the buddy list features of SIP clients that implement the SIP/SIMPLE specification.

Clients can view the online status of their registered contacts ("buddies"), and update their own online status for other clients to see. Many SIP clients require users' buddy lists to work before they can send instant messages — so the Presence service also enables sending instant messages for many SIP clients.

To use the Presence service, you need at least two SIP clients. They may be either different clients on a single host, or multiple instances of the same client on different hosts. (The same SIP client on different hosts may mean fewer interoperability issues, because many SIP clients only implement selected parts of the SIP/SIMPLE specification, or include custom extensions to the specification.)

Below are instructions for setting up SIP clients to demonstrate the Presence service, a sample message flow and details of basic and rich Presence.

Setup

Setting up the SIP clients to demonstrate the Presence service is similar to setting up to demonstrate the Registrar service:

  1. Start Rhino and deploy the Presence service.

  2. Start the clients you want to use.

  3. Create new SIP user accounts, pointing to the IP address and port that Rhino is using to run the Presence service.

  4. If the SIP clients implement the SIP/SIMPLE specification, you should then be able to add contacts to the buddy list, and send instant messages between clients.

Note

Some example SIP clients that can be used to demonstrate the Presence service are:

Sample message flow

The Presence service accepts SIP SUBSCRIBE and PUBLISH requests, and sends NOTIFY requests when appropriate.

The client sending SIP SUBSCRIBE requests lets user agents subscribe to the Presence information of other users (adding them as contacts in the "buddy list"). The client sending PUBLISH requests lets user agents publish changes to their own Presence state.

The Presence service responds by providing Presence information through NOTIFY requests. The Presence service amalgamates the Presence information available to it for any given user, and composes the information into a single Presence state for that user. When this composed Presence state changes (either by the user publishing a change to their status, or by registering or de-registering with the Registrar), the Presence service notifies any users who have subscribed to that information. Thus, if user A registers user B as a contact, an example SIP message flow could resemble the one below:

                    Presence
User A              Service               User B
    |      SUBSCRIBE    |                    |
    |------------------>|                    |
    |       200 OK      |                    |
    |<------------------|                    |
    |       NOTIFY      |                    |
    |<------------------|                    |
    |       200 OK      |                    |
    |------------------>|                    |
    |                   |                    |
    |                   |       PUBLISH      |
    |                   |<-------------------|
    |                   |        200 OK      |
    |                   |------------------->|
    |                   |                    |
    |       NOTIFY      |                    |
    |<------------------|                    |
    |       200 OK      |                    |
    |------------------>|                    |

The Presence service responds to the user A’s initial SUBSCRIBE request with a NOTIFY containing the current Presence information of user B, and informs user A with a further NOTIFY request when user B’s Presence state changes.

Basic Presence

At the most basic level, Presence describes whether or not a client is online or offline. The Presence service determines the basic Presence state of users from any PUBLISH requests it has received from the user’s client, and through determining whether the user is registered as online with the Registrar.

Many SIP clients implement basic Presence. You can demonstrate this using two clients on a single host.

Note WengoPhone, Windows Messenger, Pidgin, and X-Lite are all SIP clients that implement basic Presence. Most of them will either use SIP/SIMPLE by default, or will have SIP/SIMPLE listed as a protocol that they support.

To demonstrate the use of basic Presence:

  1. Start Rhino and deploy the Presence service.

  2. Set up two (or more) clients to use the Rhino host running the Presence service (identified by the Rhino host’s IP address and port) as their SIP server. The clients may either be on different hosts, or all on the same host.

  3. Make sure that each client has a unique user account, and ensure that each one successfully registers with the Registrar.

  4. In each client, add the other client accounts as contacts in the buddy list. The online status of the other client accounts should automatically display in the buddy list as either online or offline as appropriate.

  5. Register or deregister one of the clients (log on or off). The online status of that client should change from online to offline (or vice versa) in the buddy lists of the other clients.

Once the buddy list feature of the clients is working, most clients will also allow instant messages. Note that there are exceptions (for example, Microsoft Messenger uses proprietary extensions to the messaging part of the protocol, and will not exchange instant messages).

Rich Presence

The SIP/SIMPLE protocol also lets clients share more detailed Presence information. The Presence service implements the Presence information data format set out in RFC3863, "application/pidf+xml", which lets them communicate an extra layer of information (above the basic states of online and offline — for example publishing states such as "On the phone").

Note
Use instances of the same client

The extra layer of Presence information has been left entirely open to implementations — there are no standard states (as is the case with basic Presence). Many clients do not implement this part of the protocol, and many add extensions to it. Because of these differences, using different clients to demonstrate extended Presence can therefore be difficult.

To demonstrate the use of extended Presence information with the Presence service, you can set up two instances of WengoPhone on separate hosts:

  1. Start Rhino and deploy the Presence service.

  2. Configure two instances of WengoPhone, each on separate hosts, to use the Rhino host running the Presence service as their SIP server.

  3. In each client, add the other account as a contact in the buddy list. The status of each account should automatically update, once it has been added into the buddy list.

  4. Set the status of one of the clients to "Away" or "Do Not Disturb", by clicking on the circular button to the left of the account’s user name, and selecting the option from the drop-down list. The new status of the account should display in the buddy list of the other client.

Once the client’s buddy lists work, they should be able to exchange instant messages.

Enable Tracing for SIP Services

The SIP services can write tracing information to the Rhino SLEE logging system using the SLEE trace facility.

This is useful for understanding what the various services are doing.

Enabling tracing for a particular SBB

To enable tracing output for a particular SBB, use the setTraceLevel command in rhino-console, as follows:

user@host:~/rhino$ client/bin/rhino-console
Connecting as user admin
Interactive Rhino Management Shell
Rhino management console, enter 'help' for a list of commands
[Rhino@localhost (#0)] settracerlevel sbb service=ServiceID[name=SIP\ Proxy\ Service,
    vendor=OpenCloud,version=1.8],sbb=SbbID[name=ProxySbb,
    vendor=OpenCloud,version=1.8] root finest
Set trace level of SbbNotification[service=ServiceID[name=SIP Proxy Service,
    vendor=OpenCloud,version=1.8],sbb=SbbID[name=ProxySbb,
    vendor=OpenCloud,version=1.8]] root tracer to finest
[Rhino@localhost (#1)]

Enabling tracing for all SBBs

You can also enable tracing for all SBBs, and also the SIP RA, by modifying these settings in build.properties:

# Default SBB/RA trace levels
# Possible values: Off, Severe, Warning, Config, Info, Fine, Finer, Finest.
sbb.tracelevel=Info
ra.tracelevel=Info
Tip To apply the new trace levels, redeploy the services or ra.