JBoss Communications Platform 5.0 SIP Presence Service User Guide

Transcription

1 JBoss Communications Platform 5.0 SIP Presence Service User Guide The Guide to the SIP Presence Service Edition Eduardo Martins Tom Wells Jared Morgan Douglas Silas Ivelin Ivanov

2 JBoss Communications Platform 5.0 SIP Presence Service User Guide The Guide to the SIP Presence Service Edition Eduardo Martins m Tom Wells m Jared Mo rgan jmo m Do uglas Silas m Ivelin Ivano v iivano v@redhat.co m

3 Legal Notice Copyright 2010 Red Hat, Inc. T his document is licensed by Red Hat under the Creative Commons Attribution-ShareAlike 3.0 Unported License. If you distribute this document, or a modified version of it, you must provide attribution to Red Hat, Inc. and provide a link to the original. If the document is modified, all Red Hat trademarks must be removed. Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law. Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, MetaMatrix, Fedora, the Infinity Logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries. Linux is the registered trademark of Linus Torvalds in the United States and other countries. Java is a registered trademark of Oracle and/or its affiliates. XFS is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries. MySQL is a registered trademark of MySQL AB in the United States, the European Union and other countries. Node.js is an official trademark of Joyent. Red Hat Software Collections is not formally related to or endorsed by the official Joyent Node.js open source or commercial project. T he OpenStack Word Mark and OpenStack Logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community. All other trademarks are the property of their respective owners. Abstract T he JBoss Communications Platform (JBCP), is the first and only open source VoIP platform certified for JAIN SLEE 1.1 and SIP Servlets 1.1 compliance. JBCP serves as a high-performance core for Service Delivery Platforms (SDPs) and IP Multimedia Subsystems (IMSs) by leveraging J2EE to enable the convergence of data and video in Next-Generation Intelligent Network (NGIN) applications. JBCP enables the composition of predefined Service Building Blocks (SBBs) such as Call-Control, Billing, User- Provisioning, Administration and Presence-Sensing. Out-of-the-box monitoring and management of JBCP components is achieved through JMX Consoles. JSLEE allows popular protocol stacks such as SIP to be plugged in as Resource Adapters (RAs), and Service Building Blocks which share many similarities with EJBs allow the easy accommodation and integration of enterprise applications with end points such as the Web, Customer Relationship Management (CRM) systems and Service-Oriented Architectures (SOAs). T he JBCP is the natural choice for telecommunication Operations Support Systems (OSSs) and Network Management Systems (NMSs). In addition to the telecommunication industry, JBCP is suitable for a variety of problem domains demanding an Event-Driven Architecture (EDA) for high-volume, low-latency signaling, such as financial trading, online gaming, (RFID) sensor network integration, and distributed control.

4 Table of Contents Table of Contents. Preface Document Conventions T ypographic Conventions Pull-quote Conventions Notes and Warnings 5 2. We Need Feedback 5. Chapter Introduction to... the.... JBCP SIP.... Presence Service Architecture of the SIP Presence Service 7. Chapter Installing the.... SIP.... Presence Service Chapter XML..... Document Management Server Functional Architecture of the XDM Server Implementation Architecture of the XDM Server Configuring the XDM Server Configuring the XDM Server XCAP root Configurable Features of the XDM Server XCAP Interface Configuring the XDM Server XCAP Diff SIP Subscription Interface Configuring the XDM Server Users 16. Chapter Resource List..... Server Chapter SIP.... Presence Server Functional Architecture of the SIP Presence Server Implementation Architecture of the SIP Presence Server Resource List Server Configuring the SIP Presence Server Configuring the Abstract SIP Event Publication Interface Configuring the Abstract SIP Event Subscription Interface Configuring the Concrete SIP Event Interfaces 22. Revision History Index

5 2 JBoss Communications Platform 5.0 SIP Presence Service User Guide

6 Preface Preface 1. Document Conventions T his manual uses several conventions to highlight certain words and phrases and draw attention to specific pieces of information. In PDF and paper editions, this manual uses typefaces drawn from the Liberation Fonts set. T he Liberation Fonts set is also used in HTML editions if the set is installed on your system. If not, alternative but equivalent typefaces are displayed. Note: Red Hat Enterprise Linux 5 and later include the Liberation Fonts set by default Typographic Conventions Four typographic conventions are used to call attention to specific words and phrases. T hese conventions, and the circumstances they apply to, are as follows. Mono-spaced Bold Used to highlight system input, including shell commands, file names and paths. Also used to highlight keys and key combinations. For example: T o see the contents of the file m y_next_bestselling_novel in your current working directory, enter the cat m y_next_bestselling_novel command at the shell prompt and press Enter to execute the command. The above includes a file name, a shell command and a key, all presented in mono-spaced bold and all distinguishable thanks to context. Key combinations can be distinguished from an individual key by the plus sign that connects each part of a key combination. For example: Press Enter to execute the command. Press Ctrl+Alt+F2 to switch to a virtual terminal. T he first example highlights a particular key to press. T he second example highlights a key combination: a set of three keys pressed simultaneously. If source code is discussed, class names, methods, functions, variable names and returned values mentioned within a paragraph will be presented as above, in m ono-spaced bold. For example: File-related classes include filesystem for file systems, file for files, and dir for directories. Each class has its own associated set of permissions. Proportional Bold T his denotes words or phrases encountered on a system, including application names; dialog box text; labeled buttons; check-box and radio button labels; menu titles and sub-menu titles. For example: Choose System Preferences Mouse from the main menu bar to launch Mouse Preferences. In the Buttons tab, select the Left-handed m ouse check box and click Close to switch the primary mouse button from the left to the right (making the mouse suitable for use in the left hand). T o insert a special character into a gedit file, choose Applications Accessories 3

7 JBoss Communications Platform 5.0 SIP Presence Service User Guide Character Map from the main menu bar. Next, choose Search Find from the Character Map menu bar, type the name of the character in the Search field and click Next. T he character you sought will be highlighted in the Character T able. Double-click this highlighted character to place it in the T ext to copy field and then click the Copy button. Now switch back to your document and choose Edit Paste from the gedit menu bar. T he above text includes application names; system-wide menu names and items; application-specific menu names; and buttons and text found within a GUI interface, all presented in proportional bold and all distinguishable by context. Mono-spaced Bold Italic or Proportional Bold Italic Whether mono-spaced bold or proportional bold, the addition of italics indicates replaceable or variable text. Italics denotes text you do not input literally or displayed text that changes depending on circumstance. For example: T o connect to a remote machine using ssh, type ssh username@ domain.name at a shell prompt. If the remote machine is example.com and your username on that machine is john, type ssh john@ exam ple.com. T he m ount -o rem ount file-system command remounts the named file system. For example, to remount the /home file system, the command is mount -o remount /home. T o see the version of a currently installed package, use the rpm -q package command. It will return a result as follows: package-version-release. Note the words in bold italics above username, domain.name, file-system, package, version and release. Each word is a placeholder, either for text you enter when issuing a command or for text displayed by the system. Aside from standard usage for presenting the title of a work, italics denotes the first use of a new and important term. For example: Publican is a DocBook publishing system Pull-quote Conventions T erminal output and source code listings are set off visually from the surrounding text. Output sent to a terminal is set in mono-spaced roman and presented thus: books Desktop documentation drafts mss photos stuff svn books_tests Desktop1 downloads images notes scripts svgs Source-code listings are also set in m ono-spaced rom an but add syntax highlighting as follows: 4

8 Preface package org.jboss.book.jca.ex1; import javax.naming.initialcontext; public class ExClient { public static void main(string args[]) throws Exception { InitialContext inictx = new InitialContext(); Object ref = inictx.lookup("echobean"); EchoHome home = (EchoHome) ref; Echo echo = home.create(); System.out.println("Created Echo"); } } System.out.println("Echo.echo('Hello') = " + echo.echo("hello")); 1.3. Notes and Warnings Finally, we use three visual styles to draw attention to information that might otherwise be overlooked. Note Notes are tips, shortcuts or alternative approaches to the task at hand. Ignoring a note should have no negative consequences, but you might miss out on a trick that makes your life easier. Important Important boxes detail things that are easily missed: configuration changes that only apply to the current session, or services that need restarting before an update will apply. Ignoring a box labeled 'Important' will not cause data loss but may cause irritation and frustration. Warning Warnings should not be ignored. Ignoring warnings will most likely cause data loss. 2. We Need Feedback If you find a typographical error in this manual, or if you have thought of a way to make this manual better, submit a report in Bugzilla: against the JBoss Communication Platform. When submitting a bug report, be sure to mention the manual's identifier: doc- SIP_Presence_Service_User_Guide If you have a suggestion for improving the documentation, try to be as specific as possible when describing it. If you have found an error, please include the section number and some of the surrounding 5

9 JBoss Communications Platform 5.0 SIP Presence Service User Guide text so we can find it easily. 6

10 Chapter 1. Introduction to the JBCP SIP Presence Service Chapter 1. Introduction to the JBCP SIP Presence Service Figure 1.1. JBCP SIP Presence Service relationship with standards groups T he JBCP SIP Presence Service provides presence functionalities to SIP-based networks using standards developed by the Internet Engineering T ask Force (IET F), the Open Mobile Alliance (OMA), the 3rd Generation Partnership Project (3GPP) and the European T elecommunications Standards Institute (ET SI) Architecture of the SIP Presence Service T he SIP Presence Service is comprised of three separate but interrelated servers. Figure 1.2. JBCP SIP Presence Service servers The SIP Presence Server The JBCP SIP Presence Server (PS) is an entity that accepts, stores and distributes SIP Presence information. T he Presence Server performs the following functions: Manages publications from one or multiple presence source(s) of a certain presentity. T his includes refreshing presence information, replacing existing presence information with newly-published information, or removing presence information. 7

11 JBoss Communications Platform 5.0 SIP Presence Service User Guide Manages subscriptions from watchers to presence information and generates notifications about presence information state changes, retrieving the presence authorization rules from the XDM Server. Manages subscriptions from watcher information subscribers to watcher information and generates notifications about watcher information state changes. T he XML Document Management Server T he XML Document Management Server (XDMS) is a functional element of next-generation IP communications networks. It is responsible for handling the management of user XML documents stored on the network side, such as presence authorization rules, static presence information, contact and group lists (also known as resource lists ), policy data, and many others. T he Resource List Server T he Resource List Server (RLS) handles subscriptions to presence lists. It creates and manages back-end subscriptions to all resources in the presence list. T he list content is retrieved from the XDM Server. Figure 1.3. JBCP SIP Presence Service Integrated server A major advantage of the JBCP SIP Presence Service is that, depending on your needs, each server can be deployed separately, or all servers can be integrated on the same host. The JBCP SIP Presence Service is built on top of JBCP JAIN SLEE, a high performance and scalable Application Server, and uses many additional Java Enterprise (JEE) technologies, such as Java Persistence API (JPA) to manage data. 8

12 Chapter 1. Introduction to the JBCP SIP Presence Service Figure 1.4. JBCP SIP Presence Service Integrated implementation In addition, there are JAIN SLEE internal client interfaces available for interaction with each server, which distinguish the JBCP SIP Presence Service from other presence services. 9

13 JBoss Communications Platform 5.0 SIP Presence Service User Guide Chapter 2. Installing the SIP Presence Service T he SIP Presence Service is installed as part of the JBoss Communications Platform. For system requirements, configuration options, and installation instructions, please refer to the Platform Installation Guide. 10

14 Chapter 3. XML Document Management Server Chapter 3. XML Document Management Server T he JBCP XML Document Management Server (XDM Server) is responsible for handling the management of user XML documents stored on the network side, such as presence authorization rules, contact and group lists (also known as resource lists), and static presence information Functional Architecture of the XDM Server T he JBCP XDM Server includes the following XML Configuration Access Protocol (XCAP) application usages: IET F Presence Rules (RFC 5025) OMA Presence Rules (OMA Presence Simple v1.1 Candidate Release) IET F Resource Lists IET F RLS Services (RFC 4826) IET F XCAP-CAPS (RFC 4825) T he SIP interface partially implements the XCAP Diff Event IET F draft, version 3. Subscriptions to a single document or usage by an entire application are supported. However, these differing usages do not extend to the single-xml element or attribute value level. If the diff-processing subscription parameter is present for notifications, it is currently ignored. Note Patching of content is not available at the moment, which means that only the document etags will be provided. 11

15 JBoss Communications Platform 5.0 SIP Presence Service User Guide Figure 3.1. T he JBCP XML Document Management Server T he XDM Server comprises the following functional elements: Data Source T he XDM Server data source is where all user XML documents are stored. Information related to the server itself is also stored in this element along with the user's provisioned data. T he data source also handles subscriptions to updates on specific documents, or complete XCAP application usages. Aggregation Proxy T he aggregation proxy is responsible for handling an XDM client's XCAP requests, which includes authentication of the requester. Request Processor This element includes the XCAP Server logic to process an XCAP request and return a proper response, including authorization for the authenticated user. XDM Event Subscription Control T his element, using the SIP protocol, is responsible for handling subscriptions to documents managed by the XDM. Its functions include the authentication and authorization of a 12

16 Chapter 3. XML Document Management Server subscription, attachment to update events on specific documents or application usages, and the sending of notifications when documents change Implementation Architecture of the XDM Server The XDM Server is built on top of the JBCP JAIN SLEE container. The image below depicts the architecture of the XDM Server implementation. Figure 3.2. XML Document Management Server Implementation The Functional Elements of the XDM Server Data Source Resource Adapter T his resource adapter implements the Data Source functional element. T he RA T ype defines two activity objects, Docum entactivity and AppUsageActivity, both of which are used to fire events that signal that a document, element or attribute was updated. The RA Type also defines a Service Building Block (SBB) RA interface to manage the users and documents stored in the XDM Server, and create activities where events will be fired. T he resource adapter will only fire events on activities that exist; the RA won't create activities implicitly if a document is updated. 13

17 JBoss Communications Platform 5.0 SIP Presence Service User Guide T he RA T ype also provides a base abstract implementation of the resource adapter, making it very simple to change the underlying resource used to store information, which is by default the internal JDBC datasource of the JBoss Application Server. AppUsage Cache Resource Adaptor T his resource adapter stores the XCAP application usages installed in the server. Each AppUsage is an object that includes the logic to validate XCAP documents that result from XCAP requests. T he resource adapter does not possess events or activities. AppUsage Service XCAP Application Usages are installed through a JAIN SLEE service, making it possible to add or remove application usages while the server is running. Aggregation Proxy Service T his JAIN SLEE service implements the aggregation proxy functional element. It handles events fired by the JBCP HTTP Servlet resource adapter and then uses two child SBBs: the User Profile Enabler SBB to retrieve information regarding the user needed for authentication/authorization of the XCAP request, and the Request Processor SBB, which handles the XCAP request. Request Processor SBB T he Request Processor SBB implements the request processor functional element, providing a synchronous SBB interface to process XCAP requests. It uses the AppUsage Cache resource adapter to borrow AppUsage objects, and the Data Source resource adapter to retrieve or set documents stored in the server's data source. User Profile Enabler SBB This SBB provides a synchronous SBB interface used in JAIN SLEE child relations in order to retrieve user information, to be used on user authentication. T wo different implementations of the interface are provided: the first considers whether the information is stored in the XDM Data Source, and the second interfaces with a Diameter Sh Server, such as IMS HSS. XCAP Diff Subscription Control Service T his JAIN SLEE Service extends the abstract SIP Event Subscription Control component to handle SIP subscriptions on the xcap-diff event package. T he implementation architecture figure also contains client-side components: XCAP Client The XCAP client is a simple API to interact with an XCAP Server that internally uses the Apache HTTP Client. 14 XCAP Client Resource Adaptor The XCAP Client Resource Adapter adapts the XCAP Client API into the JAIN SLEE domain. It

18 Chapter 3. XML Document Management Server provides methods to interact with the XCAP server in both synchronous and asynchronous ways. XDM Client SBB The XDMClientSBB is an interface of a JAIN SLEE SBB to be used as a client to the JBCP XDM Server, and others compliant with same standards, in JAIN SLEE child relations. T wo implementations of this interface are provided: InternalXDMClientSBB is intended to be used on applications running in the JBCP XDM Server JAIN SLEE container, and ExternalXDMClientSBB is intended to be used on applications in a different JAIN SLEE container than the JBCP XDM Server Configuring the XDM Server Configuring the XDM Server XCAP root T he JBCP XDM Server comes pre-configured for an XCAP root of It is possible to configure <localhost>, the port and the last path segment. Rename $JBOSS_HOME/server/<server_profile>/deploy/m obicents.war to the desired last path segment in the XCAP root (e.g. rename to xcap-root.war for an XCAP root of T he <server_profile> is the server configuration used in the underlying JBoss AS which is initially set as default. Edit the deploy-config.xml file in the $JBOSS_HOME/server/<server_profile>/deploy/http-servlet-ra-DU-*.jar/MET A- INF/deploy-config.xm l directory. Uncomment and set the custom servlet name again to the desired last path segment in the XCAP root. Edit the properties in the jboss-beans.xml file in the $JBOSS_HOME/server/<server_profile>/deploy/m obicents-xdm s/3- beans/configuration/xdm s/met A-INF directory. Note that the xcaproot has a leading /. This configuration part can also be done through JMX, using the MBean named org.mobicents.slee:sippresence=xdmserverconfiguration. T he configuratian changes through JMX are not persistent Configurable Features of the XDM Server XCAP Interface T here are other configurable features related with the XCAP Interface: Edit the properties in the jboss-beans.xml file in the $JBOSS_HOME/server/<server_profile>/deploy/m obicents-xdm s/3- beans/configuration/xdm s/met A-INF/ directory. This configuration part can also be done through JMX, using the org.mobicents.slee:sippresence=xdmserverconfiguration MBean. Note T he configuratian changes through JMX are not persistent. 15

19 JBoss Communications Platform 5.0 SIP Presence Service User Guide Configuring the XDM Server XCAP Diff SIP Subscription Interface T here are several features of the JBCP XDM Server SIP Interface that can be configured, including the subscription timers. Edit the properties in the jboss-beans.xml file, in the $JBOSS_HOME/server/<server_profile>/deploy/m obicents-xdm s/3- beans/configuration/sip-event /subscription/meta-inf/ file. This configuration part can also be done through JMX, using the org.mobicents.slee:sippresence=sipeventsubscriptioncontrol MBean. Note T he configuratian changes through JMX are not persistent Configuring the XDM Server Users The XCAP interface is public, used by users to manage information such as their buddy list, presence authorization rules, etc. It needs to enforce user authentication. T o set user authentication, the server relies on the User Profile Enabler managed data, such as the users passwords, and this information must be provisioned. This can be done in two ways, both requiring the server to be running: User Provisioning through a JMX Client Users can be added/removed through the org.mobicents.slee:userprofile=userprofilecontrol MBean. User Provisioning through the JBoss AS default datasource. Users can be added/removed through adding/removing rows from the MOBICENTS_SLEE_ENABLER_USERPROFILES table. 16

20 Chapter 4. Resource List Server Chapter 4. Resource List Server T he Resource List Server (RLS) handles subscriptions to presence lists. It creates and manages backend subscriptions to all resources in the presence list. T he list content is retrieved from the XDM Server. It is currently tightly integrated with the SIP Presence Server, supporting RFC 5367 and the OMA service URI template. 17

21 JBoss Communications Platform 5.0 SIP Presence Service User Guide Chapter 5. SIP Presence Server T he JBCP SIP Presence Server (PS) is an entity that accepts, stores and distributes SIP Presence information. T he Presence Server performs the following functions: Manages publications from one or more presence source(s) of a certain presentity. T his includes refreshing presence information, replacing existing presence information with newly-published information, or removing presence information. Manages subscriptions from watchers to presence information and generates notifications about presence information state changes, and retrieves the presence authorization rules from the XDM Server. Manages subscriptions from watcher information subscribers to watcher information and generates notifications about watcher information state changes Functional Architecture of the SIP Presence Server Figure 5.1. Architecture of the SIP Presence Server T he SIP Presence Server is comprised of the following functional elements: 18 Presence Publication Control Manages the publication of presence events, which includes not only the handling of new publications, but also the refreshing, modification or removal of already-published information.

22 Chapter 5. SIP Presence Server Because the presence resource, which is also called a presentity, can have multiple publications simultaneously, such as some states published by a user agent or device, and some location data published by a Presence Network Agent (on behalf of the presentity), this element is also responsible for composing all of the different publications for the same resource. In some presence networks, it may be of interest to allow resources to have a static presence state which is stored in the XDM Server. In cases like these, Presence Publication Control may need to interface with the XDM Server to retrieve and subscribe to (learn about changes to) that information, and use it when composing the final presence information document. Presence Subscription Control T his functional element handles subscriptions to presence events or to the list of subscribers (watchers), for any specific resource. It is, of course, responsible for emitting notifications related to those subscriptions. Presence authorization rules, which define if a subscription is allowed or rejected and, if allowed, define which transformations to the original presence events are needed, are stored on the XDM Server by the user. Thus, Presence Subscription Control needs to retrieve and subscribe to that information. XDM Client Control T his last element is responsible for interfacing with the XDM Server that manages the user's XML documents, and is related to the main functions of the presence server. It is capable not only of retrieving a document or part of one, but also of subscribing to either updates of a single, specific document, or to a full collection of documents of a specific type or application. 19

23 JBoss Communications Platform 5.0 SIP Presence Service User Guide Figure 5.2. Implementation Architecture of the SIP Presence Server T he implementation of the SIP Presence Server comprises the following functional elements: The Two Services Which Compose the SIP Presence Server 20 Presence Publication Control Service This JAIN SLEE service includes the root Service Building Block (SBB), PresencePublicationControlSbb, which is the implementation of the abstract SIP event PublicationControlSbb. It handles publications on the presence event package. T he PresencePublicationControlSbb provides the following capabilities: It provides the logic to authorize a publication; however, it only authorizes PUBLISH requests when the request URI matches the PIDF document entity attribute. It provides JAXB unmarshallers to validate and parse the PIDF document for the abstract PublicationControlSbb. It demands that notifying subscribers occur through a child relation to the root SBB of the

24 Chapter 5. SIP Presence Server It demands that notifying subscribers occur through a child relation to the root SBB of the Presence Subscription Control Service. Finally, it also provides an SbbLocalObject interface that can be used, in JAIN SLEE child relations, to obtain the composed presence information for a specific resource. Presence Subscription Control Service. T his JAIN SLEE service includes the root SBB PresenceSubscriptionControlSbb, which is the implementation of the abstract SIP Event SubscriptionControlSbb. It handles subscriptions on the presence event package. T he standout SBB logic item is the usage of presence-rules documents, obtained through the XDM Client SBB child relation, in order to authorize subscriptions and transform the content notified [1]. It also defines a child relation to the root SBB of PresencePublicationService to retrieve the composed PIDF document for the subscription's notifier. T he SBB also provides an SbbLocalObject interface that can be used, in JAIN SLEE child relations, to make the presence event known to the subscribers of a specific resource. T he implementation architecture of the SIP Presence Server also contains client-side components: Presence Client SBB The PresenceClientSBB is the interface to a JAIN SLEE SBB intended to be used as a client for the SIP Presence Server (and other servers compliant with same standards), in JAIN SLEE child relations. T wo implementations of this interface are provided: the InternalPresenceClientSBB that is used with applications running in the SIP Presence Server JAIN SLEE container, and the ExternalPresenceClientSBB, used with applications running in a different JAIN SLEE container than the SIP Presence Server Resource List Server T he Resource List Server is currently tightly integrated with the SIP Presence Server, supporting RFC 5367 and OMA service uri template Configuring the SIP Presence Server Several features of the SIP Presence Server are configurable, through XML files or JMX Configuring the Abstract SIP Event Publication Interface Edit the properties in the jboss-beans.xml file, in the $JBOSS_HOME/server/<server_profile>/deploy/m obicents-sip-presence/3- beans/configuration/ sip-event/publication/meta-inf/. This configuration part can also be done through JMX, using the MBean named org.mobicents.slee:sippresence=sipeventpublicationcontrol. T he configuratian changes through JMX are not persistent Configuring the Abstract SIP Event Subscription Interface 21