Survey
* Your assessment is very important for improving the workof artificial intelligence, which forms the content of this project
Download Administering Presence Services XCP Controller
Document related concepts
no text concepts found
Transcript
Administering Presence Services XCP Controller August 2010 Contents Chapter 1: Using the Presence XCP Controller......................................................................9 Starting the Presence XCP Controller...............................................................................................................9 Using Linux...............................................................................................................................................9 Using web access...........................................................................................................................................10 Configuration views.........................................................................................................................................11 XCP Controller interface.................................................................................................................................12 System....................................................................................................................................................12 Router.....................................................................................................................................................13 Components...........................................................................................................................................13 Chapter 2: Router....................................................................................................................15 About Router Area..........................................................................................................................................15 Global Router settings.....................................................................................................................................16 Cluster....................................................................................................................................................17 Realm.....................................................................................................................................................18 MDNS.....................................................................................................................................................18 Log level.................................................................................................................................................19 Obscure Plaintext Passwords.................................................................................................................20 Advanced Performance Tuning options..................................................................................................20 Master Accept port.................................................................................................................................20 Database setup......................................................................................................................................22 Enabling SNMP......................................................................................................................................23 Mutually Trusted TLS Host Names.........................................................................................................24 Chapter 3: Logging..................................................................................................................25 Logging...........................................................................................................................................................25 Configuring Syslog for Red Hat Linux....................................................................................................26 Setting the Log Level for Router-Generated Packets.............................................................................26 Jabberd Logger Configuration................................................................................................................28 JSM Logging...........................................................................................................................................35 Message Archiver Logging.....................................................................................................................37 Statistics Logging...................................................................................................................................38 Component Logging (Jlog).....................................................................................................................39 Presence Services logging.....................................................................................................................42 Changing logging levels.........................................................................................................................43 Collecting logs........................................................................................................................................44 System Manager Alarm and Logging.....................................................................................................45 Chapter 4: Presence Session Manager (JSM)......................................................................47 Optional modules............................................................................................................................................48 JSM hostnames..............................................................................................................................................48 Presence Administrators.................................................................................................................................49 Unregistering users................................................................................................................................49 Deleting Offline messages......................................................................................................................50 Locating Inactive accounts.....................................................................................................................50 Broadcasting messages to all users.......................................................................................................51 System limits...................................................................................................................................................53 System parameters.........................................................................................................................................53 Database setup option....................................................................................................................................54 Administering Presence Services XCP Controller August 2010 3 JSM features...................................................................................................................................................56 Stats................................................................................................................................................................56 Agents.............................................................................................................................................................57 Legacy redirect to external components.........................................................................................................57 Static EventBroker events...............................................................................................................................57 Configuring JDS..............................................................................................................................................58 Configuring Roster..........................................................................................................................................59 Configuring Sendmail......................................................................................................................................59 Configuring Offline SMTP................................................................................................................................60 Configuring Registration Requirements..........................................................................................................61 Authorization...................................................................................................................................................62 JSM Logging...................................................................................................................................................62 Configuring HTTP Digest Module...................................................................................................................63 Configuring personal eventing........................................................................................................................63 Configuring SNMP..........................................................................................................................................64 Chapter 4: Authorization.........................................................................................................65 Authz Authorization.........................................................................................................................................65 XCP Server Configuration......................................................................................................................65 Authorization Protocol............................................................................................................................69 Design Notes..........................................................................................................................................72 Security Considerations..........................................................................................................................73 Licensing.........................................................................................................................................................78 Chapter 5: Access...................................................................................................................81 EventBroker....................................................................................................................................................81 Configuring the EventBroker for the Presence Session Manager..........................................................82 Configuring the EventBroker for Text Conferencing...............................................................................83 OpenPort Configuration..........................................................................................................................84 Example Component..............................................................................................................................85 Protocol: Event Access from External Components...............................................................................89 InfoBroker......................................................................................................................................................118 Planning Your Deployment...................................................................................................................119 InfoBroker Configuration.......................................................................................................................119 Creating and Publishing to Nodes........................................................................................................122 Data Drivers..........................................................................................................................................123 XEP-60 Compliance.............................................................................................................................124 Example Implementations....................................................................................................................126 InfoBroker Parameter Reference..........................................................................................................128 Category Parameter Reference............................................................................................................132 Chapter 7: Connection managers........................................................................................137 Verifying Connection Manager certificates....................................................................................................137 Adding and configuring an additional Connection Manager..........................................................................138 Chapter 8: File Transfer Proxy.............................................................................................141 Configuring the Basic File Transfer Proxy.....................................................................................................141 To configure the File Transfer Proxy.....................................................................................................141 File Transfer Proxy Parameter Reference.....................................................................................................142 Basic Parameters.................................................................................................................................142 Intermediate Parameters......................................................................................................................143 Advanced Parameters..........................................................................................................................144 4 Administering Presence Services XCP Controller August 2010 Chapter 9: OCS Gateway......................................................................................................147 Verifying OCS Gateway certificates..............................................................................................................147 Configuring a Server-to-Server Connection Manager...................................................................................148 Configuring the OCS Gateway......................................................................................................................149 Adding an Outgoing Connection Attempt Rule in the S2SCP.......................................................................152 Configuring an OpenPort connection............................................................................................................153 Configuring Jabber administrators................................................................................................................153 Chapter 10: Server-to-Server connections.........................................................................155 Configuring the Basic S2S Connection Manager..........................................................................................155 Configuring the OpenPort connection...........................................................................................................156 Configuring the dialback password...............................................................................................................157 Blacklisting and Whitelisting Hosts and IP Addresses..................................................................................158 Discovery Protocol for Querying the S2S Command Processor...................................................................159 Example: Querying the S2SCP for information....................................................................................159 Example: Querying for outbound and inbound lists..............................................................................159 Example: Querying S2CP for all items.................................................................................................160 Chapter 11: Active Directory................................................................................................161 Configuring the Active Directory component.................................................................................................161 Configuring a Directory Server to work with Active Directory...............................................................162 Configuring a database........................................................................................................................163 Configuring the JSM to use the Active Directory component........................................................................165 Chapter 12: Jabber Directory and LDAP.............................................................................167 Configuring the Jabber Directory component................................................................................................167 Configuring a Directory Server.............................................................................................................168 Configuring an LDAP Database...........................................................................................................169 Configuring the JSM to use the Jabber Directory Component......................................................................172 Jabber LDAP objectClasses and Attributes..................................................................................................173 Directory Server optimization........................................................................................................................174 Chapter 13: LaunchBroker...................................................................................................175 Configuring the LaunchBroker Component...................................................................................................175 To configure the LaunchBroker component..........................................................................................175 Configuring the WebEx Collaboration Command..........................................................................................176 To configure the WebEx Collaboration Command................................................................................176 Configuring the Adobe Acrobat Connect Professional Command ................................................................177 Setting up Adobe Connect Server........................................................................................................177 To configure the Adobe Acrobat Connect Professional command .......................................................178 Configuring a Custom LaunchBroker Command..........................................................................................179 To configure a custom command..........................................................................................................179 LaunchBroker Parameter Reference............................................................................................................180 Basic Parameters.................................................................................................................................180 Intermediate Parameters......................................................................................................................181 Advanced Parameters..........................................................................................................................182 Chapter 14: Message Archiver.............................................................................................185 Configuring Message Archive.......................................................................................................................185 Configuring the Presence Session Manager.................................................................................................186 Retrieving Message Archiver Data................................................................................................................187 Incoming and outgoing messages........................................................................................................188 Administering Presence Services XCP Controller August 2010 5 Files transfer requests..........................................................................................................................189 Chapter 16: Presence Mirror................................................................................................197 Configuring the Presence Mirror Component................................................................................................197 To configure the Presence Mirror.........................................................................................................197 Configuring the Presence Session Manager.................................................................................................198 To configure the Presence Session Manager.......................................................................................198 Presence Mirror Parameter Reference.........................................................................................................199 Intermediate Parameters......................................................................................................................199 Advanced Parameters..........................................................................................................................201 Chapter 18: Intra-Domain (Clustered) federation using Single Domain Name Support. 211 Clustered federation using Single Domain Name Support (SDNS)..............................................................211 Configuring SDNS for Intra-Domain (Clustered) Federation.........................................................................212 Configuring JSM...................................................................................................................................212 Configuring SDNS for JSM...................................................................................................................212 Configuring an R2R connection............................................................................................................213 Chapter 19: Kerberos authentication and Microsoft Active Directory.............................215 Active Directory setup...................................................................................................................................215 Configuring Kerberos for the Presence Services Server..............................................................................215 Chapter 17: Services.............................................................................................................219 Stanza Optimizer...........................................................................................................................................219 Configuring the Stanza Optimizer Component.....................................................................................219 Configuring Text Conferencing for Stanza Optimization.......................................................................221 Configuring the InfoBroker for Stanza Optimization.............................................................................221 Stanza Optimizer Parameter Reference...............................................................................................222 Text Conferencing.........................................................................................................................................226 Configuring Persistent Conference Rooms..........................................................................................227 Configuring Text Conferencing Administrators.....................................................................................227 Conference Room User Roles..............................................................................................................228 Text Conferencing Gears......................................................................................................................229 Text Conferencing Parameter Reference.............................................................................................232 Wait List Service............................................................................................................................................243 Configuring the Wait List Service Component......................................................................................243 Wait List Service Parameter Reference................................................................................................244 The Wait List Interface..........................................................................................................................248 Creating a JIG File................................................................................................................................249 Web Services................................................................................................................................................249 Configuring Web Services....................................................................................................................250 Web Services Parameter Reference....................................................................................................254 Service-Specific Configurations............................................................................................................257 Invoking Services from a SOAP-over-HTTP Client..............................................................................259 Web Services Definition Language Files..............................................................................................260 Chapter 20: System Manager...............................................................................................261 Presence.......................................................................................................................................................261 Presence administration.......................................................................................................................261 Presence configuration properties........................................................................................................261 Classes.................................................................................................................................................262 Access Levels.......................................................................................................................................264 6 Administering Presence Services XCP Controller August 2010 Presence server status.........................................................................................................................267 Access Levels...............................................................................................................................................267 Presence access levels........................................................................................................................267 Viewing Presence access levels..........................................................................................................268 Creating Presence access levels.........................................................................................................268 Modifying Presence access levels........................................................................................................268 Deleting Presence access levels..........................................................................................................269 Presence access level field descriptions..............................................................................................269 Classes.........................................................................................................................................................270 Presence classes.................................................................................................................................270 Viewing Presence classes....................................................................................................................270 Creating Presence classes...................................................................................................................271 Modifying Presence classes.................................................................................................................271 Deleting Presence classes...................................................................................................................271 Index.......................................................................................................................................273 Administering Presence Services XCP Controller August 2010 7 8 Administering Presence Services XCP Controller August 2010 Chapter 1: Using the Presence XCP Controller The Presence XCP controller is a web-based administration console that you must use to configure the Presence XCP server. From the Presence XCP Controller main page, you can access information on the server’s core router, and on all of the plug-ins and components that are running on the server. You can start and stop the server and its components from this location. You can also view an XML summary of your server configuration. Important: Avaya strongly recommends against editing any of the server component XML files manually. If you edit a file manually, you can easily compromise your configuration, and you may not be able to use use the Presence XCP Controller later to edit the configuration. This chapter consists of the following sections: • Starting the Presence XCP Controller on page 9 • Using web access on page 10 • Configuration views on page 11 • XCP Controller interface on page 12 • Online Help Starting the Presence XCP Controller This section describes how to start the Presence XCP controller and access it through a Web browser. Related topics: Using Linux on page 9 Using Linux if you are using Presence XCP Controller for Linux, then too start the Presence XCP controller: To start the Presence XCP controller Administering Presence Services XCP Controller August 2010 9 Using the Presence XCP Controller 1. Change to the $JABBER_HOME/bin directory. 2. At the command line prompt, enter: ./runcontroller start 3. Open a Web browser, and connect to the Presence XCP controller using the server’s IP address and the port that you provided during the installation. The syntax is as follows: https://[ xcp_server_IP ]:[ xcp_controller_port ]/admin For example: https://127.0.0.1:7300/admin Note: The default Presence XCP Controller port is 7300 as specified during installation. If you prefer to connect to the Presence XCP controller using the server’s host name, see Using web access on page 10. 4. Click OK when you see the message about using an unknown authority or that there is a problem with the security certificate. The system displays this message because you are connecting using SSL, and the certificate is being signed by Avaya, which is not a certificate authority. If you entered a URL containing the server’s host name rather than the IP address, you may see an error message similar to the one shown in the following figure. The free certificate that Avaya supplies is for the IP address, not the host name, of the machine on which you installed the Presence Services server. To remove this error either connect to the Presence XCP Controller using the server’s IP address, or use a certificate for your host name that is obtained from a trusted certificate authority. 5. At the login prompt, enter the username and the password for the Presence XCP controller Administrator (specified during installation), and click OK. 6. When you see the Presence XCP controller page, click XCP Controller Home. Using web access When you access Presence XCP Controller using your Presence Services server’s host name, it is automatically converted to the server’s IP address. This conversion allows multiple controllers to be run from a single host. If you prefer to use the Presence Services server host 10 Administering Presence Services XCP Controller August 2010 Configuration views name to access Presence XCP Controller, you can modify the web-cm.xml file, and change the IP address to the host name so that when you log in, the system uses the host name. To modify web-cm.xml 1. Stop the Presence Services server and log off from Presence XCP Controller. 2. Change to the $JABBER_HOME/etc directory. 3. Open the web-cm.xml file in a text editor. 4. Change the setting of the <server-host/> tag from the IP address to the host name of your Presence Services server. 5. Save and close web-cm.xml. 6. Restart Presence XCP Controller and the Presence Services server. Configuration views The Presence XCP controller offers three levels of configuration, called configuration views: Basic, Intermediate, and Advanced. The following figure shows the Configuration view menu, which is located in the top right corner of every Presence XCP Controller configuration page. When you select a particular view, it remains in effect on all pages until you change it. The Basic configuration view displays the fewest configuration options and primarily uses the server’s default values. You use this view to configure your system for most of the server components and to quickly run the Presence XCP Controller. The Intermediate configuration view displays all of the options that are available in the Basic view in addition to some other options, such as host name, command configurations, and logging. It also includes many of the options for components that are installed with the Presence XCP extras installation package. These components, which require you to configure at least the Intermediate view include: • InfoBroker • Message Archiver • Presence Mirror • Wait List Service • Web Services The Advanced configuration view displays all of the options that are contained in the Basic and Intermediate views in addition to a number of fine-tuning options such as buffer size, run level, and thread count. These options require a more advanced level of Presence Services server knowledge, and you can use them to adjust the performance of your Presence XCP system. Administering Presence Services XCP Controller August 2010 11 Using the Presence XCP Controller The components whose configurations require you to use the Advanced configuration view include: • Single Domain Name Support (SDNS) • Router-to-Router Connection • Stanza Optimizer XCP Controller interface The System, Router, and Components areas on the Presence XCP Controller main page are described in the following sections. Related topics: System on page 12 Router on page 13 Components on page 13 System The links in the System area perform the following functions: • Summary - Displays the complete jabber.xml file, which contains your configuration settings. Important: If you have modified the configuration of a plug-in or component, you must restart the system before the changes take effect and appear in the Summary. • Cluster - Displays a page from which you can access all of the controllers in this cluster. • Stop the System - Stops the Presence Services server and all of its plug-ins and components. • Online Help - Opens the controllers online help system, which is the online version of the Presence Services Admin Guide. When you stop the system, the XCP Contoller - presence page is displayed. 12 Administering Presence Services XCP Controller August 2010 XCP Controller interface You can select from the two options: • Click start the system now to restart the server. • Click view all of the controllers to display the page from which you can access all of the controllers in the current cluster. Router Router plug-ins are extensions of the Presence Services server core router, and always start and stop with the system. Each plug-in on your system is listed in the controller’s Router area. You can add a new plug-in by selecting one from the list and clicking Go to display its configuration page. You can also modify the configuration of a plug-in’s by clicking the corresponding Edit link, or remove a plug-in (except for the core router) by clicking its Remove link. Important: You cannot remove the Core Router, since it is the core of the Presence Services server. Components Components are extensions of the Presence Services server that can be started and stopped independent of the server. In the Components area, you can add, modify, start, stop, or remove server components. You add a new component by selecting from the list and clicking Go to access its configuration page. You can start and stop individual components if needed by clicking the Start and Stop links. You can also modify configuration of a component by clicking the corresponding Edit link, or remove a stopped component by clicking its Remove link. (You must stop a component before you can remove it.) Administering Presence Services XCP Controller August 2010 13 Using the Presence XCP Controller 14 Administering Presence Services XCP Controller August 2010 Chapter 2: Router About Router Area Use the Router area, to install, configure, or remove server plug-ins to the core server. In addition, you can install new “plug-ins” as extensions to the core server . You can automatically start and stop the core server . Note: You cannot independently start the core server or stop the core server using the defined plug-ins. The Router area lists the following information: • Core Router • Presence Session Manager • Database Extensions (XDBs) Each installed plug-ins and any additional plug-in you install are listed in a table in the Router section. By default, Core Router plug-in is available in the table. Note: Do not remove the “Core Router” plug-in from the server. The Status column provides a snap-shot of the system. It indicates how the system responded (whether the task completion was successful) while performing the start or stop operation of the plug-ins. To view the status report of the system, you can use either the SNMP tools or Jstats. The Plug-in Class column indicates how the server classifies the plug-in. For example, if you install Presence Session Manager, then this column displays Presence Session Manager . The Description column provides a brief information about the component. For example, if you have three connection managers, you can describe each connection manager fields as follows: • Connection Manager for SMS • Connection Manager for Basic IM • Redundant Connection Manager for Basic IM Administering Presence Services XCP Controller August 2010 15 Router The Actions column lists all actions that you can perform for that plug-in. For example, if you want to configure namespaces and other data for the plug-in, click Configuration. Global Router settings The Presence XCP core router provides the Presence Services server with its core communication functionality. When you install the Presence Services server, you also install the Presence XCP core router with default setings. The core routers configuration page contains global settings, which allow you to configure features that affect your entire server environment. For example, you can configure database settings that are used by all components that require a database. You can override the core router’s global settings in any individual components configuration page if needed. To open the Global Router Configuration page, click Edit beside Global router settings in the Router area on the Presence XCP Controllers main page. This page lists the options on the Presence XCP Controller Advanced configuration view of the Global Settings Configuration page. The following sections describe the features available in the Global Settings Configuration page: • Cluster on page 17 • Realm on page 18 • MDNS on page 18 • Log level on page 19 • Obscure Plaintext Passwords on page 20 • Advanced Performance Tuning options on page 20 • Master Accept port on page 20 • Database setup on page 22 • Enabling SNMP on page 23 • Mutually Trusted TLS Host Names on page 24 Related topics: Cluster on page 17 Realm on page 18 MDNS on page 18 Log level on page 19 Obscure Plaintext Passwords on page 20 Advanced Performance Tuning options on page 20 16 Administering Presence Services XCP Controller August 2010 Global Router settings Master Accept port on page 20 Database setup on page 22 Enabling SNMP on page 23 Mutually Trusted TLS Host Names on page 24 Cluster The Cluster, which you specify during installation, is a unique string that identifies your Presence Services server installation. Clusters enable the server to use dynamic routing in high-scale installations where multiple Presence XCP core routers are required. All the routers that need to interact must have the same cluster name, and must be installed on the same network subnet. You can change the cluster after you have installed the Presence Services server. To do this, you must change the cluster’s setting in the Global Settings Configuration page and in the web-cm.xml file. To change the cluster 1. In the Global Settings Configuration page, enter a new identifier in the Cluster field. For example: abcdefg123 2. Click Submit to save your configuration. 3. On the Presence XCP Controller main page, click Stop the System to stop the Presence Services server. 4. Change to the $JABBER_HOME/bin directory, and enter the following command to stop the Presence XCP Controller: ./runcontroller stop 5. Change to the $JABBER_HOME/etc directory, and open the web-cm.xml file in a text editor. 6. Locate the following line. In this example, the cluster is set to c4d8f7d17136: <config config:cluster=“c4d8f7d17136” config:realm=“presence” xmlns=“http://www.Presence.com/config/cm”> 7. Change the value of the config:cluster attribute to the identifier that you used in step 1. For example: config:cluster=“abcdefg123” 8. Save and close the web-cm.xml file. 9. Change to the $JABBER_HOME/bin directory, and enter the following command to start the Presence XCP Controller: Administering Presence Services XCP Controller August 2010 17 Router ./runcontroller start 10. Access the Presence XCP Controller in a Web browser and restart the server. Realm The Realm, which you specify during installation, is a unique string that identifies the Presence XCP core router and all of its components. The default realm is presence. You can change the realm after you have installed the server. To do this, you must change the realm’s setting in the Global Settings Configuration page and in the web-cm.xml file. To change the realm: 1. In the Global Settings Configuration page, enter a new identifier in the Realm field; for example: xcp1 2. Click Submit to save your configuration. 3. On the Presence XCP Controller’s main page, click Stop the System to stop the Presence Services server. 4. Change to the $JABBER_HOME/bin directory, and enter the ./runcontroller stop command to stop the Presence XCP Controller. 5. Change to the $JABBER_HOME/etc, and open the web-cm.xml file in a text editor. 6. Locate the following line. In this example, the realm is set to Presence: <config config:cluster=“c4d8f7d17136” config:realm=“presence” xmlns=“http://www.Presence.com/config/cm”> 7. Change the value of the config:realm attribute to the identifier that you used in step 1. For example: config:realm=“xcp1” 8. Save and close the web-cm.xml file. 9. Change to the $JABBER_HOME/bin directory, and enter the ./runcontroller start command to restart the Presence XCP Controller. 10. Access the Presence XCP Controller in a Web browser, and start the server. MDNS When you install the Presence Services server, the MDNS (multicast DNS) option is disabled by default . MDNS allows the server to use its dynamic clustering feature, which provides 18 Administering Presence Services XCP Controller August 2010 Global Router settings automatic router-to-router functionality when you have multiple core routers installed in the same network subnet. Important: For single Presence XCP router installations, Avaya recommends disabling the MDNS option to prevent unnecessary packets from being sent through the network. Log level The Level of information to log option lets you specify the level at which the Presence Services server logs messages to the jabberd Logger. This log level acts as a high-level filter for the types of messages that the server logs. The system does not send log messages that are less severe than the level you specify to the logger. For example, If you set the log level to info, the system by default sends the info, warn, and error levels to jabberd Logger. The log levels from which you can choose are described in the following table. Each log level specifies the severity of the data that is logged and determines the amount of data that the Presence Services server records: the lower the severity level, the more verbose the log. The levels are listed from the highest severity to the lowest. Table 1: Log levels Log Level Description error System-generated errors such as the inability to create listen ports, server configuration errors, failure to create the log files, and so on. warn Non-fatal errors such as bounced packets, nonexistent user logging in, invalid recipient for a message, and so on. In addition, all data logged at the error level. info Data on socket connections and all JSM logs (packet, session, and message) with all data logged at the error and warn levels. The server logs at this level by default. verbose Every packet that is processed by the server and JSM, and all data logged at the error, warn, and info levels. debug Information from all other log levels in addition to debug data. Administering Presence Services XCP Controller August 2010 19 Router Obscure Plaintext Passwords The system enables the Obscure plaintext passwords in log files option by default when you install the Presence Services server. This feature X’s out passwords in log files. If you disable this option, the system displays the passwords in the log files using plaintext. Advanced Performance Tuning options The Presence XCP Controller’s Advanced configuration view displays the following three options for router performance tuning. Name Description Number of threads devoted to I/O Enter the number of threads dedicated to I/O between the router and external components. These threads handle all traffic from external components. This option is used primarily for performance tuning. The default value should be adequate in most circumstances. The interval (in seconds) between keepalive packets Enter the number of seconds between keepalives that are sent over the network to ensure that the connection does not close at the TCP socket layer. When two keepalives are missed, the connection is closed and then restarted if possible. Maximum number of bytes per Jabber ID resource You may want to set a maximum resource if you are using a custom client that has a restriction. This value is the maximum number of bytes (18 or greater) that your users can specify for the resource portion of their Jabber ID. Resources allow users to log on to multiple client sessions using the same Jabber ID. For example, a user can log on as [email protected]/one in one location and as [email protected]/two in another location. One and two are the resource portions of the Jabber ID . The number of hashtable buckets for JID lookups Enter the number of hashtable buckets used for cashing Jabber IDs. The setting of this parameter affects the core router’s memory usage and performance. The higher this number is set, the more memory the router uses, but the higher its performance. Master Accept port The core router uses the Master Accept port to accept connection requests from the Presence XCP components that run behind your firewall. The Master Accept Port is ideal for internal 20 Administering Presence Services XCP Controller August 2010 Global Router settings components that connect to the router, since it removes the necessity of configuring router connections for each individual component. Important: Components that run outside the firewall can be configured to allow the core router to connect to them. This configuration mitigates the security risks that would exist if these components were to connect to the router. You can also enable StartTLS to configure secure socket layer settings to establish secure component connections with the server on the Master Accept Port. Changing the Master Accept port If you change the Master Accept port option’s Port value in the Global Settings Configuration page, all components that are connected to the Presence XCP router changes. You do not need to change this value anywhere else. Related topics: Enabling StartTLS on page 21 Enabling StartTLS The StartTLS Configuration option lets you configure secure socket layer settings to establish a secure connection with the server. Important: The Presence Services server does not support private keys for SSL certificates that have pass phrases. If you have a pass phrase or encrypt your private key, your private key/public certificate pair does not load into Presence XCP To enable TLS: 1. Change to the Presence XCP Controller Intermediate configuration view. 2. Select the StartTLS Configuration option. 3. Configure the parameters as follows: Parameter ssl-mode Description Select tls or tls-required from the list. tls - Enables TLS (transport layer security). Clients that support TLS can connect to the server securely over 5222. Clients that do not support TLS can still connect to the server. This mode does not require a secure connection. tls-required - The same as the tls option, except that the client must support TLS. Clients that do not support TLS cannot connect to the server. Administering Presence Services XCP Controller August 2010 21 Router Parameter Description Full path to SSL key Enter the full path to the location of the private key that is file used to establish a secure server connection. By default, this is set to $JABBER_HOME/certs/hostkey.pem. If you want to use a different key, place the key in the $JABBER_HOME/certs directory, and enter its full path here. You can also use the ip-key.pem file if preferred, which is located in the same directory. Full path to SSL cert Enter the full path to the location of the certificate file. By file default, this path is set to the same value as the SSL Key, $JABBER_HOME/certs/host-key.pem. If you want to use a different certificate file, place the file in the $JABBER_HOME/certs directory, and enter its full path here. You can also use the ip-key.pem file if preferred, which is located in the same directory. Full path to root CA cert file Optionally, enter the full path to the CA certificate that is used to verify incoming client certificates. verify-depth Enter the maximum depth for the certificate chain verification to allow for incoming client connections. enable-weakciphers Select Yes if you want to allow SSL connections to use cryptographically weak ciphers. Database setup The Database Setup option in the Global Settings Configuration page contains information on the database that you are using to store Presence XCP data. If you configured settings for Oracle, PostgreSQL, or DB2 when you installed the Presence Services server, the Database Setup option is enabled, and the settings are displayed as illustrated in the following figure. All components that require a database, use the database globallay; however, if necessary, you can override the database settings in any component’s configuration. Description of the basic Database Setup parameter. 22 Name Description Datasource Name For the PostgreSQL database, this is the name of the component’s datasource as specified in the .odbc.ini file. For Oracle, ORACLE_SID environment variable or in the tsnames.ora file specify the datasource. For DB2, this is typically the database alias. Database User Name Enter the username used to connect to the database. Administering Presence Services XCP Controller August 2010 Global Router settings Name Description Database User’s Password Enter the password used to connect to the database. Confirm Password Enter the password again to confirm it. Database Type Select the type of database you are using from the list. Important: If you select postgresql-odbc, you must add the line, MaxVarcharSize=4000, to the datasource definition used in the .odbc.ini file. Enabling SNMP The SNMP Configuration option allows you to enable the use of the Simple Network Management Protocol for the Presence XCP core router. Network management systems use SNMP to monitor network-attached devices for conditions that warrant administrative attention. SNMP exposes management data in the form of variables on the managed systems, which describe the system configuration. These variables can then be queried (and sometimes set) by managing applications (http://en.wikipedia.org/wiki/ Simple_Network_Management_Protocol). To enable SNMP for the core router 1. Select the SNMP Configuration option to enable the feature. 2. Configure the following parameters: Parameters Description Enable SNMP This option is set to Yes by default. Leave it as is. Count errors This option is set to No by default. Select Yes only if you want to enable SNMP error counting. This option takes a great deal of server resource; use it with caution. Administering Presence Services XCP Controller August 2010 23 Router Mutually Trusted TLS Host Names Only Presence Server and the SIP Proxy component use this configuration option. If you are not using these features, you can ignore the option. Transport Layer Security (TLS) is a cryptographic protocol that provides secure communications on the Internet for such things as Web browsing, e-mail, Internet faxing, instant messaging, and other data transfers (from http://en.wikipedia.org/wiki/ Secure_Sockets_Layer). The Presence Server uses HTTP digest authentication to authenticate SIP users who attempt to connect to the Presence Services server. However, if you have a list of SIP hosts that you know use TLS, you can specify their host names in the Presence Services server Core Router configuration. SIP clients on these hosts can then connect to the Presence Services server using TLS without going through the HTTP digest authentication process. If you have multiple Presence Services servers running in the same cluster, you only have to configure the list of trusted TLS hosts on one of the servers. The other servers in the cluster can then reference the realm of that server, allowing them to use the list of trusted hosts as well. 24 Administering Presence Services XCP Controller August 2010 Chapter 3: Logging Logging T he XCP server provides a number of different logging options. By default, the server’s core router is configured to log JSM and router data to syslog at the ’info’ log level. You can change this default level as needed (as described in Setting the Log Level for Router-Generated Packets ). Any level that you choose logs data at that level in addition to all the levels above it. For example, when the log level is set to ’info’, data is logged at the ’warn’ and ’error’ levels as well. The current jabberd log level is recorded in the jabber.loglevel file, which is located in xcpInstallDir /var/tmp. This file is updated any time someone changes the log level and restarts the server. If you require more logging than what occurs by default, you can configure the server to log statistics and other types of JSM data, and to use file and stderr loggers in addition to syslog. You can also configure syslog and stream loggers for each component. Note: Logging is an intermediate, and sometimes advanced, feature in the XCP controller. When you configure Logging, make sure you are using the controller’s Intermediate or Advanced configuration view. Related topics: Configuring Syslog for Red Hat Linux on page 26 Setting the Log Level for Router-Generated Packets on page 26 Jabberd Logger Configuration on page 28 JSM Logging on page 35 Message Archiver Logging on page 37 Statistics Logging on page 38 Component Logging (Jlog) on page 39 Presence Services logging on page 42 Changing logging levels on page 43 Collecting logs on page 44 Administering Presence Services XCP Controller August 2010 25 Logging Configuring Syslog for Red Hat Linux Red Hat Linux sets its syslog level to *.info by default, which means that it logs at the info, warn, and error levels (log levels are described in the following table). If you prefer to log information at lower levels as well, such as debug , you must edit the syslog configuration file on your Red Hat system, and set the syslog default to a value that is greater than or equal to the XCP log level that you plan to use. Related topics: To configure syslog on page 26 To configure syslog 1. Change to the /etc directory on your Red Hat system. 2. Open the syslog.conf file in a text editor. 3. Locate the following lines: # Log anything (except mail) of level info or higher. # Don't log private authentication messages! *.info;mail.none;authpriv.none;cron.none /var/log/messages 4. To log all information in Syslog, add *.debug in the third line as shown here: *.info;*.debug;mail.none;authpriv.none;cron.none /var/log/messages 5. Save and close the syslog.conf file. Setting the Log Level for Router-Generated Packets The log level specifies the severity of the data that is logged and determines the amount of data that the server records; the lower the severity level, the more verbose the log. The core router is configured by default to log packets at the info level and above, which means that log packets are generated only for data that comes into the router at the ’info’, ’warn’, and ’error’ levels. The log level that is set for the core router is the level at which the server starts. If needed, you can temporarily change the level during runtime; however, the default level is restored when you restart the server. 26 Administering Presence Services XCP Controller August 2010 Logging Log levels are described in the following table and are listed in the order of decreasing severity. For example, the ’warn’ log level is less severe than the ’error’ log level. The lower the severity level, the higher the log’s level of verbosity. Severity Level Information logged... error System-generated errors such as the inability to create listen ports, server configuration errors, failure to create the log files, etc. warn All ’error’ level data plus non-fatal errors such as bounced packets, nonexistent user logging in, invalid recipient for a message, etc. info All ’error’ and ’warn’ level data plus information about socket connections and all JSM logs (packet, session, and message) verbose All ’error’, warn’, and ’info’ level data plus every packet that is processed by the server and JSM. debug All log-level data plus debug data. Note: The log level must be set to ’info’ or higher for the Presence Session Manager (JSM) log types (message, packet, and session) to function properly. In addition, statistics data is not available if the log’s verbosity level is set below ’info’. Related topics: To change the router’s default log level on page 27 To view the current log level on page 28 To increase the log’s verbosity level while the server is running on page 28 To decrease the log’s verbosity level while the server is running on page 28 To change the router’s default log level 1. In the Router area on the controller’s main page, click Edit beside Global Router Settings . 2. In the Global Settings Configuration page, select the preferred level in the Level of information to log list. 3. Scroll to the bottom of the page and click Submit to save your configuration. Administering Presence Services XCP Controller August 2010 27 Logging To view the current log level Enter the following command from the presenceInstallDir /bin directory: ./runjabber loglevel check To increase the log’s verbosity level while the server is running 1. Enter the following command from the presenceInstallDir /bin directory to increase the log level by one increment; for example, from ’warn’ to ’info’). ./runjabber loglevel increase 2. Repeat the command for each desired level increase. To decrease the log’s verbosity level while the server is running 1. Enter the following command from the presenceInstallDir /bin directory to decrease the log level by one increment; for example, from ’info’ to ’warn’). ./runjabber loglevel decrease 2. Repeat the command for each desired level decrease. Jabberd Logger Configuration The Jabberd Logger receives packets that are generated by the core router (jabberd ), by JSM, and by any other plugin, and logs them to syslog, file, and/or stderr. The Jabberd Logger that is installed by default is configured to capture information generated in the generic namespace, jcs:log:default, and to log the information to syslog. You can edit the default logger, or you can add new ones. In the Jabberd Logger Configuration page, you can select the namespaces for other types of information that you want to log, and you can specify the names of the hosts 28 Administering Presence Services XCP Controller August 2010 Logging from which you want to log the information. You can also select the types of loggers that you want to use, and the log level(s) used to log the information. Note: You can configure multiple Jabberd Loggers depending on how specific you want to your logging to be. For example, if you want to log presence and session packets for host alpha.example.com to a file logger, and message packets for host beta.example.com to syslog, you would need to configure two Jabberd Loggers to handle the logging. Related topics: To add a Jabberd Logger on page 29 Selecting Namespaces on page 29 Specifying Host Filters on page 31 Configuring Loggers and Log Levels on page 31 Syslog logger on page 31 File logger on page 32 Standard error logger on page 33 Log Levels on page 33 Formatting Logs on page 34 To add a Jabberd Logger 1. Change to the controller’s Intermediate configuration view. 2. In the Router area on the controller’s main page, select Jabberd Logger from the list, and then click Go . 3. Read the following sections for instructions on configuring the Jabberd Logger. Selecting Namespaces Namespaces are used to capture specific types of log packets that are generated by JSM (mod_log) or the core router, jabberd . When these packets are generated, they are sent to the Jabberd Logger. If they match the namespaces that are in the Namespace Filters list in the Jabberd Logger Configuration page, the Jabberd Logger logs the information to the configured log types (syslog, file, or stderr). Related topics: To select the namespaces for the data you want to log on page 30 Administering Presence Services XCP Controller August 2010 29 Logging To select the namespaces for the data you want to log Delete the namespaces that you do not want to use from the Namespace Filters list. You can type in other namespaces, but you must have a custom logger that handles them. The namespaces that are provided for logging are described in the following table. Namespace This log captures... jcs:log:default Information from the router and from JSM. This namespace is selected by default. jcs:stats:jsm System statistic information. You must select this namespace if you plan to enable Statistics logging in the JSM configuration. jcs:mod_log:ses Information about each user session that occurs on the server. sion You must select this namespace if you plan to enable session packet logging in the JSM configuration. jcs:mod_log:me ssage:in Incoming messages and file transfer requests as they are received by the server. You must select this namespace if you plan to enable incoming message logging in the JSM configuration, and you want the Jabberd Logger to handle the logging. Note: If you prefer to use Message Archiver rather than the Jabberd Logger to handle message packets, you do not have to select the message namespaces here (see Message Archiver Logging ). jcs:mod_log:me ssage:out Outgoing messages and file transfer requests as they are sent by the server. You must select this namespace if you plan to enable outgoing message logging in the JSM configuration, and you want the Jabberd Logger to handle the logging. jcs:mod_log:pac Information about packets going into JSM. ket:in Note: Logging incoming and outgoing packets is not recommended because of the massive load it places on the router. This type of logging is usually reserved for debugging purposes. jcs:mod_log:pac Information about packets coming out of JSM. ket:out jcs:mod_log:pre sence 30 Information about client users’ presence. You must select this namespace if you plan to enable presence packet logging in the JSM configuration. Administering Presence Services XCP Controller August 2010 Logging Specifying Host Filters In the Host Filters text box, you can specify the names of hosts from which you want to log the selected packet types. For jcs:log:default packets, you should leave the asterisk (*), which will log packets in that namespace from all hosts. However, for other namespace filters you can either use the asterisk to indicate that you want to log these packet types from all hosts, or you can list specific hosts only. Configuring Loggers and Log Levels In addition to the Syslog logger, which is enabled by default, you can configure a file logger and a standard error logger. In addition, you can select one or more log levels at which to log the information to these log types. Syslog logger The Syslog logger is enabled by default when you install the server. This logger logs information from the router, and from JSM and other plugins to syslog. Syslog refers to the logging daemon used to log messages generated by your operating system components. Syslog also provides log rotation based on file age and size. It can be run locally or remotely and does not require any additional hardware or software. Related topics: To configure the Syslog logger on page 31 To configure the Syslog logger 1. Under Configuration on the Jabberd Logger Configuration page, click Details beside the Syslog Logger. The Syslog Logger Configuration page is displayed. (If you prefer, you can add a new Syslog logger rather than modifying the existing one.) 2. Configure the Syslog logger parameters as follows. Paramete r Description Identity Identifies where the log information came from. The identity is displayed in syslog next to the associated data. You can change the default value if preferred. Facility Select the facility that you want to use from the list. Administering Presence Services XCP Controller August 2010 31 Logging Paramete r Format Description Enter the formatters for the information that you want to log to syslog. See Formatting Logs for more information. 3. Click Submit to save your configuration. File logger The File Logger lets you specify the name and location of a log file and various parameters for the information that you want to log to it. Related topics: To configure the File logger on page 32 To configure the File logger 1. Under Configuration on the Jabberd Logger Configuration page, select File Logger in the list, and then click Go . The File Logger Configuration page is displayed. 2. Configure the File Logger parameters as follows. Parameter 32 Description Name and location Enter the name and location of the log file. Memory buffer size (in bytes) Enter the number of bytes in the memory buffer used to store log information. When the size limit is reached, the logs are written to the current log file. If you enter 0, the messages are written to a log file continuously. Format Enter the type of information that you want to log to the file using any or all of the log formatters. (See Formatting Logs for more information.) Size of file (in megabytes) after which the log rotates Enter the size of the log file in megabytes after which the log rotates. For example, if you enter 24, the log rotates out every time the file reaches a size of 24 megabytes. Administering Presence Services XCP Controller August 2010 Logging Parameter Description If you enter a value both for this option and the next, the log rotates when it reaches either the size or the age limit. Number of hours after which the log rotates Enter the number of hours after which you want the log to rotate. For example, if you enter 24, the log rotates out every 24 hours. Number of log files to keep after the log Enter the number of log files to keep rotates after they have been rotated. When this number is reached, the oldest rotated log file is deleted. 3. Click Submit to save your configuration. Standard error logger The Standard Error Logger lets you format information that is logged to stderr. Related topics: To configure the Standard Error logger on page 33 To configure the Standard Error logger 1. Under Configuration on the Jabberd Logger Configuration page, select Standard Error Logger in the list, and then click Go . 2. In the Standard Error Logger Configuration page, enter the log formatters for the type of information that you want to log. (See Formatting Logs for more information.). 3. Click Submit to save your configuration. Log Levels You can select one or more log levels, which pertain to all of the loggers configured in this particular instance of the Jabberd Logger plugin. Related topics: To select one or more log levels on page 34 Administering Presence Services XCP Controller August 2010 33 Logging To select one or more log levels 1. Under Configuration on the Jabberd Logger Configuration page, select Log Levels in the list, and then click Go . 2. In the Log Levels Configuration page, select one or more log levels in the list; hold down the ctrl key to select more than one. The logs that you select for this particular Jabberd Logger configuration will each log at these levels. 3. Click Submit to save your configuration. Formatting Logs You can modify how log information is formatted using a number of attribute codes. Related topics: To format a log on page 34 To format a log Add any or all of the attribute codes listed in the following table in a logger’s Format text box to capture the desired data in your log. Format Tag 34 Description %h The point in the code where the log message was generated. In general, this information is useful in debugging the server. It is usually not useful when used with message and session logs. %i The thread number inside the server that generates the log message; used for debugging. %s The information being logged. %d The Greenwich Mean Time and date when the log message was generated. %t The log level of the message; for example, none, error, info, warn, verbose, debug. This attribute does not work with message, packet, or session logs. Administering Presence Services XCP Controller August 2010 Logging JSM Logging You can configure the logging of message, session, and presence packets in the Presence Session Manager. These packets will be logged in addition to the JSM-generated packets that are logged by default. Related topics: To configure JSM logging on page 35 Packet Logs on page 36 Session Logs on page 36 Message Logs on page 37 To configure JSM logging 1. Change to the controller’s Advanced configuration view. 2. In the Router area on the controller’s main page, click Edit beside Presence Session Manager . 3. In the Presence Session Manager Configuration page, scroll down toward the bottom of the page, and select the JSM Logging option. 4. Select Yes beside any of the packets that you want to log. 5. Select the Namespace Packets option if you want to log IQ packets for specific namespaces. Enter the namespaces in the Namespace(s) box; for example: jabber:iq:roster jabber:iq:last 6. Select the Excluded Hosts option if you want to exclude specific hosts from packet log generation. Enter the hostnames for each host in the Host(s) box. Hostname exclusions apply to all logging parameters. 7. Click Submit to save your configuration. You are returned to the controller’s main page. 8. In the Router area, click Edit beside Logger Plugin . 9. In the Jabberd Logger Configuration page, select or type the namespaces in the Namespace Filters list that correspond to the packet types that you selected for JSM logging. The namespaces correspond to the Presence Session Manager packets as described in the following table. Packets generated by JSM in these namespaces will be logged to the loggers that you have configured for the Jabberd Logger. Administering Presence Services XCP Controller August 2010 35 Logging Jabberd Logger namespaces JSM packet types jcs:mod_log:sessi on Session Packets jcs:mod_log:mess age:in Incoming message packets jcs:mod_log:mess age:out Outgoing message packets jcs:mod_log:packe Summarized packet data t:in jcs:mod_log:packe Summarized packet data t:out jcs:mod_log:prese nce Presence packets 10. Click Submit to save your configuration. 11. Restart your XCP system. Packet Logs Packet logs contain two types of data: non-IQ packets and IQ packets. A non-IQ packet records whether the packet contained an IQ packet (designated by ’i’), presence information (designated by ’p’), or subscription information (designated by ’s’). Non-IQ packet information resembles the following: An IQ packet contains all of the information that is saved for the non-IQ packet. It also includes a numeric sub-type for the packet and the namespace from which the data came. Numeric sub-types include: 5 for ’get’; 6 for ’set’, and 7 for ’result’. Session Logs Session logs contain information about each user session that occurs on the server. When the user logs off or is disconnected, the server logs the timestamp of when the session ended, the number of seconds the session lasted, and the full JID of the user associated with the session (for example, user@host/resource). It also records the number of packets sent and received. 36 Administering Presence Services XCP Controller August 2010 Logging Note: The session log provides information only after a session has ended, and therefore does not provide information about a user’s session while that user is logged in. Message Logs Message logs contain all messages. You may want to use the message log feature to archive your message traffic. You may archive traffic through the server by writing the message logs to a file and backing them up outside of the server. Message Archiver Logging You can send all inbound and outbound message packets to the Message Archiver component for logging instead of, or in addition to, the Jabberd Logger. The Message Archiver handles the message packets and stores them in the selected database. Note: If you do not select the message namespaces in the Jabberd Logger configuration, message packets will be logged only through the Message Archiver component providing that you have one configured. Related topics: To log message packets through Message Archiver on page 37 To log message packets through Message Archiver 1. Configure a Message Archiver component as described in Chapter 14. 2. Using the controller’s Intermediate configuration view, edit the Presence Session Manager. 3. In the Presence Session Manager Configuration page under Optional modules , select mod_message_archiver . 4. Scroll down toward the bottom of the page, and select the JSM Logging option. 5. Select Yes for one or both message packet options. The packets you enable here must match the namespaces that you selected in the Message Archiver namespace configuration. Administering Presence Services XCP Controller August 2010 37 Logging 6. Click Submit to save your configuration. 7. Restart your XCP system. Statistics Logging Statistics logging captures server statistics and logs the data to the log types that are configured for the Jabberd Logger. Statistics logging is turned off by default when you install the Presence XCP server; however, you can enable it in the JSM configuration and set the time interval for capturing data. Server statistics data includes the number of: • Users who are currently online • Successful logins in the last time-slice interval • Successful logins since server startup • Failed logins since server startup • Offline messages stored in the last time-slice interval • Total messages since server startup • Presence packets since server startup • IQ packets since server startup Statistics data also includes information about: • The length of time, in seconds, that the server has been running • The average message size in the last time-slice interval • The number of messages in the last time-slice interval Related topics: To enable server statistics logging on page 38 To enable server statistics logging 1. Change to the controller’s Intermediate configuration view. 2. In the Router area on the controller’s main page, select Jabberd Logger/Statistics Logger in the list, and then click Go . 38 Administering Presence Services XCP Controller August 2010 Logging 3. In the Jabberd Logger Configuration page in the Namespace Filters list, remove all of the namespaces except for jcs:log:default and jcs:stats:jsm . 4. Click Submit to save your configuration. You are returned to the controller’s main page. 5. In the Router area, click Edit beside Presence Session Manager . 6. In the Presence Session Manager Configuration page, select the Stats option. 7. If preferred, change the number of seconds that elapse before each capture of server statistics. 8. Scroll to the bottom of the Presence Session Manager Configuration page, and click Submit to save your configuration. Component Logging (Jlog) All XCP components can log to the Presence Logging Library, Jlog. Each component configuration page has a Component Logging (Jlog) section, in which you can configure Syslog and stream loggers that filter the information based on the selected log level. The information that is logged varies by component. The Syslog and stream loggers log information that is generated at or above the selected severity level and drops messages that are below that level. For example, if you select the warning level, warning and error messages are logged, and messages at the debug, verbose, and info levels are dropped. Note: When a component is daemonized, logging to stderr or stdout is disabled; if you start a component from the command line using the -P flag, it is daemonized. Related topics: To enable component logging on page 40 Configuring the Filtered Syslog Logger on page 40 Configuring the Filtered Stream Logger on page 41 Adding a New Custom Logger on page 42 Administering Presence Services XCP Controller August 2010 39 Logging To enable component logging 1. Change to the controller’s Intermediate or Advanced configuration view. 2. Select the check boxes beside Component Logging (Jlog) and Logger. 3. Select one or both filtered logger types and configure them as described in the following sections. Configuring the Filtered Syslog Logger The Filtered Syslog Logger logs component information to syslog at the selected level. Related topics: To configure the Filtered Syslog Logger on page 40 To configure the Filtered Syslog Logger 1. Select the Filtered Syslog Logger option. 2. In the Level list, select the preferred severity level. 3. In the Pipe file box, enter the full path to a pipe file for this component. Note: If you are running the XCP server for Solaris or Linux, naming the file as $JABBER_HOME/var/log/comp-id is suggested, where comp-id is the component’s ID. If the pipe file does not already exist on your system, it will be created. You can send the file a pipe command of U (up) or D (down) to increase or decrease the amount of data being logged from the component. For example, if your log level is set to ’verbose’ and you send a pipe command of D, the log’s level of verbosity is decreased to ’info’. You can also use the echo C > pipe_file command to create an entry in syslog indicating the current log level for the component. For pipe_file, enter the full or relative path (including the pipe file’s name) to the location of the component’s pipe file. 4. In the Facility list, select the facility that you want to use. Facilities are defined on the syslog(3) mainpage. 40 Administering Presence Services XCP Controller August 2010 Logging 5. In the Identity box, enter a term that identifies where the log information is coming from. The identity is displayed in syslog next to the associated data. You can change the default value as needed. 6. In the Formatter box, enter the formatters for the information that you want to log. (See Formatting Logs.) 7. When you have finished configuring the loggers, click Submit to save your configuration. 8. Restart your XCP system. Configuring the Filtered Stream Logger The Filtered Stream Logger logs information to stdout or to stderr at the selected level. Related topics: To configure the Filtered Stream Logger on page 41 To configure the Filtered Stream Logger 1. Select the Filtered Stream Logger option. 2. In the Level list, select the preferred severity level. 3. In the Pipe File box, enter the full path to a pipe file for this component. Note: If you are running the XCP server for Solaris or Linux, naming the file $JABBER_HOME/var/log/comp-id , is suggested where comp-id is the component’s ID. If the pipe file does not already exist on your system, it will be created. (For more information about the pipe file, see step 3 in the previous section.) 4. In the Stream list, select stderr or stdout . 5. In the Formatter box, enter the formatters for the information that you want to log. (See Formatting Logs.) 6. When you have finished configuring the loggers, click Submit to save your configuration. 7. Restart your XCP system. Administering Presence Services XCP Controller August 2010 41 Logging Adding a New Custom Logger If you have created a custom logger for logging component information using the libjcore library, you can add it to your XCP server configuration. Related topics: To add a custom logger on page 42 To add a custom logger 1. Change to the controller’s Advanced configuration view. 2. Click Go beside Add a new custom logger . The Custom Logger Configuration page is displayed. 3. Configure the parameters as follows. Parameter Description Description Enter a description for the custom logger. Custom Library Enter the library used for this logger. Load Enter the library entry point function. 4. Click Submit to save your custom logger configuration. You are returned to the component’s configuration page. 5. Click Submit again to return to the controller’s main page. 6. Restart your XCP system. Presence Services logging This section describes the various types of logs and alarms generated during the PS installation and gives you the location where the information is stored. Presence Core and Audit Log PS provides an audit log file which stores before and after component configuration changes made through the Presence XCP Controller: /var/log/presence/presence_core.log After completing the installation, the system displays the location of the log file, it should look similar to the example below: 42 Administering Presence Services XCP Controller August 2010 Logging /opt/Avaya/Presence/ps_process_panel_2008_xxxx.log Refer to this log file for errors and compare them to the known issues section for warnings. This log also contains detailed logging information from core components that may be truncated in: /var/log/messages. Backup and Restore Log Shows the output from restores and backups run against the current installation. /var/log/presence/backup.log Database Log By default, Postgres logging files are at /var/lib/pgsql/data/pg_log The PS installation installs a file, that controls Postgres logging, into /var/lib/pgsql/data called “postgresql.conf”. The PS Administrator can change the location of these log files, For more information about “PostgreSQL 8.2.13”, please refer to the documentation available at http://www.pgostgresql.org web site. Memory Usage Log PS provides a memory log file which takes snapshots of the memory usage on the server every hour. /var/log/presence/memory.log . PS Core Start Stop log If the scripts stop.sh and start.sh in /opt/Avaya/Presence/presence/bin folder are used to stop and start the PS XCP Core and its components then the output from those scripts are logged to/var/log/presence/stop_start.log Changing logging levels The Presence Service debug files are at /var/log/messages. To change the log level permanently 1. In Presence XCP Controller, in Router section, click Edit for the Core Router. 2. Change the Configuration View to Advanced view. 3. Update Level of information to log to required level. Administering Presence Services XCP Controller August 2010 43 Logging 4. Click Submit. 5. Restart PS (go to /opt/Avaya/Presence/presence/bin/ for stop and start commands). Result Note: Core Router logs are stored in /var/log/presence/presence_core.log. Related topics: Component level logging examples on page 44 Component level logging examples It is possible to set the log level of the some components dynamically (without restarting PS) by using the updateLogLevel.sh script. To use this script, pass the parameters of the component and the change required. Example 1: To Increase log level /opt/Avaya/Presence/jabber/xcp/bin/updateLogLevel.sh ACTIVE-DIR INCREASE increases the log level of the Active Directory Component Note: The Component logging(Jlog) must be enabled in the AD component and the pipe file entered must be /opt/Avaya/Presence/jabber/xcp/var/log/act-dir.pipe Example 2: To decrease log level /opt/Avaya/Presence/jabber/xcp/bin/updateLogLevel.sh CORE-ROUTER DECREASE decreases log level of the Core Router Example 3: To check the level of OCS Gateway /opt/Avaya/Presence/jabber/xcp/bin/updateLogLevel.sh OCS-Communication Manager CHECK checks the level of the OCS Gateway without changing it. This does not update the static setting on the configuration page but the level of logging is updated unless the component is restarted. Collecting logs A script is provided with PS to collect and compress the logs files. 44 Administering Presence Services XCP Controller August 2010 Logging /opt/Avaya/Presence/presence/bin/getpslogs.sh The script by default will get the log files which have been updated in the last 7 days and save them to a file in: /home/craft/support-logs-<date&time>.zip Important: If you need the log file to contain information for more than the specified default value (default value is 7), change the value by running the following command /opt/Avaya/Presence/presence/bin/getpslogs.sh 14 System Manager Alarm and Logging Viewing System Manager logs You can see a Log Viewer and an Alarm Viewer on the System Manager Console interface. The Log Viewer displays logs which were sent to the logging service. The logs which are found in the Log Viewer can be found in /var/log/presence/ harvest.log locally on the PS machine. Viewing SAL Agent log The SAL Agent forwards logs to the System Manager Log Viewer, however it also has log messages on the local server at $SPIRIT_HOME/logging/spirit.log. This file is also collected when collecting PS logs as mentioned above with the tool $PRES_HOME/presence/ bin/getpslogs.sh. To set the SAL Agent to debug logging, edit the file $SPIRIT_HOME/wrapper.config as follows: 1. Change the field wrapper.debug=false to wrapper.debug=true. 2. Restart the spiritAgent with service spiritAgent restart. Result Important: You will then see the debug logs in $SPIRIT_HOME/logging/wrapper.log Administering Presence Services XCP Controller August 2010 45 Logging Viewing Log Harvester log The log harvester logs to /var/log/presence/harvest.log. To update the log level of the log harvester component itself by replacing INFO in $PRES_HOME/presence/lib/path/log4j.properties at the property log4j.logger.events.operational=INFO#com.avaya.common.loggging.client.LogLevel, with other levels such as SPIRIT_FILE to FINE, FINER or FINEST in order of increasing granularity. Viewing System Manager Alarms Alarms can be viewed in the System Manager Alarm Viewer. The SAL Agent has rules in $SPIRIT_HOME/config/agent/IPS_2.0_0_EPBaseRules_orig.xml that define filters for identifying which log messages should also be raised as Alarms. By default all log messages of level ERROR or FATAL generate alarms. Also when you install Presence Services on a server there is a successful start up alarm that the system sends to the Alarm Viewer which says Successful installation of Presence Services 5.2, now available at: <IPAddress>. 46 Administering Presence Services XCP Controller August 2010 Chapter 4: Presence Session Manager (JSM) The Presence Session Manager (JSM) controls all sessions on the Presence Services server. Each time a client connects to the server, a new session is started; one session is opened for every client logged onto the system. An operational Presence Session Manager is provided by default when you install the Presence Services server. You can modify the configuration, enabling the JSM to handle additional Presence Services server features as needed. The following sections describe the features that are contained in the Presence Session Manager Configuration page: • Optional modules on page 48 • JSM hostnames on page 48 • Presence Administrators on page 49 • System limits on page 53 • System parameters on page 53 • Database setup option on page 54 • JSM features on page 56 • Stats on page 56 • Agents on page 57 • Legacy redirect to external components on page 57 • Static EventBroker events on page 57 • Configuring JDS on page 58 • Configuring Roster on page 59 • Configuring Sendmail on page 59 • Configuring Offline SMTP on page 60 • Configure The following parameters. • Configuring Registration Requirements on page 61 • Authorization on page 62 • JSM Logging on page 62 • Configuring HTTP Digest Module on page 63 Administering Presence Services XCP Controller August 2010 47 Presence Session Manager (JSM) • Configuring personal eventing on page 63 • Configuring SNMP on page 64 Optional modules The optional modules are used by the Presence Services server to enable specific features. Many of the modules, once you enable them, must be configured in more detail further down in the JSM configuration, or in a different component. The Optional modules section in the Presence Session Manager Configuration page is shown in the following figure in the Advanced configuration view so that all of the modules are visible. As shown, some of the modules are selected by default. See the online help for the Presence Session Manager Configuration page for descriptions of the modules that display in each configuration view. JSM hostnames The Hostnames for this Component configuration section is available in the Presence XCP Controller’s Intermediate configuration view. JSM handles packets from all of the hosts listed here. By default, the host name in the Host Filters field belongs to the server on which Presence XCP is installed. You can enter the names or IP addresses of other hosts for which you want this JSM to handle packets as well. To enable the JSM to handle packets from any host, enter an asterisk (*). A host filter must be a host name, or an IPv4 or IPv6 address. Important: If you configure SDNS to run in front of this JSM, leave the Host Filters field blank. Since the host name for which this JSM handles packets must be specified in the SDNS component’s configuration, if you add the host name in the JSM configuration as well, the same packets will be sent to the host twice. 48 Administering Presence Services XCP Controller August 2010 Presence Administrators Presence Administrators Important: To use the Presence Administrator feature, select mod_admin under Optional modules. The Presence Administrators configuration section is available in the Presence XCP Controller’s Intermediate configuration view. You can add and delete Presence administrators as needed. By default, the Administrator(s) field contains the Jabber ID of the person who installed the Presence Services server. You can add other Jabber IDs as necessary; separate each Jabber ID with a line break. The following sections describe tasks that Presence administrators can perform. Related topics: Unregistering users on page 49 Deleting Offline messages on page 50 Locating Inactive accounts on page 50 Broadcasting messages to all users on page 51 Unregistering users Presence administrators can unregister any user who has an account on the Presence Services server. To do this, the administrator must use a client that is capable of sending raw XML to the server. Once a user has been unregistered, his or her account is deactivated, and the Jabber ID is marked unavailable. Unregistered users are automatically removed from the rosters of contacts on the same server who are subscribed to their presence. (They may not be removed from the rosters of people who are on other Presence servers.) To unregister a user: 1. Using a XMPP IM Client, display the console (or debug) pane. SHIFT+F12: In Presence Messenger, select Console in the View menu. In Jabber MomentIM, press SHIFT+ F12. 2. In the text-entry area of the console pane, type the following XML: <iq type='set' from=' [email protected] ' to=' [email protected] Administering Presence Services XCP Controller August 2010 49 Presence Session Manager (JSM) '> <query xmlns='Presence:iq:register'><remove/></query></iq> 3. Modify the from and to attributes as needed, entering the Jabber ID of an administrator and the Jabber ID of the user who is being unregistered. 4. Press ENTER to send the XML. The server returns a type=result indicating that the user is unregistered. If the server encounters a problem, it returns a type=error packet. Deleting Offline messages When a Presence user is unregistered, the user’s persistent data, such as preferences, JID, off-line messages, remain stored in the system. To delete offline messages sent to unregistered users 1. In the Presence Session Manager Configuration page, select mod_offline under Optional modules. This module enables Presence administrators to receive IM notifications when unregistered users receive offline messages. 2. Delete the offline messages using the database or directory service tools for the database where the messages are stored. Locating Inactive accounts Presence administrators can locate inactive user accounts by querying the Presence:iq:last namespace. This namespace records the last information sent by users when they log out of the system in a directory service or database. This information includes the time and date that they last logged out. By using the directory service’s tools, the administrator can query for users who have not used the system for a long period of time and then remove these users from the system. Administrators can also use the Presence:iq:last query with online users to see what their last activity was and when it occurred. To locate inactive accounts 1. Using a XMPP IM Client, display the console pane. 50 Administering Presence Services XCP Controller August 2010 Presence Administrators SHIFT+F12: In Presence Messenger, select Console in the View menu. In Jabber MomentIM, press SHIFT+F12. 2. In the text entry area of the Console tab, type the following XML. The to attribute contains the Jabber ID of the user for whom you want to receive the Presence:iq:last information. <iq type='get' to='user@host'> <query xmlns='Presence:iq:last'/> </iq> 3. Press Enter to send the XML. 4. View the returned XML. It should resemble the following <iq type='result' from='user@host'> <query xmlns='Presence:iq:last' seconds='903'/> </iq> 5. Interpret the results using the following attribute descriptions Attribute Description type Indicates that the XML is the result of a query. from Contains the Jabber ID of the person or component sending the data. xmlns Indicates that the XML is related to a Presence:iq:last query. seconds Contains the number of seconds since the user performed his or her last action on the server. In the previous example, the user last performed an action 15 minutes and 3 seconds ago. Broadcasting messages to all users Presence administrators can broadcast messages through an IM client to all users who are connected to a specific Connection Manager. To broadcast messages to all users on a Communication Manager Administering Presence Services XCP Controller August 2010 51 Presence Session Manager (JSM) 1. Change to the Presence XCP Controller’s Advanced configuration view. 2. Edit the Presence Session Manager and verify that the mod_admin module is selected. 3. Edit the Connection Manager, and under Add a New Command Processor, click Details beside jsmcp. 4. In the JSM Command Processor Configuration page, select Yes for the Enable Broadcast to all online users connected to thisCommunication Manager parameter. 5. Submit your configuration changes and restart the server. 6. Using a XMPP IM Client, display the console pane. SHIFT+F12: In Presence Messenger, select Console in the View menu. In Jabber MomentIM, press SHIFT+ F12. 7. In the text-entry area of the Console pane, type the following XML. The to attribute contains the resource to which you want the message sent. In the following example, the message is sent to all users online at example.com. When users receive the message, they see which Presence server the message came from, but not the Jabber ID of the person who sent it. <message to='example.com/announce/online'> <body>Text of message here.</body> </message> 8. Press ENTER to send the XML. 9. View the message sent out by the Presence Session Manager. It resembles the following: <route to='*@cm1'> <message>Text of message here.</message> </route> Result The message is sent to all Connection Managers that have users connected to the Presence Services server. 52 Administering Presence Services XCP Controller August 2010 System limits System limits The System Limits configuration section is available in the Presence XCP Controller’s Advanced configuration view. This setting controls the usage of your Presence XCP system. The System Limits parameter is described in the following table. Name Description Maximum number of sessions a single user (Jabber ID) can open at a time Enter the maximum number of sessions a Presence user can have on the server using the same Jabber ID and different resources. Each time a Presence user logs into the server, a session is created. If the same user logs on from two locations, that user has two sessions active on the server. By default, users may have an unlimited number of concurrent sessions. You may want to limit this number to prevent overuse of your Presence Services server. System parameters The System Parameters configuration section is available in the Presence XCP Controller’s Advanced configuration view. These parameters control the Presence Services server use of your system’s processor, and default values have been supplied based on average server usage. If you want to change these values, we recommend that you call Presence Support for help. The System Parameters are described in the following table. Name Description Number of threads to use for processing Presence tasks The number of threads that the Presence Services server should create to process Presence tasks. We recommend that you use the number of CPUs plus 1. Creating more threads enables the Presence Services server to process Presence tasks more quickly, but uses more of your system’s processor. Closed session cache time (in seconds) The number of seconds that a user’s session is cached in memory after he or she logs out. The lower the number of seconds, the more time JSM must spend trying to free memory. The higher the number of seconds, the fewer times cleanup occurs. Administering Presence Services XCP Controller August 2010 53 Presence Session Manager (JSM) Name Description User session cache time (in seconds) The number of seconds that a user’s session resources are cached after he or she has logged out from all sessions. The lower the number of seconds, the more time JSM must spend trying to free memory. The higher the number of seconds, the fewer times cleanup occurs. Timeout for XDB requests The number of seconds to wait before an XDB request that has been sent to the router times out. This setting affects users; the higher the setting, the slower the system runs. If you are configuring JSM for the Redirect Events to External Component feature, set this value to something greater than 0. If you are using JDS, set this value to 120 seconds. Timeout for IQ requests The number of seconds to wait before an IQ request that has been sent to the router times out. This item is used only during the discovery of other components, and its setting has no effect on users. Maximum XDB requests to allow The number of XDB requests that can be sent to the JSM from the Connection Manager (Communication Manager) at one time. When this number is reached, the Presence XCP core router tells the Communication Manager to stop listening on its socket. Resume sockets when XDB requests drop below The number of XDB requests that JSM still must handle before accepting them again from the Communication Manager. When this number is reached, the Presence XCP core router tells the Communication Manager to resume listening on its socket. Maximum The number of database requests that can be sent to the JSM at one database requests time. When this number is reached, the Presence XCP core router tells to allow the Communication Manager to stop listening on its socket. Resume sockets when database requests drop below The number of database requests that JSM still must handle before accepting them again. When this number is reached, the Presence XCP core router tells the Communication Manager to resume listening on its socket. Database setup option The Database Setup configuration section is available in the Presence XCP Controller’s Intermediate and Advanced configuration views. If you selected SQLite as your database during Presence XCP installation, these parameters contain information about SQLite. If you selected one of the databases, this option is dimmed. Any database configured in this section is used only to store basic Presence IM data such as usernames, passwords, rosters, vCard information, and offline messages. 54 Administering Presence Services XCP Controller August 2010 Database setup option Important: If you use the SQLite database, make sure that mod_presence_mirror and mod_message_archiver are not selected under Optional modules. If you select the Oracle database, you must enable the mod_auth_plain and mod_auth_digest modules. The Database Setup parameters are described in the following table. Name Description Datasource Name Enter the name of the database’s datasource. For the SQLite database, this is the database filename. For the PostgreSQL database, this is the name of the component’s datasource as specified in the .odbc.ini file. For Oracle, the datasource is specified in the ORACLE_SID environment variable or in the tsnames.ora file. For DB2, this is typically the database alias. Database User Name Enter the username used to connect to the database. Database User’s Password Enter the password used to connect to the database. Confirm Password Enter the password again to confirm it. Database Type Select the type of database you are using from the list. Important: If you select postgresql-odbc, you must add the line, MaxVarcharSize=4000, to the datasource definition used in the .odbc.ini file. Number of connections to the database Enter the number of connections that you want the component to use for processing requests. Time in seconds between database connection heartbeats Enter the number of seconds after which the database connection should refresh. Do not set this value to zero without contacting Presence support. Is database debug logging enabled? (Advanced view only) Select 1 to log database debug information. Database logging uses the Presence XCP router’s logging facility, the jabberd Logger. The log level must be set to debug for database logging to occur. Administering Presence Services XCP Controller August 2010 55 Presence Session Manager (JSM) JSM features The JSM Features configuration section is available in the Presence XCP Controller’s Advanced configuration view. These parameters are used to enable and disable a number of miscellaneous server features. The JSM feature parameters are described in the following table. Name Description Apply Single Domain Name Support semantics to local user lookups Select Yes if you are using Single Domain Name Support (SDNS) for multiple JSMs. SDNS determines if a particular Jabber ID is a local user when users are spread across multiple domains. Allow invisible presence Select Yes if you want to allow users to set their presence to Invisible so that they can be online with the Presence Services server, but show up in their contacts’ rosters as offline. Allow restrictive offline Select Yes if you want to prevent the server from off-lining bounced messages that are empty. This setting affects message packets only. Automatically provision new users Select Yes if you want users who authenticate via SASL or x509 to be created automatically in the JSM database when they create a new session. With the Yes setting, you will no longer have to provision users in the JSM database as part of your new employee provisioning process. Stats The Stats feature, available in the Presence XCP Controller’s Intermediate configuration view, logs server statistics to the log types that are configured for the statistics logger. A Statistics logger has been set up by default in the Presence Services server configuration and logs infolevel data to $JABBER_HOME/var/log/stats-logger.log. The Stats option has been configured by default to capture data every 60 seconds. You can change the frequency if preferred. 56 Administering Presence Services XCP Controller August 2010 Agents Agents Agents display information relating to the corresponding component in the client interface. For example, if you configure a Text Conferencing component, the Text Conferencing agent enables the client to display the Text Conferencing interface to client users. To configure an agent, you must first select mod_agents under Optional modules. Important: Unless you have components that do not support XEP-0030: Service Discovery, we strongly recommend that you use the mod_disco module rather configuring agents. The mod_disco module uses the Service Discovery protocol to discover components automatically; therefore, with mod_disco, you do not have to configure agents. If you are not using mod_disco, you must configure an agent for each component that you add to your Presence Services server. The Agents configuration section is available in the Presence XCP Controller’s Intermediate configuration view. To add an agent for a component, select the agent in the list, and click Go. Legacy redirect to external components The Legacy Redirect to External Components configuration section is available in the Presence XCP Controller’s Advanced configuration view. This feature allows you to redirect packets to an external component. Before being redirected, packets are processed by the JSM like any other packets. This feature is still available in the JSM configuration to provide backwards compatibility for Presence Services servers that do not have the newer, more interactive EventBroker feature. Important: To use the Legacy Redirect feature, select mod_redirect under Optional modules. Static EventBroker events The EventBroker has replaced the Legacy Redirect to External Components feature, and is more interactive than the legacy feature. Whereas the legacy feature simply sends a copy of the packet to the external component, the EventBroker allows the component to send a Administering Presence Services XCP Controller August 2010 57 Presence Session Manager (JSM) response back to the JSM. The response can specify whether to pass or handle the packet. It can also change the contents of the packet; for example, it can remove sensitive information from the message body. Important: To use the Static EventBroker Events feature, select mod_eventbroker under Optional modules. The Static EventBroker Events configuration section is available in the Presence XCP Controller’s Advanced configuration view. You can configure Static EventBroker Events to redirect packets from JSM to custom external components that are written in any programming language. After processing the packets, the component can send responses back to JSM as needed. Configuring JDS The JDS Configuration feature lets you configure how the JSM and the Jabber Directory Component interact. You must enable this feature if you have configured, or plan to configure a Jabber Directory Component on your server. The JDS Configuration section is available in the Presence XCP Controller’s Basic and Intermediate configuration views. To configure JDS parameters 1. Select mod_jds under Optional modules. 2. Select the JDS Configuration option. 3. Configure the parameters as needed. The parameters that you enable here must match the JDS commands that you enable in the JDS Database configuration. Important: If you are configuring Active Directory, set the first two parameters to No. Result The JDS Configuration parameters are described in the following table, and the configuration view in which each parameter appears is indicated below its name. 58 Administering Presence Services XCP Controller August 2010 Configuring Roster Parameter Description Digest Authentication Select Yes if you want to allow users to log onto the server using Basic digest authentication rather than plain-text authentication. Important: For digest authentication to work, the LDAP database must be configured to use plaintext authentication. If LDAP uses hashed passwords, you must not enable digest authentication. Digest authentication is more secure than plaintext authentication. When the client connects to the server, the Connection Manager passes a session ID to it. The session ID is SHA-hashed with the client’s password and returned to the server. The server authenticates the client based on this value. Community Groups Basic Select Yes if you want to allow users to access community groups through the client software. Offline SMTP Basic Select Yes if you want to redirect messages that are sent to offline users to an email server. VCard Basic Select Yes if you want to allow users to enter vCard information for themselves and to query the vCard information of other users. Use Proxy Authentication Intermediate Select Yes if you want to enable proxy authentication, which allows a user to bind to the LDAP database as one user and proxy as another user. This feature enables UserA to pass a control that assumes the rights of UserB for the duration of a database operation. Configuring Roster The Roster Configuration section is available in the Presence XCP Controller’s Advanced configuration view. Select the Roster Configuration option if you want to change the default setting (150) for the maximum number of items that users can have in their rosters. This feature limits how much space rosters require on your Presence Services server. Roster items include contacts, pending contacts, and any other item that appears in the roster. Configuring Sendmail The sendmail feature allows IM client users to send transcripts of chat and conference room conversations via email. To use this feature, you must also configure a Connection Manager Administering Presence Services XCP Controller August 2010 59 Presence Session Manager (JSM) with an SMTP command processor; if you do not have an appropriately configured Communication Manager, the server ignores the sendmail parameters. The Sendmail Configuration section is available in the Presence XCP Controller’s Basic configuration view. To configure the Sendmail feature 1. Configure a Connection Manager with an SMTP command processor. 2. In the Presence Session Manager Configuration page, select mod_sendmail under Optional modules. 3. Select the Sendmail Configuration option, and configure the following parameters. Parameter Description Service ID of the SMTP processor Enter the ID of the SMTP command processor that will send the mail. Default reply address for email Enter a default email address to which replies should be sent if the Presence Services server is unable to determine the email address of the sender. Configuring Offline SMTP The offline SMTP feature redirects messages that are sent to offline users to an email server. To use this feature, you must also configure a Connection Manager with an SMTP command processor; if you do not have an appropriately configured Communication Manager, the server ignores the offline SMTP parameters. The Offline SMTP Configuration section is available in the Presence XCP Controller’s Basic configuration view. To configure the Offline SMTP feature 1. Configure a Connection Manager with an SMTP command processor. 2. In the Presence Session Manager Configuration page, select mod_offline_smtp under Optional modules. 3. Select the Offline SMTP Configuration option. 4. Configure the following parameters. 60 Administering Presence Services XCP Controller August 2010 Configuring Registration Requirements Parameter Description Service ID of the SMTP processor Enter the ID of the SMTP command processor that you configured to send the mail. Default reply address for email Enter a default address to which any replies should be sent. If the Presence Services server is unable to determine the email address of the sender, it automatically plugs in this address. Configuring Registration Requirements The Registration Requirements feature, which is enabled by default, lets client users create accounts on the Presence Services server. It also lets you configure the information and prompts that display in the client interface when users register. Important: If you are using the Jabber Directory Suite, clear the check box beside Registration Requirements to disable the feature. The JSM Registration feature does not work with JDS. The Registration Requirements configuration section is available in the Presence XCP Controller’s Basic and Intermediate configuration views. To configure registration requirements 1. Change to the Presence XCP Controller’s Intermediate configuration view. 2. Select mod_register under Optional modules. 3. Under Registration Requirements, select the registration fields that you want to display on the client. 4. Configure the following parameters as needed. Parameter Description Anyone can register in When set to Yes, anyone can create an account on this band with this server server using Jabber (pre-XMPP) protocol. If you select No, users cannot register in band. Behavior when a user unregisters Administering Presence Services XCP Controller Select the action the server should take when a user unregisters. The default setting is remove, which removes the user from the database. The disable option disables the user’s account without removing them from August 2010 61 Presence Session Manager (JSM) Parameter Description the database. The not-allowed option prevents users from unregistering. Registration Message The server uses these parameters to send an instant welcome message to newly created accounts. If you want to change the wording of a message, you must modify your dictionary file. Type of message Select normal, chat, or headline for the type of registration message you want sent. The Presence clients always use the chat type, which sends welcome messages in a chat window. You can select another message type if you are using a custom client. For example, a headline type could be a pop-up message, and a normal type could be a message sent in a window containing a Reply button. You must define these types as you plan to use them with your custom client. Enable welcome messages Select Yes if you want the server to send a welcome message to users after they register. Authorization The Presence Services server provides authorization capabilities for instant messaging through the Presence Session Manager, and for conference room participation through the Text Conferencing component. To make use of these capabilities through Presence XCP, you must provide your own custom component that provides authorization services. An authorization component generally provides black- and white-listing capabilities by controlling who can and cannot communicate with each other through the Presence Services server. JSM Logging The JSM Logging feature lets you log message, session, and presence packets in addition to the JSM-generated packets that are logged by the server by default. 62 Administering Presence Services XCP Controller August 2010 Configuring HTTP Digest Module Configuring HTTP Digest Module Select the Configuration for the HTTP digest module option if you are using a custom component or the JDS component for authentication. All authentication requests will be sent to the component that handles the http digest namespace. This feature is available in the Presence XCP Controller’s Intermediate configuration view. To configure the HTTP digest module 1. Change the Presence XCP Controller’s Intermediate configuration view. 2. Select mod_http_digest under Optional Modules. 3. Scroll to the bottom of the Presence Session Manager Configuration page, and select Configuration for the HTTP digest module. Configuring personal eventing The Personal Eventing feature is an implementation of the protocols that are described in XEP-0163: Personal Eventing via Pubsub (http://www.xmpp.org/extensions/xep-0163.html) and in XEP-0115: Entity Capabilities (http://www.xmpp.org/extensions/xep-0115.html). The Personal Eventing feature allows the broadcast of state change events that are associated with an IM and presence account, and tailors the broadcast to the capabilities of the receiving entity. The Personal Eventing feature is available in the Presence XCP Controller’s Advanced configuration view. To configure the Personal Eventing feature 1. Change to the Presence XCP Controller’s Advanced configuration view. 2. Select mod_caps and the mod_pep under Optional modules. The mod_caps module is enabled by default, and uses the Entity Capabilities described in XEP-0115. The mod_pep module enables Personal Eventing through PubSub, as described in XEP-0163. 3. Scroll to the bottom of the Presence Session Manager Configuration page, and select the Personal Eventing Configuration feature. Administering Presence Services XCP Controller August 2010 63 Presence Session Manager (JSM) Default values are provided. 4. If needed, change the default values. Keep in mind that these values impact both memory (caching) and disk storage. Result The parameters are described in the following table. Parameter Description Maximum number of seconds a user’s nodes are cached Enter the maximum number of seconds that a user’s nodes are cached in memory. After this time has elapsed with no activity on the node, the node is deleted. The default value is 14400 seconds, or 4 hours. Maximum number of nodes per user Enter the maximum number of nodes that each user can create. Maximum number of items per node Enter the maximum number of items that each node can contain. Maximum item size in XML bytes Enter the maximum size of each item in bytes. Configuring SNMP Select the SNMP Configuration option if you want to configure SNMP for the Presence Session Manager. Configure the parameters as follows. Parameter 64 Description Enable SNMP Intermediate This parameter is set to Yes by default. Count errors Advanced Select Yes only if you want to enable SNMP error counting. This option takes a great deal of server resource; use it with caution. Administering Presence Services XCP Controller August 2010 Chapter 4: Authorization Authz Authorization T he XCP Server provides authorization capabilities for instant messaging through the Presence Session Manager (JSM), and for conference room participation through the Text Conferencing (TC) component. To make use of these capabilities through XCP, you must provide your own custom component that provides authorization services. An authorization component generally provides black- and white-listing capabilities by controlling who can and cannot communicate with each other through the XCP server. The protocol with which this component must comply is described in Authorization Protocol . Authorization allows you to track communication between users for various purposes, and to block communications between unauthorized peers. For JSM, a list of permitted communication peers is maintained within the context of a user’s session. For the TC component, the same is true within the context of text conference rooms; users who are not permitted to communicate cannot be in the same conference room concurrently. Authz authorization is used only for controlling user-to-user requests and not user-to-domain requests. When authz is enabled, an IQ request made by a user to the domain for his or her roster will not go through authz. However, a request sent by a user to another user will go through authz. Related topics: XCP Server Configuration on page 65 Authorization Protocol on page 69 Design Notes on page 72 Security Considerations on page 73 Authorization Manager Configuration on page 74 XCP Server Configuration This section describes how to configure authorization for Presence Session Manager and for Text Conferencing. Enabling Authorization for the Presence Session Manager You can enable and configure authorization in the JSM if you want to control who can and cannot communicate via instant messaging through the XCP server. Administering Presence Services XCP Controller August 2010 65 Authorization Related topics: To configure authorization for JSM on page 66 Enabling Authorization for Text Conferencing on page 68 To configure authorization for JSM 1. Change to the controller’s Advanced configuration view. 2. In the Router area on the controller’s main screen, click Edit beside the Presence Session Manager. 3. In the Presence Session Manager Configuration screen under Optional Modules , click the check box beside mod_authz to enable the module. 4. Scroll down toward the bottom of the page and select the Authorization Configuration option. 5. Configure the parameters as follows. Parameter 66 Description Jid matching rules Select ’bare’ or ’full’ depending on whether you want the authz module to authorize nodes based on their bare (node@domain) or full (node@domain/resource) JIDs. The module will always try to send a JID that corresponds to the option selected, but it cannot ensure that a full JID will always be available. Query local Select ’in’ or ’out’ depending on when you want authorization requests to be sent for stanzas that originate from and are destined to a local node. We recommend that you set this option to ’in’ whenever a full JID is preferred for authorization requests. Since a stanza from a local node to a local node has only full JIDs available for both from and to attributes when it enters a session, using the ’in’ option makes sense. If you set Query local to ’out’, authorization requests are dispatched when the stanza leaves the session of the from attribute. Using the ’out’ option is more efficient; however, it does not guarantee that the full JID will be available for the to attribute on the stanza. Include original stanza in request? Select Yes or No depending on whether you want to include the original stanza in the authorization request. Administering Presence Services XCP Controller August 2010 Authz Authorization Parameter Description Default behavior Select ’pass’ or ’authorize’ depending on how you want the authz module to handle authorization requests by default. A setting of ’pass’ causes the module to pass all stanzas through without authorization except for those that match what is configured in the Exceptions to default handling area. A setting of ’authorize’ causes the module to authorize all stanzas except for those that match what is configured Exceptions. Time to live for authz requests Enter the number of seconds to cache results from the custom authorization component. If you set this option to ’0’, results are not cached unless they explicitly contain expiration information. Default permission Select ’allow’, ’deny’, or ’force’ depending on how you want the authz module to handle situations in which an error response is received for the authorization request. The 'allow' option allows the packet to be sent to the user, who can then accept or deny the request. The ’deny’ option blocks the delivery of all packets when the module receives error responses to its authorization requests. The 'force' option allows an external mechanism to handle the authorization. The user never sees the packet. Note: If this option is set to ’deny’ and the server stops, no messages or presence packets are sent. Force the use of default values for all requests Select Yes if you want the server to respond to all client authentication requests using the default values. This setting is useful when you do not have a custom authentication component. If you select No, the XCP server looks for an external authentication component. If such a component exists, the component sends a response regarding the request. If an external component does not exist, Jabberd must send a response to JSM saying to use the default values. Exceptions to default handling Select this option if you want to configure exceptions to the default settings. Click Go beside an exception to configure it. Administering Presence Services XCP Controller August 2010 67 Authorization Parameter Description Stanza Exception lets you set up exceptions for certain stanza types, such as presence or iq. JID Exception lets you enter JIDs for either from or to attributes on a packet. Namespace Exception lets you specify a namespace to which the exception applies, and to configure string-matching rules for message subjects and bodies. 6. If you want to configure exceptions to the rules that you have set in the previous parameters, select Exceptions to default handling . 7. Click Go beside the exception that you want to configure. These exceptions apply to the Default behavior setting. For example, if you set the default behavior to pass , all exceptions will be authorized. You can configure multiple exceptions in each category. Stanza Exception lets you set up exceptions to the default behavior for certain stanza types, which include message , presence , or iq . JID Exception lets you specify JIDs that are exempt from the JID matching rules setting. If you selected bare for JID matching rules , you must enter a bare JID in this screen. Likewise, if you selected full , you must enter a full JID in this screen. If you leave the expression matching parameter set to false , authorization will be based upon an exact match to the specified JID. Namespace Exception lets you specify a namespace to which the exception applies, and to configure string-matching rules for message subjects and bodies. This exception is primarily used to except message events that have a blank body and subject, as shown in the following figure. The ”jabber:x:event” namespace applies to the ”is replying” message event. 8. Scroll to the bottom of the Presence Session Manager Configuration screen, and click Submit to save your configuration. Enabling Authorization for Text Conferencing You can enable the Authorization Gear in the Text Conferencing component if you want to control which users cannot be in the same text conference rooms at the same time. When you enable this gear, everything that the TC component handles is checked by the custom component. Note: Your Authorization component must be running before the Text Conferencing component starts. If the component is not running, rooms will not load. 68 Administering Presence Services XCP Controller August 2010 Authz Authorization Text Conferencing does not pay attention to the time-to-live setting, which is the number of seconds that the custom component’s results are cached. Related topics: To configure Authorization for TC on page 69 To configure Authorization for TC 1. Change to the controller’s Advanced configuration view. 2. In the Components area on the controller’s main screen, click Edit beside Text Conferencing . 3. In the Text Conferencing Configuration screen, scroll down to the TC Configuration area. The Authorization Gear is the first gear displayed under Advanced TC Features . 4. Select the Authorization Gear option. You can enter a custom library if needed; however, this is not necessary. 5. Scroll down to the bottom of the screen, and click Submit to save your configuration. 6. Start your custom authorization component. If your component is not running when you restart the TC component, no TC rooms will load. 7. Restart your system. Authorization Protocol This section describes the protocol with which your custom authorization component must comply. Related topics: Authorization Flow on page 69 XDB Authorization Protocol on page 71 Cache Reset Protocol on page 72 Authorization Flow Upon receiving a packet, JSM will dispatch an XDB request on behalf of the user to request authorization for the attempted operation. A request can either be allowed or denied. Administering Presence Services XCP Controller August 2010 69 Authorization Allowed An allowed communication has the following flow: 1. [email protected] sends a <message> stanza to [email protected]. 2. JSM receives message from [email protected]. 3. JSM dispatches an <xdb type=’get’> to authorize communication between [email protected] and [email protected]. 4. External component dispatches <xdb type=’result’> to JSM that allows communications between [email protected] and [email protected]. 5. JSM allows <message> from [email protected] to be delivered to [email protected]. Denied A denied communication has the following flow: 1. [email protected] sends a <message> stanza to [email protected]. 2. JSM receives message from [email protected]. 3. JSM dispatches an <xdb type=’get’> to authorize communication between [email protected] and [email protected]. 4. External component dispatches <xdb type=’result’> to JSM that denies communications between [email protected] and [email protected]. 5. JSM bounces <message> back to [email protected], adding a type=’error’ attribute, and a <error code=’401’>Unauthorized</error> element. Forced A forced communication has the following flow: 1. [email protected] sends a <message> stanza to [email protected]. 2. JSM receives message from [email protected]. 3. JSM dispatches an <xdb type=’get’> to authorize communication between [email protected] and [email protected]. 4. External component dispatches <xdb type=’result’> to JSM expressing that the communication between [email protected] and [email protected] should be forced 5. JSM sets a ”forced” bit in the mapi_struct. This can be used by other modules to know that the authorization component has asserted that no further authorization is required. This allows other modules to process differently based on the value of the flag. 70 Administering Presence Services XCP Controller August 2010 Authz Authorization XDB Authorization Protocol Authorization Consumer requests authorization decision The protocol that is used to request authorization is a XDB type=’get’ request. <xdb type='get' id='01' ns='http://www.jabber.com/schemas/authz.xsd'> <query xmlns='http://www.jabber.com/schemas/authz.xsd'> <action>getAuthorization</action> <operation>chat</operation> <subject> <jid>[email protected]</jid> </subject> <resources> <item type='user'>[email protected]</item> <item type='user'>[email protected]</item> <item type='user'>[email protected]</item> <item type='room'>[email protected]</item> </resources> </query> </xdb> The XDB request conforms to the standard for JDS requests. The <action/> element describes the JDS action requested. For the authorization protocol, this MUST be ”getAuthorization”. The <operation/> element describes the feature we’re requesting authorization for. For normal one-to-one messaging, this will be described as ”chat”, but other features will have other values for the <operation/> element. For example, conferencing may use the value ”enter” to query whether a user is allowed to enter a room. The <subject/> element refers to the subject of the system who is requesting authorization to perform the specified operation. The requesting entity should be identified by a JID in a <jid/> element inside the <subject/> element. The <resources/> element contains a list of items that the subject is requesting authorization to perform the operation on. Each <item/> should have a ”type” attribute that describes the type of entity that the <subject/> is trying to communicate with. The contents of the <item/> element should be the JID of the target. In the previous example, the server is querying to find out if the entity [email protected] is allowed to send messages (chat) with the nodes [email protected], [email protected] and [email protected], and the chat room [email protected]. It is important to note that as an implementation specific detail that where JIDs are used in the previous protocol, they can be either host only (example.com), bare ([email protected]) or full ([email protected]/ resource) identifiers. Authorization Service returns authorization decision <xdb type='result' ns='http://www.jabber.com/schemas/authz.xsd' id='01'> <query xmlns='http://www.jabber.com/schemas/authz.xsd'> <allow> <item type='user' expires='CCYY-MM-DDThh:mm:ssZ'>[email protected]</item> <item type='room' expires='CCYY-MM-DDThh:mm:ssZ'>[email protected]</item> </allow> <deny> Administering Presence Services XCP Controller August 2010 71 Authorization <item type='user' expires='CCYY-MM-DDThh:mm:ssZ'>[email protected]</item> <item type='user' expires='CCYY-MM-DDThh:mm:ssZ'>[email protected]</item> </deny> </query> </xdb> The response sent by the server should contain lists of items that the queried entity is allowed (<allow/> element) and denied (<deny/> element) the ability to perform the provided <operation/> with. In the previous example, the entity [email protected] is allowed to send messages (chat) with the user [email protected] and the chat room [email protected], but not the nodes [email protected] or [email protected]. The ”expires” attribute on the <item/> is the date at which the module is required to requery authorization for this user. If it is not specified the module MAY use a default cache lifetime, or request authorization for each operation. The component can force the module to always request authorization for each operation by specifying the current date and time for the ”expires” element. Cache Reset Protocol Administrator Resets a User’s Authorization Cache Functionality may exist that allows an administrator to reset the authorization cache. <iq type='set' id='authz01' to='tolkien.lit'> <query xmlns='http://www.example.com/schemas/authz.xsd'> <action>resetAuthz</action> <list> <jid>[email protected]</jid> <jid>[email protected]</jid> </list> </query> </iq> Server Returns Success <iq type='result' id='authz01' from='tolkien.lit'/> Design Notes The proposed implementation consists of a number of components which, through their interaction, will prevent communication between Presence nodes without prior authorization. JSM module <message>, <presence>, and <iq> stanzas should be authorized before they are delivered. Optionally, an implementation may use an in-memory cache of permitted and prohibited communication peers. If a cache entry is not found, the JSM module will make the appropriate authorization request to update the cache with the appropriate data. The packet will be permitted or bounced based on the value of the permit/prohibit flag associated with the peer. 72 Administering Presence Services XCP Controller August 2010 Authz Authorization External authorization component To provide authorization services for multiple components within the XCP system, an external component that supports the xdb protocol defined in this document must be present. Text conferencing authorization Authorization rules could also apply to communications within Text Conference rooms. To accomplish this goal, the authorization request callout could be modified to authorize a ”room join” attempt using the XDB authentication protocol. This operation need only apply to the presence packet sent to join a room, as barring entry to a room will be sufficient to prevent communication between prohibited peers. The following rules could be used: User join will be permitted only if the user may communicate with all nodes currently in the room. Billing and logging rules Another use of this authorization protocol could be billing, or counting of communications between two endpoints. Since all packets that pass through the JSM module could trigger an XDB authorization request (provided caching was disabled), a smart external component could make decisions on whether a packet is allowed to be delivered based on this information. Consider the following rules: • Local domain communications (from ’[email protected]/wireless’ to ’[email protected]/wired’) would require an outgoing check to the authorization component. This would fall under the standard <operation/> of ”chat”. • Messages originating from the local domain and destined for a remote domain (from ’[email protected]/wireless’ to ’[email protected]/wired’), would require an outgoing check to the authorization component. This would fall under the standard <operation/> of ”chat”. • Messages originating from a remote domain and destined for a local domain (from ’[email protected]/wired’ to ’[email protected]/wireless’) would require an incoming check to the authorization component. This would fall under the standard <operation/> of ”chat-incoming”. Using these rules, an external component should be able to determine if communication should be allowed between the nodes, [email protected]/wireless, [email protected]/wired, and [email protected]/wired, based on information stored in a database, and their JIDs. The component could, for example, determine that ’[email protected]/wireless’ is not allowed to receive messages from ’[email protected]/wired’ (as described previously in rule 3), because [email protected]/wireless hasn’t sent enough messages to nodes with the resource of ”wired”. Security Considerations The proposed implementation provides for authorization of <message>, <presence>, and <iq> packets sent through JSM, as well as <presence> packets sent to the Text Conferencing service to join a user to a TC room. Any services or functionality provided by a XCP installation Administering Presence Services XCP Controller August 2010 73 Authorization that don’t meet these criteria will not be subject to authorization without additional integration effort. Authorization Manager Configuration This section provides a reference for all of the parameters associated with the Authorization Manager. The parameters are divided into subsections based on the configuration view in which they display. Basic Parameters The following table describes the parameters that display in the controller’s Basic configuration view. The basic parameters are sufficient to configure an operational Presence component. Parameter Description Description The description is displayed in the Components area on the controller’s main page and should help you distinguish between components of the same type when you have more than one configured. You can change the description as needed. ID The component ID Description The component description Intermediate Parameters Parameters that display in the Presence component’s Intermediate configuration view. Parameter Description Router Outbound Connection Information Select this option only if you want the XCP router to connect to the component. For example, if the component is running outside your firewall, this option allows the router to connect to the component safely rather than introducing security risks by letting the component connect to it. By default, components connect to the router using the router’s Master Accept Port. Component IP Enter the IP address or host name of the system on which the component is installed. Port Enter the port that the component uses for communications. Password Enter the password that the router uses to authenticate the component. Execute an External Command 74 Administering Presence Services XCP Controller August 2010 Authz Authorization Parameter Description This option allows the router to start the component automatically. If you prefer to start the component from a command line, disable this option. Command line to run A command that runs the component automatically is provided by default. You can modify it if needed. Do not use the -B argument with this component. Since the PS logger is already a daemon process, its children must not be daemons. You should not redirect output, because all output to STDOUT and STDERR will be redirected to /dev/null. Hostnames for this Component This option specifies the hosts for which this component will handle packets. Specify a host filter only if you want the component to be externally addressable; for example, if you want clients and other components or programs to communicate with it. This is because the mod_disco module in JSM uses host filters to return the component as something that should be discoverable. Host Filters Enter the host names or IP addresses for which you want this component to handle packets. Separate each host name or address with a line break. Host filters must be host names, or IPv4 or IPv6 addresses. If you use an IP address, the packet address must also use this IP address. XDB Namespace Filters Enter the namespaces for which you want this component to handle xdb messages. Separate each namespace with a line break. XDB Host Filters Enter the host names or IP addresses for which you want this component to handle xdb requests. Separate each host name or address with a line break. Host filters must be host names, or IPv4 or IPv6 addresses. If you use an IP address, the packet address must also use this IP address. Advanced Parameters The following table describes the parameters that are displayed in the ACL Pending Manager component’s Advanced configuration view. Most of the advanced parameters are used for adjusting the Presence server’s performance. Default values have been provided for these parameters, and in most cases, these values are sufficient. We recommend contacting technical Support if you want to change the values. Administering Presence Services XCP Controller August 2010 75 Authorization Parameter Description Runlevel Enter the order in which this component shuts down. The runlevel must be an integer value greater than or equal to 0. Component shutdown is executed in reverse order of the specified runlevel; components with the highest level (typically 70) shut down first. Do not change the runlevel unless you know exactly what you are doing and understand the effects that changing it will have. The default runlevel is provided to help the system shut down as smoothly as possible, and is based on this component's dependencies upon other components. Timeout for shutdown Enter the number of seconds that the server waits to receive acknowledgement from the component that the shutdown process has completed. If the component has not shut down by the time this time period has elapsed, the router leaves the process in its current state and continues shutting down other processes. Number of packets buffered when component is down Enter the number of packets bound for the component that should be buffered if the component goes down. Bounce error packets to stderr Select Yes if you want the router to send warnings to stderr when the component is down. Router Outbound Connection Information Select this option only if you want the XCP router to connect to the component. For example, if the component is running outside your firewall, this option allows the router to connect to the component safely rather than introducing security risks by letting the component connect to it. By default, components connect to the router using the router’s Master Accept Port. 76 Buffer size in bytes for outgoing data Enter the number of bytes the router should buffer when it sends information to the component. You may want to modify this element when working on performance enhancements. Buffer size in bytes for incoming data Enter the number of bytes the router should buffer when it receives information from the component. You may want to modify this element when working on performance enhancements. Component IP Enter the IP address or host name of the system on which the component is installed. Administering Presence Services XCP Controller August 2010 Authz Authorization Parameter Description Port Enter the port that the component uses for communications. Password Enter the password that the router uses to authenticate the component. Execute an External Command This option allows the router to start the component automatically. If you prefer to start the component from a command line, disable this option. Command line to run A command that runs the component automatically is provided by default. You can modify it if needed. Do not use the -B argument with this component. Since the PS logger is already a daemon process, its children must not be daemons. You should not redirect output, because all output to STDOUT and STDERR will be redirected to /dev/null. Hostnames for this Component This option specifies the hosts for which this component will handle packets. Specify a host filter only if you want the component to be externally addressable; for example, if you want clients and other components or programs to communicate with it. This is because the mod_disco module in JSM uses host filters to return the component as something that should be discoverable. Host Filters Enter the host names or IP addresses for which you want this component to handle packets. Separate each host name or address with a line break. Host filters must be host names, or IPv4 or IPv6 addresses. If you use an IP address, the packet address must also use this IP address. XDB Namespace Filters Enter the namespaces for which you want this component to handle xdb messages. Separate each namespace with a line break. XDB Host Filters Enter the host names or IP addresses for which you want this component to handle xdb requests. Separate each host name or address with a line break. Host filters must be host names, or IPv4 or IPv6 addresses. If you use an IP address, the packet address must also use this IP address. Administering Presence Services XCP Controller August 2010 77 Authorization Licensing Licensing within Presence Services is used to restrict the number of users that can be downloaded by the Presence Server. A License is installed on the System Managers WebLM Server and user licenses are requested by Presence Services as required. Licensing status can be monitored by the presstatus command line tool ($PRES_HOME/ presence/bin/presstatus) or by monitoring logs and alarms. See Command line tools Validity License validity is evaluated based on three criteria: • Named feature (number of users) • Version • Expiration date Named feature is a feature representing the number of allowed users. The version of the product must match the allowed version of the installed license. The expiration date on the license must not be exceeded. For each criteria the status may be valid, grace or expired. Valid status means that licensing is in a valid state and working normally. Grace means that the license is no longer valid, this state may be sustained for 30 days. The Presence Services license must be in a valid state for over 24 hours and the user must have made an attempt to request licenses from WebLM before the 30 day count is reset. Expired means that the grace period is exceeded. If there is no license installed or communication failed with the licensing server then the grace period started. Configuration Licenses must be requested and installed on System Manager. Login to System Manager, navigate to Licenses on the menu and select Server Properties. Copy the first MAC address listed (Primary Host ID) and send it in the request indicating the maximum number of users that may be required. When a license file is received, use the licensing configuration page to install the license by selecting the Install option, indicating the location of the license file. The license can now be navigated using the menu when the Presence Services is operational by clicking on the “Licensed Products” link. As licenses are acquired and dropped they are displayed at the link. Licensing within Presence Services is configured at installation time using the following variables within the silent install file: • LICENSING_POLL_INTERVAL=300 • LICENSING_RENEW_INTERVAL=300 • PANTHER_HOST=pantherhost.example.com 78 Administering Presence Services XCP Controller August 2010 Licensing The interval values should not be adjusted below 300, the PANTHER_HOST value is required for multiple components. Once installed, the above variables can be accessed from the “presence-container-1” component (Presence Server) within the Web CM. Administering Presence Services XCP Controller August 2010 79 Authorization 80 Administering Presence Services XCP Controller August 2010 Chapter 5: Access EventBroker T his chapter describes how to configure the EventBroker, which redirects Presence Session Manager (also known as the JSM) and Text Conferencing (TC) packets to external components. For example, if you have your own authentication system, you may want to copy all authentication packets to your system in addition to using the XCP server’s authentication functionality. The EventBroker can be configured as a module in the JSM and as a gear in the TC component. Important: To configure the EventBroker, you must installed the XCP extras installation package. The EventBroker is more interactive than the ”Legacy Redirect to External Components” feature. Whereas the legacy redirect feature simply sends a copy of the packet to the external component, this EventBroker allows the component to respond to JSM or TC. The response can specify whether to pass or handle the packet. It can also change the contents of the packet; for example, it can remove sensitive information from the message body. Redirected packets are not copies of the packets that are sent to TC or JSM. Rather, when TC and JSM receive packets, they send them on to the external component. The external component processes the packets and sends them back to TC or to JSM, which then handles the packets as needed. If enabled, the following modules will always process the packet before the external component: • mod_log • mod_authz • mod_eventbroker Related topics: Configuring the EventBroker for the Presence Session Manager on page 82 Configuring the EventBroker for Text Conferencing on page 83 OpenPort Configuration on page 84 Example Component on page 85 Protocol: Event Access from External Components on page 89 Administering Presence Services XCP Controller August 2010 81 Access Configuring the EventBroker for the Presence Session Manager This section describes how to configure the EventBroker for the Presence Session Manager. Related topics: To configure the EventBroker for JSM on page 82 To configure the EventBroker for JSM 1. Change to the Controller’s Advanced configuration view. 2. In the Router area on the controller’s main page, click the Edit link beside Presence Session Manager . 3. In the Presence Session Manager Configuration page under Optional modules , select mod_eventbroker . 4. You must specify a timeout interval to wait for the external component to respond after a request has been sent. To do this, scroll down to the System Parameters section, and change the setting for Timeout for XDB requests to a value greater than '0'. When the timeout interval expires, JSM sends the request either to the next external component or to the next module that might handle the event. 5. Scroll further down, and select the Static EventBroker Events option. 6. Click Go to display the EventBroker Event Configuration page. 7. Configure an event as follows: a. Select an Event and a Type in the corresponding drop-down lists. (Events and types are described in the online help.) b. If you selected a Type of ”iq”, you can enter an iq namespace in the IQ Namespaces text box; for example, jabber:iq:register . IQ packets that are sent to the external component will be filtered on this namespace. If you leave this box blank, all IQ packets will be sent to the component. c. In the JID(s) text box, enter the ID and realm (in the format ID.realm ) of at least one external component to which the selected event will be redirected. d. For Event/Error handling , select whether to bounce error packets or to pass them to the external component. e. For Fire and Forget? , leave the default setting of No if you want to include the event as part of the chain. If this is a fire-and-forget event, select Yes . 82 Administering Presence Services XCP Controller August 2010 EventBroker f. Click Submit to save your configuration. You are returned to the Presence Session Manager Configuration page. You can add more events as needed. 8. If you want to add events that are not included in the Event list in the EventBroker Event Configuration page, enter the names of configuration elements that contain redirection rules in the External redirection rules box. The contents of these elements must match the schema for what is expected in the mod_external.jig file. 9. Configure an OpenPort component for your external component as described in OpenPort Configuration . If you plan to configure redirection for TC as well, you can use the same OpenPort for both JSM and TC. Configuring the EventBroker for Text Conferencing In the Text Conferencing configuration, you can configure the EventBroker gear to redirect a number of event packets to one or more external components. Related topics: To configure the EventBroker for Text Conferencing on page 83 To configure the EventBroker for Text Conferencing 1. Change to the Controller’s Advanced configuration view. 2. In the Components area on the controller’s main page, click Edit beside Text Conferencing . 3. In the Text Conferencing Configuration page, scroll down to the Advanced TC Features area, and select EventBroker Gear . 4. Click Go to access the EventBroker Event Configuration page. 5. Configure an event as follows: a. Select an Event in the drop-down list. Events are described in the online help. b. In the JID(s) text box, enter the ID and realm (in the format ID.realm ) of at least one external component to which the event will be redirected. c. For EventError handling, select bounce or pass . This option determines the action that the TC component will take if the external component returns an error or does not respond. Administering Presence Services XCP Controller August 2010 83 Access d. For Fire and Forget?, leave the default setting of No if you want to include the event as part of the chain. If this is a fire-and-forget event, select Yes. e. When you have finished, click Submit to save your configuration. 6. Configure an OpenPort component for your external component. OpenPort Configuration In addition to configuring EventBroker events in JSM and TC, you must configure an OpenPort for each external component that you have. You can use the same OpenPort for both JSM and TC; however, you can configure separate OpenPorts if you prefer. The important thing to remember is that you must configure a separate OpenPort for each external component. Related topics: To configure an OpenPort on page 84 To configure an OpenPort 1. In the Components area on the controller’s main page, select OpenPort in the list, and then click Go . 2. At the prompt, enter the external component’s ID as the ID of the OpenPort, and click OK . Do not enter the realm. Note: The OpenPort ID must match the JID you entered in the JID(s) text box in the EventBroker Event Configuration page. 3. In the OpenPort Configuration page, click the check box beside Router Outbound Connection Information , and enter the Component IP , Port , and Password for the listening socket. 4. Scroll down and select the XDB option. 5. Do the following: a. In the Namespace Filters textbox, enter the XDB namespaces for the events you are redirecting to this component. For example, if event e-session is being redirected, enter jsm:e_SESSION . The namespace that you entered in the TC or JSM EventBroker Event Configuration page does not go here. The namespaces that you can enter here are defined in the ”Event Access from External Components” protocol described 84 Administering Presence Services XCP Controller August 2010 EventBroker in the following section. The event types and their associated namespaces are listed in the section, Event Types . b. In the Host Filters textbox, enter the JID of the external component. This must match the JID that you entered for the component in the EventBroker Event Configuration page. 6. Click Submit at the bottom of the page to save your configuration. 7. Restart the XCP system. 8. Start the external component so that it connects with IPS logger on the OpenPort. The Component IP, Port, Password, and ID of the component must match the values configured for the OpenPort. Example Component This section contains an example component, eventbroker.java, which illustrates external component redirection by changing the phrase ”foo” to ”f**”. The component’s code is provided in EventBroker.java , and the protocol that it uses is described in Protocol: Event Access from External Components . Related topics: Initial Setup on page 85 To configure a redirect instance and an OpenPort on page 85 EventBroker.java on page 87 Initial Setup Some initial setup is required before you can run the EventBroker component. You must configure your redirect instance and an OpenPort component before you can run the EventBroker component. To configure a redirect instance and an OpenPort 1. Change to the Controller’s Advanced configuration view. 2. Edit the Presence Session Manager. and select the mod_eventbroker module. 3. In the Presence Session Manager Configuration page under Optional modules , select mod_evenbroker . Administering Presence Services XCP Controller August 2010 85 Access 4. Scroll down, and select the Static EventBroker Events option. 5. Click Go to display the EventBroker Event Configuration page. 6. Configure the event as follows: a. In the Event list, select es_out . b. In the Type list, select message . c. In the JID(s) box, enter eventbroker.jabber (assuming you used the default values when installing XCP and selected ’presence’ as the realm). d. Set Event/Error handling to bounce . e. Leave Fire and Forget? set to No . 7. Click Submit to save your configuration. You are returned to the Presence Session Manager Configuration page. 8. Click Submit again to return to the Controller’s main page. 9. Add an OpenPort component as described in OpenPort Configuration . Enter EventBroker for the ID. 10. In the OpenPort Configuration page, select the XDB option, and do the following: a. Enter jsm:es_OUT in the Namespace Filters box. b. Enter * in the Host Filters text box. 11. Click Submit to save your configuration. 12. Restart the XCP system. Next steps Be sure to perform the EventBroker final tasks and to do the EventBroker component testing Related topics: Final tasks on page 86 Component testing on page 87 Final tasks You must perform the following tasks before you can run the EventBroker component: 1. Make sure that ’.’ and all of the JAR files in $JABBER_HOME/lib are in your classpath. 2. Compile the source using the following command: javac -g eventbroker.java 3. Run the EventBroker component using the following command: 86 Administering Presence Services XCP Controller August 2010 EventBroker java eventbroker -h localhost -n eventbroker.jabber -p 9000 s test -d debug The OpenPort component that you configured for the EventBroker should display a green status of ”Running” on the Controller’s main page. Component testing You can test your EventBroker component as follows: 1. Log into the client using two separate users. 2. Send the message ”bar” from one user to the other. The other user should receive the message, ”bar.” 3. Now send the message ”foo” from one user to the other. The other user should receive the message, ”f**.” EventBroker.java package com.jabber.jcore.example; import import import import import import import org.jdom.Element; com.jabber.jcore.jax.Component; com.jabber.jcore.jax.Connection; com.jabber.jcore.jax.ConfigException; com.jabber.jcore.util.XMPPUtil; com.jabber.jcore.util.DOMUtil; com.jabber.jcore.util.logging.Jlog; /** * An example EventBroker component that blocks unwanted words. */ class EventBroker extends Component { /** * Constructor. */ public EventBroker() { super("1.0.0", Component.PROTOCOL_1_0); } /** * This method is used to configure the component. * * @param conn * The router connection. * @param config * The config element sent by the router. * @throws ConfigException * Thrown when the component configuration is not suitable for * configuration. Note that the router connection is closed when Administering Presence Services XCP Controller August 2010 87 Access * a component fails to configure. */ public void onConfig(Connection conn, Element config) throws ConfigException { Jlog.debug("EventBroker.onConfig:\n" + DOMUtil.domToString(config)); // Nothing to do here } /** * This method is invoked for each stanza addressed to this component. * * @param conn * The router connection. * @param packet * An XMPP stanza. */ public void onPacket(Connection conn, Element packet) { // make sure to configure this component as an XDB component! /* * <xdb type="get" to="EventBroker.jabber" from="jsm-1.jabber" * ns="jsm:es_OUT" id="8"> <event> <original> <message * from="[email protected]/Exodus" id="jcl_41" * to="[email protected]" type="chat"> * <thread>34f9cff25302c09a86336c3146eea9129af9d306</thread> <body>some * food for thought</body> </message> </original> </event> </xdb> */ Jlog.debug("EventBroker received packet:\n" + DOMUtil.domToString(packet)); Element event = packet.getChild("event", packet.getNamespace()); Element original = event.getChild("original", event.getNamespace()); Element message = original.getChild("message", original.getNamespace()); XMPPUtil.swapToFrom(packet); packet.setAttribute("type", "result"); packet.removeContent(event); // clean up existing contents, we'll // replace. // just pass along, by default Element res = new Element("response", packet.getNamespace()); res.setAttribute("type", "PASS"); packet.addContent(res); Element body = message.getChild("body", message.getNamespace()); if (body != null) { String bodyText = body.getText(); if (bodyText.matches(".*foo.*")) { // modify the message if it contains /* * <xdb type="result" from="EventBroker.jabber" * to="jsm-1.jabber" ns="jsm:es_OUT" id="19"> <response * type="PASS"> <original> <message * from="[email protected] id="jcl_41" * to="[email protected]" type="chat"> * <thread>34f9cff25302c09a86336c3146eea9129af9d306</ * <body>some f**d for thought</body> </message> </original> * </response> </xdb> */ bodyText = bodyText.replaceAll("foo", "f**"); body.setText(bodyText); } } 88 // copy in the modified message. Element o = new Element("original", res.getNamespace()); o.addContent((Element)message.clone()); res.addContent(o); Administering Presence Services XCP Controller August 2010 EventBroker } conn.send(packet); /** * Called by the framework when the component by the router or some * asynchronous */ protected void _shutdown() { Jlog.debug("EventBroker._shutdown invoked"); // Nothing to do here } /** * Run the EventBroker Component. */ public static void main(String argv[]) { EventBroker comp = new EventBroker(); // The application blocks here for int retval = comp.run(argv); Jlog.debug("EventBroker exited with " + ((retval == 0) ? "SUCCESS" : "ERROR")); System.exit(retval); } } /* EventBroker class */ Protocol: Event Access from External Components The EventBroker protocol, ”Event Access from External Components,” can be used by the JSM mod_eventbroker module or by the TC EventBroker gear to talk to XCP server components, enabling those components to accomplish most of what a JSM module or a TC gear can do. Important: The protocol still contains references to ”ecr”. Related topics: Terms on page 90 Requirements on page 90 Use Cases on page 90 Response Types on page 93 XDB Protocol on page 96 Dynamic Event Registration/Unregistration on page 101 Example JSM Event Flows on page 108 Error Codes on page 109 Security Considerations on page 109 IANA Considerations on page 109 Presence Registrar Considerations on page 109 Notes on page 109 Administering Presence Services XCP Controller August 2010 89 Access Terms The following terms are used in this protocol: JSM The Presence Session Manager TC Text Conferencing Components Extensions to XCP that can connect directly to the IPS logger router. In this context, they are components that are listening for this protocol. Events Both TC and JSM are event based components, generating events for items of interest such as initial login, room creation, sending an outgoing message, and so on. PASS Event processing should continue in the originating component (TC or JSM). HANDLE Event processing should cease in the originating component (TC or JSM). fire-forget Event processing will continue in router non-blocked. The router will not expect a response from consumer. chain Event processing will block in router and a response will be expected for nonerror conditions. Requirements • Components must be able to return PASS or HANDLE for any event. • Some events have a stanza associated with them. For example, a new user registration event is associated with a stanza which may contain that user's username, email address, and so on. Components must be able to modify the stanza associated with any event, such that subsequent event handlers get the modified version. • It must be possible to have multiple different components registered for the same event, with a well-defined order of execution. • Event types should be extensible, so that, for example, the Text Conferencing component could use the same protocol to be extended externally. Use Cases These use cases all show events having associated stanzas. Not all event types will include a stanza, however. 90 Administering Presence Services XCP Controller August 2010 EventBroker Related topics: Event is passed through on page 91 Event is passed through with a modified stanza on page 91 Event is handled on page 92 Event is passed through with a modified stanza and extra stanzas on page 92 Event is passed through The component wants to PASS to the next event handler. Perhaps the component is providing access control, and has determined that this event may continue to be processed. The event type is passed along so the that consumer is not required to preserve knowledge of registrations. JSM makes a request <xdb type='get' to='component' from='jsm1.capulet.com' ns='jsm:es_OUT' id='1'> <event type='chain'> <original> <message from='[email protected]/balcony' to='[email protected]/garden' type='chat'> <body>Wherefore art thou, Romeo?</body> </message> </original> <event> </xdb> Component returns result <xdb type='result' from='component' to='jsm1.capulet.com' ns='jsm:es_OUT' id='1'> <response type='PASS'/> </xdb> Event is passed through with a modified stanza If the component wants to modify the stanza before passing it along, it includes the modified stanza in the result Component returns result with modified stanza <xdb type='result' from='component' to='jsm1.capulet.com' ns='jsm:es_OUT' id='1'> <response type='PASS'> <original> <message from='[email protected]/balcony' to='[email protected]/garden' Administering Presence Services XCP Controller August 2010 91 Access type='chat'> <body>Dude, where's my Romeo?</body> </message> </original> </response> </xdb> Event is handled If the component wants to block further processing of this event, it returns a type of HANDLE. Component returns result to block further processing of this event <xdb type='result' from='component' to='jsm1.capulet.com' ns='jsm:es_OUT' id='1'> <response type='HANDLE'/> </xdb> Considerations Handled responses should not contain a modified original element. The original element will be discarded by the JSM module. Event is passed through with a modified stanza and extra stanzas If the component wants to include more stanzas to be sent on behalf of the user associated with the event, it may send them directly through the IPS logger router. In this case, the component should inform JSM that it should not continue processing of the original stanza. Otherwise ordering issues may arise. Component takes over handling of the stanza in order to add additional messages <xdb type='result' from='component' to='jsm1.capulet.com' ns='jsm:es_OUT' id='1'> <response type='HANDLE'/> </xdb> <message xmlns='jabber:client' from='[email protected]/balcony' to='[email protected]/garden' type='chat'> <body>[WARNING] Never give out sensitive information.</body> </message> <message from='[email protected]/balcony' to='[email protected]/garden' type='chat'> <body>Wherefore art thou, Romeo?</body> </message> <message xmlns='jabber:client' from='[email protected]/balcony' to='[email protected]/garden' type='chat'> 92 Administering Presence Services XCP Controller August 2010 EventBroker <body>[WARNING] This user has not been verified.</body> </message> Considerations It should be noted that sending these new messages will generate events, thus making it possible to configure the system with infinite loops. If, for example, a component registers for the normal stanza delivery event and uses that event to inject a new stanza, it should be prepared to receive the new stanza back as part of a later normal stanza delivery event. With careful use, however, the ability to inject new stanzas into the xmpp stream is quite powerful. Response Types • PASS : continue processing • HANDLE : stop processing Event Types JSM Master event types jsm:e_SESSION after initial authentication, signals the final creation of a session. The only valid response is PASS. jsm:e_OFFLINE tanza arriving for a user who is currently offline. jsm:e_SERVER stanza addressed to the server itself. jsm:e_DELIVER called for all stanzas sent from one user to another user. jsm:e_AUTH user is authenticating. jsm:e_REGISTER called immediately prior to new user registration. jsm:e_REG_CB called immediately after successful new user registration. jsm:e_STATS called periodically to collect statistics. The only valid response is PASS. jsm:e_DISCOFEAT gather disco features from each module. jsm:e_PRISESSION called to determine the primary/default session used in delivery. Session event types jsm:es_IN for packets coming into the session jsm:es_OUT for packets originating from the session Administering Presence Services XCP Controller August 2010 93 Access jsm:es_END when a session ends Text conferencing For all of the onAfter events defined below, the only valid and acceptable response is PASS since these are simply notifications of something that has already taken place. In case of violation of this rule by the external component, the action taken by the TC external gear is left to the implementation. Any modification to original stanza requested by external component as part of the response to these events will not have any effect. Service event types tc:onServicePacket This event is fired when the system receives a packet from the router which is either addressed directly to the tc service itself (tc.foo.com) or to a room which does not currently exist in the system. tc:onBeforeRoomCreate A gear is attempting to create a room in the system. tc:onAfterRoomCreate A room has been successfully created in the system. The only valid response is PASS with no modification to original stanza. tc:onServiceDiscoInfo This method is called when an entity has sent a disco#info packet to the service itself. The only valid response is PASS. tc:onServiceReconfig The method called when the TC service receives a signal to reconfigure itself. The only valid response is PASS with no modification to original stanza. tc:onBeforeChangeUser A change has been requested of either a user role, nickname, or presence. This includes on entry, exit, nick change, availability change, or any role change (granting/revoking voice, moderator privilege) Room event types 94 tc:onDestroy The room owner has decided to close the room. The only valid response is PASS with no modification to original stanza. tc:onClose A gear makes a request to close the room. tc:onPacket A new XML stanza is received directed at a room or participant within a room. tc:onMetaInfoGet Report configuration information available. The only valid response is PASS. tc:onBeforeMetaInfoSet About to modify configuration based on options chosen by the user tc:onAfterMetaInfoSet Modified configuration based on options chosen by the user. The only valid response is PASS with nothing in it. Administering Presence Services XCP Controller August 2010 EventBroker tc:onExamineRoom A Presence entity requests information (via browse, or disco) to the room in question. The only valid response is PASS. tc:onAfterChangeUser A user has changed. The only valid response is PASS with nothing in it. tc:onBeforeChangeAffiliation User affiliation about to change. tc:onAfterChangeAffiliation User affiliation changed. The only valid response is PASS with nothing in it. tc:onBeforeRemoveAffiliation An affiliation is about to be removed tc:onAfterRemoveAffiliation An affiliation should go away. The only valid response is PASS with no modification to original stanza. tc:onBeforeJoin A user is about to join the room tc:onAfterJoin A user has joined the room. The only valid response is PASS with nothing in it. tc:onLeave A user has left the room. The only valid response is PASS with no modification to original stanza. tc:onBeforeSubject The subject is about to change tc:onAfterSubject The subject has changed. The only valid response is PASS with nothing in it. tc:onBeforeInvite A user is about to be invited tc:onAfterInvite A user has been invited. The only valid response is PASS with nothing in it. tc:onHistory History has been requested. The only valid response is PASS with no modification to original stanza. tc:onBeforeSend Message is about to be sent tc:onBeforeBroadcast Message is about to be broadcast S2S event types Support for these events may be added in a future release, but is not planned for version 4.2 of XCP. More analysis is needed to determine if these are the correct events for S2S, since S2S does not support events at this time. Service event types s2s:s_onBeforeConnect S2S is about to connect to an external domain. s2s:s_onAfterConnect S2S has connected to an external domain. s2s:s_onBeforeAccept S2S is about to allow a connection from an external domain. s2s:s_onAfterAccept S2S has allowed a connection from an external domain. Administering Presence Services XCP Controller August 2010 95 Access Connection event types s2s:c_onBeforeSend About to send a stanza out an S2S connection. s2s:c_onAfterSend Sent a stanza out an S2S connection. s2s:c_onBeforeReceive About to receive a stanza from an S2S connection. s2s:c_onAfterReceive Received a stanza from an S2S connection. XDB Protocol The xdb protocol is documented and explained in this section. First the outline is presented, followed by information specific to events. Related topics: Outline on page 96 JSM event info on page 96 TC event info on page 98 Outline The general protocol is for the xdb request to contain one element named <event/>. The event element in turn contains two optional elements named <original/> and <info/>. The original element, if present, contains the stanza that caused this event to be triggered. Note that in some cases, there is no explicit stanza associated with an event. The info element, if present, contains additional information about the event. This element should be used in cases where the stanza alone is not enough for the external component to make a decision on processing of the event. The info element provides the event context information in such cases. The info element has an xmlns attribute that uniquely identifies the schema for the element. The stanza inside the original element is the presence, iq, message or route element that triggered this event. The contents of the info element shall depend on the particular event type, and is documented in the following sub-sections. JSM event info The JSM events for which the info tag is defined are the es_END and e_PRISESSION events. es_END For this event, there is no associated original stanza so the relevant information is sent as part of info tag. The xmlns for the info tag is http://www.jabber.com/eventinfo/jsm/ session. Here is an example of an es_END event. <xdb type='get' from='jsm1.capulet.com' to='component' ns='jsm:es_END' id='1'> <event type='fire-forget'> 96 Administering Presence Services XCP Controller August 2010 EventBroker <info xmlns="http://www.jabber.com/eventinfo/jsm/session"> <session-jid>[email protected]/83F0838</session-jid> <physical-jid>[email protected]/12F1FD948</physical-jid> <logical-jid>[email protected]/balcony</logical-jid> </info> </event> </xdb> e_PRISESSION There is also no associated original stanza for the e_PRISESSION event. The relevant information must then be sent with the info tag. The associated namespace for this info tag is http://www.jabber.com/eventinfo/jsm/prisession. There is also a response necessary as this is considered a query for the suggested primary session. JSM Primary Session selection info <xdb type='get' from='jsm1.capulet.com' to='component' ns='jsm:e_PRISESSION' id='1'> <event type='chain'> <info xmlns='http://www.jabber.com/eventinfo/jsm/prisession"> <sessions type='get'> <session logical-jid='[email protected]/JM' physical-jid='[email protected]/11DEF3B21' session-jid='[email protected]/82DC0E8' priority='5'> <presence from='[email protected]/JM'> <priority>5</priority> <x from='[email protected]/JM' stamp='20061006T19:30:53' xmlns='jabber:x:delay'/> </presence> </session> <session logical-jid='[email protected]/JM2' physical-jid='[email protected]/22ABF4E01' session-jid='[email protected]/81410DF' priority='10'> <presence from='[email protected]/JM2'> <priority>10</priority> <x from='[email protected]/JM2' stamp='20061006T20:12:34' xmlns='jabber:x:delay'/> </presence> </session> </sessions> </info> </event> </xdb> Possible answers to this query can be an error condition, a selection of no session, a selection of one of the provided sessions in the info tag, or simply passing on the event with the previously described PASS response. Unless passing to use the default session, all responses must be of type HANDLE. Error condition <xdb type='result' to='jsm1.capulet.com' from='component' ns='jsm:e_PRISESSION' Administering Presence Services XCP Controller August 2010 97 Access id='1'> <response type='HANDLE'> <info xmlns='http://www.jabber.com/eventinfo/jsm/prisession"> <sessions type='error'/> </info> </response> </xdb> Note: The session tags are not required in this error response, and it is good practice to remove them, but it is not required. Selection of NULL session (offline storage) <xdb type='result' to='jsm1.capulet.com' from='component' ns='jsm:e_PRISESSION' id='1'> <response type='HANDLE'> <info xmlns='http://www.jabber.com/eventinfo/jsm/prisession"> <sessions type='result'/> </info> </response> </xdb> Selection of provided valid session <xdb type='result' to='jsm1.capulet.com' from='component' ns='jsm:e_PRISESSION' id='1'> <response type='HANDLE'> <info xmlns='http://www.jabber.com/eventinfo/jsm/prisession"> <sessions type='result'> <session logical-jid='[email protected]/JM' physical-jid='[email protected]/11DEF3B21' session-jid='[email protected]/82DC0E8' priority='5'> <presence from='[email protected]/JM'> <priority>5</priority> <x from='[email protected]/JM' stamp='20061006T19:30:53' xmlns='jabber:x:delay'/> </presence> </session> </sessions> </info> </response> </xdb> Note: It is the first child to the sessions element that will be used as the valid session. TC event info The info tag is used to convey additional context information for the following TC events. 98 Administering Presence Services XCP Controller August 2010 EventBroker TC service events For proper handling of TC service events, information about the actor (user who initiated this event) needs to be included in the xdb request. The information that needs to be sent includes the full jid of the user and whether the user is an admin for the TC service. The xmlns for the info tag is ”r;http://www.jabber.com/eventinfo/muc/service”. The syntax is shown below. TC Service Event actor info <xdb type='get' from='jsm1.capulet.com' to='component' ns='tc:onBeforeRoomCreate' id='1'> <event type='chain'> <original> .... </original> <info xmlns="http://www.jabber.com/eventinfo/muc/service"> <actor jid='[email protected]/balcony' admin='no'/> </info> </event> </xdb> TC room events For proper handling of TC room events, information about the actor (user who initiated this event) needs to be included in the xdb request. The information that needs to be sent includes the full jid of the user, the nick jid, the affiliation with the room, current role, and whether the user is an admin for the TC service. The xmlns for the info tag is ”r;http://www.jabber.com/ eventinfo/muc/room”. The syntax is given below. The room events that use a different event info namespace are defined in the following sub-sections. TC Room Event actor info <xdb type='get' from='jsm1.capulet.com' to='component' ns='tc:onBeforeJoin' id='1'> <event type='chain'> <original> .... </original> <info xmlns="http://www.jabber.com/eventinfo/muc/room"> <actor jid='[email protected]/balcony' admin='no' nick='damsel' role='member' affiliation='member'/> </info> </event> </xdb> TC room events - onBeforeChangeUser and onAfterChangeUser These events are generated when the corresponding TC protocol iq is received from the client. A single iq can contain requests for changing multiple users and an event is generated for each user. It does not make sense to send the entire iq for each event. Hence there is a need to come up with a xml structure to send the relevant information as part of the event. For the events onBeforeChangeUser and onAfterChangeUser, the information that needs to be sent is: user being changed, the TC room, new nick, new role, old nick, old role and current affiliation Administering Presence Services XCP Controller August 2010 99 Access of the user to the room. The xmlns defined for event info is ”r;http://www.jabber.com/eventinfo/ muc/room/ChangeUser”. The syntax is given below. TC Room Event ChangeUser info <xdb type='get' from='jsm1.capulet.com' to='component' ns='tc:onBeforeChangeUser' id='1'> <event type='fire-forget'> <info xmlns="http://www.jabber.com/eventinfo/muc/room/ChangeUser"> <actor jid='[email protected]/balcony' admin='no' nick='damsel' role='member' affiliation='member'/> <changeuser jid='[email protected]/garden' room='[email protected]' affiliation='member'> <old nick='macho' role='member'/> <new nick='adonis' role='moderator'/> </changeuser> </info> </event> </xdb> TC room events - onBeforeChangeAffiliation and onAfterChangeAffiliation These events are generated when the corresponding TC protocol iq is received from the client. A single iq can contain requests for changing multiple users and an event is generated for each user. It does not make sense to send the entire iq for each event. Hence there is a need to come up with a xml structure to send the relevant information as part of the event. For events onBeforeChangeAffiliation and onAfterChangeAffiliation, the information that needs to be sent is: user being changed, the TC room, old affiliation and new affiliation. The xmlns defined is ”r;http://www.jabber.com/eventinfo/muc/room/ChangeAffiliation”. The syntax is given below. TC Room Event ChangeAffiliation info <xdb type='get' from='jsm1.capulet.com' to='component' ns='tc:onBeforeChangeAffiliation' id='1'> <event type='chain'> <info xmlns="http://www.jabber.com/eventinfo/muc/room/ ChangeAffiliation"> <actor jid='[email protected]/balcony' admin='no' nick='damsel' role='member' affiliation='member'/> <changeaffiliation jid='[email protected]' room='[email protected]' oldaffiliation='member' newaffiliation='moderator'/> </info> </event> </xdb> TC room events - onBeforeRemoveAffiliation and onAfterRemoveAffiliation These events are generated when the corresponding TC protocol iq is received from the client. A single iq can contain requests for changing multiple users and an event is generated for each user. It does not make sense to send the entire iq for each event. Hence there is a need to 100 Administering Presence Services XCP Controller August 2010 EventBroker come up with a xml structure to send the relevant information as part of the event. For events onBeforeRemoveAffilation and onAfterRemoveAffiliation, the information that needs to be sent is: user jid, the TC room and the current affiliation. The xmlns for event info is ”r;http:// www.jabber.com/eventinfo/muc/room/RemoveAffiliation”. The syntax is given below. TC Room Event RemoveAffiliation info <xdb type='get' from='jsm1.capulet.com' to='component' ns='tc:onBeforeRemoveAffiliation' id='1'> <event type='fire-forget'> <info xmlns="http://www.jabber.com/eventinfo/muc/room/ RemoveAffiliation"> <actor jid='[email protected]/balcony' admin='no' nick='damsel' role='member' affiliation='member'/> <removeaffiliation jid='[email protected]' room='[email protected]' affiliation='member'/> </info> </event> </xdb> Dynamic Event Registration/Unregistration An event consumer can register for inclusion to the event chain. The registration may be one of only two types. A fire and forget registration, and a traditional insertion to the event chain. If the type is not that of ’r;chain’ or ’r;fire-forget’ a (BAD_REQUEST) will be returned. Fire and forget registration implies that the consumer will not respond to the event. Behavior in this case may be that of PASS or HANDLE. Inclusion to the event chain will suspend processing until consumer responds with a result, error, or a timeout threshold is achieved. The error behavior in this case can again be that of PASS or HANDLE. A consumer can further filter on packet type (message, presence, iq, subscription, all) and in the case of iq packet type a namespace filter can be added. If not a packet type of iq the namespace attribute will be ignored. If no packet type is included in registration then ’r;all’ is assumed. Current protocol does not support multiple register/unregister children per single iq request. Only the first child per iq will be handled and processed. Supported Events Event Name Purpose jsm:e_SESSION Register for e_SESSION event jsm:e_OFFLINE Register for e_OFFLINE event jsm:e_SERVER Register for e_SERVER event jsm:e_DELIVER Register for e_DELIVER jsm:e_AUTH Register for e_AUTH Administering Presence Services XCP Controller August 2010 101 Access Event Name 102 Purpose jsm:e_REGISTER Register for e_REGISTER jsm:e_STATS Register for e_STATS jsm:e_DISCOFEAT Register for e_DISCOFEAT jsm:es_IN Register for es_IN jsm:es_OUT Register for es_OUT jsm:es_END Register for es_END tc:onServicePacket Register for onServicePacket tc:onBeforeRoomCreate Register for onBeforeRoomCreate tc:onAfterRoomCreate Register for onAfterRoomCreate tc:onServiceDiscoInfo Register for onServiceDiscoInfo tc:onServiceReconfig Register for onServiceReconfig tc:onDestroy Register for onDestroy tc:onClose Register for onClose tc:onPacket Register for onPacket tc:onMetaInfoGet Register for onMetaInfoGet tc:onBeforeMetaInfoSet Register for onBeforeMetaInfoSet tc:onAfterMetaInfoSet Register for onAfterMetaInfoSet tc:onExamineRoom Register for onExamineRoom tc:onBeforeChangeUser Register for onBeforeChangeUser tc:onAfterChangeUser Register for onAfterChangeUser tc:onBeforeChangeAffiliation Register for onBeforeChangeAffiliation tc:onAfterChangeAffiliation Register for onAfterChangeAffiliation tc:onBeforeRemoveAffiliation Register for onBeforeRemoveAffiliation tc:onAfterRemoveAffiliation Register for onAfterRemoveAffiliation tc:onBeforeJoin Register for onBeforeJoin tc:onAfterJoin Register for onAfterJoin tc:onLeave Register for onLeave tc:onBeforeSubject Register for onBeforeSubject tc:onAfterSubject Register for onAfterSubject tc:onBeforeInvite Register for onBeforeInvite tc:onAfterInvite Register for onAfterInvite Administering Presence Services XCP Controller August 2010 EventBroker Event Name Purpose tc:onHistory Register for onHistory tc:onBeforeSend Register for onBeforeSend tc:onBeforeBroadcast Register for onBeforeBroadcast Supported packet filters Packet Type Filter Created message Filter on JPACKET_MESSAGE presence Filter on JPACKET_PRESENCE iq Filter on JPACKET_IQ subscription Filter on JPACKET_S10N all No packet filtering; default behavior is JPACKET_ALL Related topics: Server disco#info response on page 103 Registration for event on page 104 Unregistration for event on page 105 Event consumer requests registered events on page 107 Server disco#info response Server responds to disco#info request with dynamic EventBroker information Registerable events communicated with service discovery extensions (XEP-0128) <iq type='get' from='consumer.capulet.com' to='capulet.com' id='001'> <query xmlns='http://jabber.org/protocol/disco#info'/> </iq> <iq type='result' from='capulet.com' to='consumer.capulet.com' id='001'> <query xmlns='http://jabber.org/protocol/disco#info'> <feature var='http://www.jabber.com/schemas/dynamic-ecr.xsd'/> <x xmlns='jabber:x:data' type='result'> <field var='FORM_TYPE' type='hidden'> <value>http://www.jabber.com/schemas/dynamic-ecr.xsd</value> </field> <field var='http://www.jabber.com/schemas/dynamic-ecr.xsd'> <value>jsm:e_SESSION</value> <value>jsm:e_OFFLINE</value> <value>jsm:e_SERVER</value> <value>jsm:e_DELIVER</value> <value>jsm:e_AUTH</value> <value>jsm:e_REGISTER</value> <value>jsm:e_STATS</value> Administering Presence Services XCP Controller August 2010 103 Access <value>jsm:e_DISCOFEAT</value> <value>jsm:es_IN</value> <value>jsm:es_OUT</value> <value>jsm:es_END</value> </field> </x> </query> </iq> Registration for event Consumer attempts to register for e_DELIVER event Request for inclusion to event chain with an error behavior of HANDLE. <iq type='set' from='consumer.capulet.com' to='capulet.com' id='001'> <query xmlns='http://www.jabber.com/schemas/dynamic-ecr.xsd'> <register event='jsm:e_DELIVER' type='chain' behavior='HANDLE'/> </query> </iq> Consumer attempts to register for e_DELIVER event Request for fire and forget with an event behavior of PASS. <iq type='set' from='consumer.capulet.com' to='capulet.com' id='001'> <query xmlns='http://www.jabber.com/schemas/dynamic-ecr.xsd'> <register event='jsm:e_DELIVER' type='fire-forget' behavior='PASS'/> </query> </iq> Consumer attempts to register for e_OFFLINE event Request for inclusion to event chain and a JPACKET_MESSAGE filter. <iq type='set' from='consumer.capulet.com' to='capulet.com' id='001'> <query xmlns='http://www.jabber.com/schemas/dyanmic-ecr.xsd'> <register event='jsm:e_OFFLINE' type='chain' packet-type='message' behavior='HANDLE'/> </query> </iq> Registration is successful – result is returned <iq type='result' id='001' to='consumer.capulet.com' from='capulet.com'/> 104 Administering Presence Services XCP Controller August 2010 EventBroker Registration unsuccessful – already registered The consumer already registered for this event and possible filter combination. <iq type='error' to='consumer.capulet.com' from='capulet.com' id='001'> <error code='409' type='cancel'> <conflict xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/> </error> </iq> Registration unsuccessful – iq request unsupported The; iq request contained an unsupported event, unsupported behavior, unsupported type, unsupported packet-type, or some other unexpected xml. <iq type='error' to='consumer.capulet.com' from='capulet.com' id='001'> <error code='400' type='modify'> <bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/> </error> </iq> Registration unsuccessful – jid not in component list The sending jid is not contained in the component list. Presence users/admins cannot register for event consumption, request must be sent from consuming component. <iq type='error' to='consumer.capulet.com' from='capulet.com' id='001'> <error code='401' type='cancel'> <not-authorized xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/> </error> </iq> Unregistration for event An event consumer can unregister for registered events. This will remove the consumer from inclusion in the event chain. If no additional filters are given then all events for sending jid will be removed. If packet type filter of iq is used then and additional attribute of namespace can be added to further restrict search. Consumer attempts to unregister for concerned event <iq type='set' to='capulet.com' from='consumer.capulet.com' id='002'> <query xmlns='http://www.jabber.com/schemas/dynamic-ecr.xsd'> <unregister event='jsm:e_DELIVER'/> </query> </iq> Consumer attempts to unregister for event with specific filter match <iq type='set' to='capulet.com' Administering Presence Services XCP Controller August 2010 105 Access from='consumer.capulet.com' id='002'> <query xmlns='http://www.jabber.com/schemas/dynamic-ecr.xsd'> <unregister event='jsm:e_OFFLINE' packet-type='message'/> </query> </iq> Consumer attempts to unregister for event with specific filter match of packet type and namespace <iq type='set' to='capulet.com' from='consumer.capulet.com' id='002'> <query xmlns='http://www.jabber.com/schemas/dynamic-ecr.xsd'> <unregister event='jsm:e_DELIVER' packet-type='iq' namespace='jabber:iq:version'/> </query> </iq> Unregistration is successful – consumer will no longer be notified of event <iq type='result' to='consumer.capulet.com' from='capulet.com' id='002'/> Unregistration unsuccessful – consumer not registered for event The consumer has not previously registered for this event and filter combination. <iq type='error' to='consumer.capulet.com' from='capulet.com' id='002'> <error code='404' type='cancel'> <item-not-found xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/> </error> </iq> Unregistration unsuccessful – unsupported event or packet type The consumer has requested unregistration for unsupported event, unsupported packet type, or has sent some other unexpected xml. <iq type='error' to='consumer.capulet.com' from='capulet.com' id='002'> <error code='400' type='modify'> <bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/> </error> </iq> Unregistration unsuccessful – jid not in component list The sending jid is not contained in the component list. Presence users/admins cannot register for event consumption; therefore, cannot unregister for any events. <iq type='error' to='consumer.capulet.com' from='capulet.com' id='002'> 106 Administering Presence Services XCP Controller August 2010 EventBroker <error code='401' type='cancel'> <not-authorized xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/> </error> </iq> Event consumer requests registered events An event consumer can request a list of events that the entity has been successfully registered. Consumer requests list of registered events <iq type='get' to='capulet.com' from='consumer.capulet.com' id='003'> <query xmlns='http://www.jabber.com/schemas/dynamic-ecr.xsd'/> </iq> Server responds with registered list <iq type='result' to='consumer.capulet.com' from='capulet.com' id='003'> <query xmlns='http://www.jabber.com/schemas/dynamic-ecr.xsd'/> <registered event='jsm:es_END' type='fire-forget' behavior='PASS'/> <registered event='jsm:e_DELIVER' type='chain' packet-type='message' behavior='HANDLE'/> <registered event='jsm:e_SESSION' type='chain' packet-type='all' behavior='PASS'/> <registered event='jsm:e_DISCOFEAT' type='chain' packet-type='iq' behavior='PASS'/> </query> </iq> Request unsuccessful – consumer not contained in component list <iq type='error' from='capulet.com' to='consumer.capulet.com' id='003'> <error code='401' type='cancel'> <not-authorized xmlns='urn:ieft:params:xml:ns:xmpp-stanzas'/> </error> </iq> Administering Presence Services XCP Controller August 2010 107 Access Example JSM Event Flows Message sent between two local online users 1. Romeo sends a message to Juliet. 2. As the message leaves Romeo's session, it generates an es_OUT event. 3. If all handlers pass on the event, it next generates an e_DELIVER event. 4. If all handlers pass on the event, it generates an es_IN event as it enters Juliet’s session. 5. Juliet receives the message. Message sent from a local user to an offline local user 1. Romeo sends a message to Juliet, who is sleeping. 2. As the message leaves Romeo’s session, it generates an es_OUT event. 3. If all handlers pass on the event, it next generates an e_DELIVER event. 4. If all handlers pass on the event, after detecting that Juliet is offline, it generates an e_OFFLINE event. 5. If all previous handlers pass on the event, mod_offline, registered for e_OFFLINE, stores the message for later retrieval. Message sent from remote user to a local user 1. Romeo sends a message to Juliet from afar. 2. If S2S events are implemented, a s2s:c_onBeforeReceive event is fired. 3. If S2S events are implemented, a s2s:c_onAfterReceive event is fired. 4. Since Romeo’s session is managed on a foreign server, no es_OUT event is fired in JSM. 5. The first event generated in JSM is an e_DELIVER event. 6. If all handlers pass on the event, it generates an es_IN event as it enters Juliet’s session. 7. Juliet receives the message. User requests roster 1. Romeo sends a roster retrieval request. 2. As the request leaves Romeo’s session, it generates an es_OUT event. 3. mod_roster, registered for es_OUT, retrieves user’s roster and sends it to Romeo. 4. As the result enters Romeo’s session, it generates an es_IN event. 5. Romeo receives his roster. 108 Administering Presence Services XCP Controller August 2010 EventBroker Error Codes Error code 409 (conflict) is used on registration failure when consumer registers for an event that is already registered under its name. Error code 400 (bad request) is used to signify bad protocol and/or bad values for an unsuccessful registration attempt. Error code 401 (not authorized) is used to signify requesting agent is not recognized as a component by the system. Error code 404 (item not found) is used for unsuccessful unregistration when the requested event has not been previously registered. Security Considerations Non-trusted sources cannot send XDB requests or responses. IANA Considerations No interaction with the Internet Assigned Numbers Authority (IANA) [1] is required. Presence Registrar Considerations No interaction with Presence Registrar [2] is required. Notes Internet Assigned Numbers Authority (IANA) The IANA is the central coordinator for the assignment of unique parameter values for Internet protocols. For further information, see http://www.iana.org. Reserved Presence namespaces The Presence Registrar maintains a list of reserved Presence namespaces as well as a registry of parameters used in the context of XEPs approved by the JSF. For further information, see http://www.xmpp.org/registrar. Administering Presence Services XCP Controller August 2010 109 Access Category Configuration An InfoBroker category is a high-level data organizer that contains nodes of information to which users can publish and subscribe. Configuring a Category Perform the configuration described in this section first. Then, if you want to fine-tune your configuration, configure the parameters described in Advanced Configuration parameters . 1. Change to the Controller's Intermediate configuration view. 2. Configure the following parameters: Node prefix for this category Enter the name of the category. InfoBroker driver Leave this field blank unless you are using a custom driver. Load function The load function loads the driver. Select a function from the drop-down list. ps_memdriver stores published items in memory; ps_databasedriver writes published items to a database. Note: When you select ps_databasedriver , nodes contained in the category are not deleted from the database when you delete the category through the Controller. Deliver published items with notification? Select Yes if you want details to accompany the notification that something has been published. If you select No , only the notification is sent to users. Notify subscribers when items are deleted? Select Yes to notify subscribers when items in the category are deleted. Allow anyone to Select Yes to allow any user to subscribe to nodes in this subscribe to nodes in category. If you select No , only InfoBroker administrators this category? can subscribe to nodes in the category. Allow anyone to create nodes in this category? 110 Select Yes to allow any user to create nodes in this category. If you select No , only InfoBroker administrators can create nodes in the category. Administering Presence Services XCP Controller August 2010 Category Configuration 3. Select the Database Setup option if you want to configure a database that is different than the one configured for the Core Router in the Global Settings Configuration screen. Database Setup Parameters Datasource Name For the PostgreSQL database, this is the name of the component's datasource as specified in the .odbc.ini file. For Oracle, the datasource is specified in the ORACLE_SID environment variable or in the tsnames.ora file. For DB2, this is typically the database alias. Database User Name Enter the username used to connect to the database. Database User's Password Enter the password used to connect to the database. Confirm Password Enter the password again to confirm it. Database Type Select the type of database you are using from the pulldown list. Important: If you select postgresql-odbc, you must add the line, "MaxVarcharSize=4000" to the datasource definition used by the Message Archiver in the .odbc.ini file. Number of connections tothe database Enter the number of connections that you want the component to use for processing requests. Time in seconds between database connection heartbeats Enter the number of seconds after which the database connection should refresh. Do not set this value to 0 without contacting technical support. 4. Click Submit to save your configuration. You are returned to the InfoBroker Configuration screen. Advanced Configuration Parameters The parameters described in this section display in the Controller's Advanced configuration view. They allow you to configure more advanced category features. Category Only send notifications to subscribers who are online? Select Yes to if you do not want users who are offline to receive notifications of new or changed information in this Administering Presence Services XCP Controller August 2010 111 Access category. Selecting Yes makes the category presenceenabled. If you select No , notifications are sent to everyone who is subscribed to nodes in this category regardless of whether they are online. Presence IDs for Proxy Entities Presence ID(s) Enter one or more Presence IDs of the users whom you want to administer this particular category. Node Configuration Maximum items for each node Enter the maximum number of items that can be contained in each node in the category. Maximum subscriptions for each node Enter the maximum number of subscriptions that can occur for each node in the category. Maximum affiliations for each node Enter the maximum number of users who can be affiliated with the node. Affiliations include Owner, Publisher, None, and Outcast. Database Setup Is database debug logging enabled? Select 1 to log database debug information. InfoBroker Important: To get the InfoBroker component up and running, follow the instructions in Configuring the InfoBroker. Then, if you want to fine tune your configuration, you can configure the parameters in the Controller's Advanced configuration view. The InfoBroker is an enabling technology, which means that you must write an application that uses its functionality. (See the InfoBroker chapter in the XCP Server Developer Guide for more information.) The InfoBroker allows you to organize different types of information into categories that are accessible by users of your application. Users can create, publish to, and subscribe to nodes within categories. With XCP 5.2, the InfoBroker also supports the use of extended stanza addressing, which enables XMPP stanzas to specify multiple recipients or sub-addresses. (See XEP-0060 and XEP-0033 for more information about the InfoBroker, which is also known as "Publish Subscribe" and its ability to use extended stanza addressing.) 112 Administering Presence Services XCP Controller August 2010 InfoBroker Note: To install the InfoBroker package, you must first purchase a license. Configuring the InfoBroker Perform the configuration described in this section first. This section provides instructions for getting the InfoBroker component up and running quickly by configuring the parameters provided in the Controller's Intermediate configuration view. The parameters provided in the Intermediate view are sufficient to configure an operational InfoBroker component. 1. Change to the Controller's Intermediate configuration view. 2. Select the Router Outbound Connection Information option only if you want to configure parameters that allow the router to connect to the component. For example, if the component is installed on a system that is running outside your firewall, this option allows the XCP router to connect to the component safely rather than introducing security risks by having the component connect to the router. (If you do not configure this option, the component will connect to the router using the Master Accept Port that is configured for the Core Router.) Router Outbound Connection Parameters Component IP Enter the IP address or hostname of the system on which the component is installed. Port Enter the port that the component uses for communications. Password Enter the password that the router uses to authenticate the component. A default is provided if the command configuration is used. You can change this value as needed. 3. The Execute an External Command option is enabled by default and allows the component to be started automatically by the router. If you prefer to start the component from a command line, disable this option. Command line to run A command that runs the component automatically is provided by default. You can modify it if needed. Caution: Do not use the -B argument with this component. Since the IPS logger is already a daemon process, its children must not be daemons. Administering Presence Services XCP Controller August 2010 113 Access You should not redirect output, because all output to STDOUT and STDERR will be redirected to /dev/null. 4. Under Hostnames for this Component, specify a Host Filter only if you want the component to be externally addressable For example, if you want clients and other components or programs to communicate with it. This is because the mod_disco module in JSM uses host filters to return the component as something that should be discoverable. Host Filters By default, the XCP server's hostname prepended by "info-broker" is provided in the textbox. Enter the hostnames or IP addresses for which you want this component to handle packets. Separate each hostname or address with a line break. By default, this field contains the hostname of the system on which the XCP server is installed prepended by "info-broker"; for example: info-broker.example.com Enter an asterisk (*) in the textbox to enable the component to handle data from any host. Caution: If you configure SDNS to run in front of this component, leave this field blank. Because the hostname for which this component handles packets must be specified in the SDNS component's configuration, if you add the hostname in this configuration as well, the same packets are sent to the host twice. Note: Host filters must be hostnames, or IPv4 or IPv6 addresses. If an IP address is used, the packet address must also use this IP address. 5. ForInfoBroker Administrators, type the IDs of users who can administer categories and nodes; for example, [email protected]. Separate each ID with a line break. InfoBroker administrators can create, configure, and delete categories and nodes by sending appropriate protocol stanzas to the InfoBroker component. 6. For Default category , enter the node prefix of the category that acts as the default when a user adds a node without specifying a particular category. An InfoBroker category is a name that is used as a prefix for organizing nodes of information. You can create multiple categories, each of which can contain many nodes. You can also specify whether or not users can create and publish to nodes within each particular category. You should always have at least one category. 7. To add a new category, click the Go button to access the Category Configuration screen. 114 Administering Presence Services XCP Controller August 2010 InfoBroker Note: Nodes contained in the category are not deleted from the database when you delete the category through the Controller. 8. If you want to configure logging for the component, see Component Logging (Jlog) for parameter descriptions. 9. If you want to enable SNMP , click the checkbox next to the SNMP Configuration option. 10. When you have finished, click Submit to save your configuration. 11. Restart your system. Advanced Configuration Parameters Configuration parameters that are provided in the Controller's Advanced configuration view are described below in their respective sections. These parameters let you configure advanced settings such as runlevel, buffer sizes, thread counts, and custom loggers. They require a more advanced level of XCP server knowledge and can be used for fine tuning your XCP system on a granular level. Default values have been provided for required Advanced parameters. Runlevel The order in which this component shuts down. The runlevel must be an integer value greater than or equal to 0. (Component shutdown is executed in reverse order of the specified runlevel; components with the highest level (typically 70) shut down first.) Caution: Do not change the runlevel unless you know exactly what you are doing and understand the effects that changing it will have. The default runlevel is provided to help the system shut down as smoothly as possible, and is based on this component's dependencies upon other components. Timeout for Shutdown The number of seconds that the server waits to receive acknowledgement from the component that the shutdown process has completed. Note: If the component has not shut down by the time this time period has elapsed, the XCP core router leaves the process in its current state and continues shutting down other processes. Component Properties Select the Component Properties option if you want to configure the number of packets that are buffered when the component is down and whether to send error packets to stderr. Administering Presence Services XCP Controller August 2010 115 Access Number of packets buffered Enter the number of packets bound for the component that when component is down should be buffered if the component goes down. Bounce error packets to stderr Select Yes if you want the router to send warnings to stderr when the component is down. Router Outbound Connection Information Buffer size in bytes for outgoing data Enter the number of bytes the router should buffer when it sends information to the component. You may want to modify this element when working on performance enhancements. Buffer size in bytes for incoming data Enter the number of bytes the router should buffer when it receives information from the component. You may want to modify this element when working on performance enhancements. Keep-alive interval in seconds Enter the number of seconds after which the router sends a keep-alive to the component. The keep-alive helps prevent firewalls from dropping an unused connection to the component. If this option is set to 0 or left empty, keep-alives are disabled. Log delivery of packets to this component Select Yes if you want the data that the router delivers to the component to be logged. The information is logged to the logger(s) you set up during IPS Logger configuration (syslog, file, or stderr). Socket-level logging happens only at the debug level. Execute an External Command Maximum interval in seconds to wait before restarting component Enter the maximum number of seconds after which the router tries to restart the component. If the component goes down, the router tries to restart it after 1 second. If the component is not running yet, the router multiplies the wait time by 1.5, and retires after the longer time. Once the maximum time interval that you specify in this field is reached, the router continues to retry after waiting this amount of time. Maximum number of times to restart component Enter the total number of restarts allowed. The default setting, -1, means unlimited. Note: If you want to be able to kill the component from the command line and prevent it from starting again automatically, you must set this number to something other than -1. For example, if you set it to 1, the component will not restart once you have killed it; if you set it to 2, the component will only restart once, and so on. 116 Administering Presence Services XCP Controller August 2010 InfoBroker Interval in seconds at which The number of seconds that the component has been up and to reset this value to 1 running, after which to set the restart time back to 1 second. second Path to Binary The directory path to the shell that launches the component. You can change the default setting if needed. InfoBroker Configuration Number of threads to Enter the number of threads that you want to have processing dedicate to InfoBroker tasks tasks in the component. Increasing this value enables InfoBroker to handle more tasks at a time. However, it spends more time scheduling the tasks as this number goes up. We recommend that you set this number to one more than the number of processors on your system. Number of managed queues to dedicate to InfoBroker tasks Enter the number of queues that you want the InfoBroker component to use. This number reflects the concurrent number of anticipated InfoBroker nodes divided by 20. Enable stanza optimization support Click the checkbox to enable stanza optimization support for the component. Number of publish recipients to trigger an extended address stanza Enter the number of recipients required to cause an extended address stanza to be used rather than individual packets. Multiple optimizer address threshold Important: This option is to be used mainly for fine-tuning your system. The default value that is supplied should be sufficient in most cases. Enter the number of recipients per found stanza optimizer to warrant separating a single packet into many. Take the following scenario, for example: • Three stanza optimizers are found for domain.example.com. • This stanza optimizer receives a packet with 400 recipients to domain.example.com. • The optimizer address threshold is set to 100. In this case, each stanza optimizer would handle approximately 133 recipients, warranting three extended stanza packets rather than one. Using the same scenario but with only 200 recipients, each optimizer would then handle approximately 66 recipients each. This situation does not warrant splitting the packet. Therefore, only one packet will be sent to one optimizer for local delivery. Administering Presence Services XCP Controller August 2010 117 Access Probe presence for all subscribers at startup? Select Yes if, upon component startup, you want the system to query the presence status of all entities that are subscribed to nodes under presence-enabled categories. Also, select Yes if you are starting the component or system after an extended period of downtime, in order to refresh the presence information. Add a new custom logger Click the Go button to access the Custom Logger Configuration screen, in which you can specify the library and library entry point function for a custom logger. SNMP Configuration Count errors Select Yes only if you want to enable SNMP error counting. This option takes a great deal of server resource; use it with caution. InfoBroker The InfoBroker is an enabling technology, which means that you must write an application that uses its functionality. The InfoBroker allows you to organize different types of information into categories that are accessible by users of your application. Users can create, publish to, and subscribe to nodes within categories. Some of the ways you can implement the InfoBroker include: • Broadcasting messages to text conferencing rooms • Notifying users of certain events • Pushing news content • Enabling extended presence attributes that are popular in wireless communication (for example, storing user location data) The InfoBroker is XEP-60 compliant.. The InfoBroker also supports the use of extended stanza addressing, which enables XMPP stanzas to specify multiple recipients or subaddresses. See XEP-0033: Extended Stanza Addressing for more information about the InfoBroker and its ability to use extended stanza addressing. Related topics: Planning Your Deployment on page 119 InfoBroker Configuration on page 119 Creating and Publishing to Nodes on page 122 118 Administering Presence Services XCP Controller August 2010 InfoBroker Data Drivers on page 123 XEP-60 Compliance on page 124 Example Implementations on page 126 InfoBroker Parameter Reference on page 128 Category Parameter Reference on page 132 Planning Your Deployment If you have a small deployment, you can configure the InfoBroker service as a single component. However, if your deployment is larger, you should add multiple InfoBroker components using the Single Domain Name Support functionality to spread the load over multiple machines as shown in Figure 21 . You can redirect InfoBroker stanzas based on the node identifier. This means that any given InfoBroker instance handles a subset of the total number of InfoBroker nodes in the system. How large a subset it handles is determined by how many nodes are in the system and how many InfoBroker instances are available to share the load. InfoBroker Configuration This section provides instructions for configuring the InfoBroker component and categories using the parameters provided in the controller’s Intermediate configuration view. These parameters are sufficient to configure an operational InfoBroker. Related topics: Configuring the InfoBroker Component on page 119 Configuring Categories on page 120 To configure a category on page 121 Configuring the InfoBroker Component The following instructions describe only the intermediate parameters that are specific to the InfoBroker component. For descriptions of all of the parameters associated with the component, see InfoBroker Parameter Reference . Related topics: To configure the InfoBroker component on page 120 Administering Presence Services XCP Controller August 2010 119 Access To configure the InfoBroker component 1. Change to the controller’s Intermediate configuration view. 2. In the Components area on the controller’s main page, select InfoBroker in the list, and then click Go . 3. In the InfoBroker Configuration page, scroll down to the InfoBroker Configuration area. 4. Configure the parameters as follows. Parameter Description InfoBroker Administrators Enter the JIDs of users who can administer categories and nodes; for example, [email protected]. Separate each ID with a line break. Default category An InfoBroker category is a name that is used as a prefix for organizing nodes of information. Enter the node prefix of the category that acts as the default when a user adds a node without specifying a particular category. You can create multiple categories, each of which can contain many nodes. You should always have at least one category. 5. Click Go beside Add a new Category to configure a category. Instructions for configuring categories are provided in the next section. 6. When you have finished configuring the component and one or more categories, click Submit to save your configuration. Configuring Categories A category is a prefix on the name of an InfoBroker node and is used conceptually to organize the flat (non-hierarchical) nature of nodes. All nodes in a single category have the same configuration. The InfoBroker places a hierarchy on node identifiers as defined in XEP-60 . The following instructions describe only the intermediate parameters that are specific to InfoBroker categories. For descriptions of the advanced parameters associated with categories, see Category Parameter Reference . 120 Administering Presence Services XCP Controller August 2010 InfoBroker To configure a category 1. On the InfoBroker Configuration page, click Go beside Add a New Category . The Category Configuration page is displayed. 2. Configure the first seven parameters as follows. Parameter Description Node prefix for this category Enter a name for the category. InfoBroker Driver Leave this box blank unless you are using a custom driver. Load function The load function loads the driver. Select a function in the list. The ps_memdriver function stores published items in memory; The ps_databasedriver function writes published items to a database. When you select the ps_databasedriver function, nodes contained in the category are not deleted from the database when you delete the category through the controller. Deliver published items Select Yes if you want details to accompany the with notification? notification that something has been published. If you select No, only the notification is sent to users. Notify subscribers when items are deleted? Select Yes to notify subscribers when items in the category are deleted. Allow anyone to subscribe to nodes in this category? Select Yes to allow any user to subscribe to nodes in this category. If you select No, only InfoBroker administrators can subscribe to nodes in the category. Allow anyone to create Select Yes to allow any user to create nodes in this nodes in this category? category. If you select No, only InfoBroker administrators can create nodes in the category. 3. The InfoBroker requires a database—Oracle, PostgreSQL, or DB2. If you configured one of these database when you installed the XCP server, you do not have to configure one here. However, if you want to use a different database for the InfoBroker, or if you selected SQLite during installation, select the Database Setup option and configure the parameters. The database parameters are described as follows. Administering Presence Services XCP Controller August 2010 121 Access Parameter Description Datasource Name For the PostgreSQL database, this is the name of the component’s datasource as specified in the .odbc.ini file. For Oracle, the datasource is specified in the ORACLE_SID environment variable or in the tsnames.ora file. For DB2, this is typically the database alias. Database User Name Enter the username used to connect to the database. Database User’s Password Enter the password used to connect to the database. Confirm Password Enter the password again to confirm it. Database Type Select the type of database you are using from the list. Note: If you select postgresql-odbc, you must add the line, MaxVarcharSize=4000 to the datasource definition used in the .odbc.ini file. Number of connections to the database Enter the number of connections that you want the component to use for processing requests. Time in seconds Enter the number of seconds after which the database between database connection should refresh. Do not set this value to zero connection heartbeats without contacting technical support. 4. Click Submit to save your configuration. Creating and Publishing to Nodes A node is a virtual location to which information can be published and from which event notifications and/or payloads can be received. An application that is created to use the InfoBroker feature should allow its users to create nodes and to publish to nodes on the XCP server. Three methods are available for doing this: • XMPP sent from a client • XMPP sent from a custom component • A request sent through a Web Services application The XMPP that must be sent from a client or a custom component to the XCP server to create or publish to a node is explained in detail in XEP-60 . InfoBroker is one of three XCP services that have been made available through a Web Services component and API. You can develop a Web Services application that allows users to create 122 Administering Presence Services XCP Controller August 2010 InfoBroker and publish to nodes on the XCP server. (See the Web Services API Development Guide for more information.) Data Drivers The InfoBroker component has a driver interface for the storage of data. As requests come in, the InfoBroker controller hands them off to the correct driver based upon the category to which the information is being published. This enables published information to be placed in a data store that is appropriate for that type of information. Transient data may be stored in memory whereas persistent data may be stored in a relational database. There are two generic drivers —one for memory storage and one for database storage. RDBMS Driver An RDBMS data driver provides the ability to store the XML payload of a publish request as a large object (LOB) only. No attempt is made to parse out the contents of the payload or to map the contents into a customer’s existing schema. The RDBMS driver is written using DBI libraries, and can use Oracle or PostgreSQL databases. Memory Drivers The memory driver stores information in physical RAM. All data is lost when the InfoBroker component is shut down. This driver provides a high-speed alternative to the RDBMS driver when using the InfoBroker service for notification only or for when the data integrity provided by the RDBMS driver is not essential. Custom Drivers You may provide your own drivers that take advantage of knowledge of the format of the item being published to a particular category. For example, you may provide your own RDBMS driver for geolocation information that breaks the fields apart into longitude, latitude, and altitude. Doing so may provide another service the ability to search based on published information. Subscription Storage An RDBMS subscription driver will provide the ability to store subscriptions to a specific schema. No in-memory driver is provided. Limitations Given that a great deal of state information is stored in InfoBroker, attention has been given to speed and reliability first, with simplicity in design and implementation a secondary design goal. A survey of popular InfoBroker systems (Sienna, Gryphon, Elvin, and JMS) reveals that all such systems have subtle race conditions. For example, in a distributed environment, both Elvin and the JMS InfoBroker interface do not guarantee that transient subscriptions will receive information published immediately following the initial subscription request. These types of race conditions are an accepted market standard, and also exist in the the Presence implementation. Administering Presence Services XCP Controller August 2010 123 Access XEP-60 Compliance This section describes how the of the InfoBroker component deviates from the protocol and specifications laid out in XEP-60 . XEP-60 defines the XMPP Standards Foundation protocol for generic InfoBroker systems. The current implementation includes all must implement features defined in the XEP. Several should and may implement features have not yet been implemented. The sections in the Presence implementation differs from the XEP match the following headings. Related topics: Requirements on page 124 Affiliations on page 124 Subscription States on page 124 Entity Use Cases on page 125 Owner Use Cases on page 125 Implementation Notes on page 125 Requirements Presence implementation does not support the following: • Direct Node Addressing – This is defined as a may implement part of the specification. • Dynamic Node Configuration – This is defined as a may implement part of the specification. • Configurable options for each subscriber – This is defined as a may implement part of the specification. Affiliations Presence implementation does not support the affiliation of “ outcast.” This is not defined as a must implement part of the specification. All other affiliations are supported. Subscription States Presence implementation allows the following subscription states: • Subscribed: The entity will receive event notifications (and possibly payloads) when a new item is published to the node. • Pending: The entity is allowed to subscribe. During category configuration (see “ Configuring Categories” on page 42 ), you can allow anyone to subscribes to nodes 124 Administering Presence Services XCP Controller August 2010 InfoBroker within the category. This is how Presence has implemented “ white-list” node functionality. Presence implementation does not implement any subscription approval process. • Unsubscribed: The entity is not receiving event notifications. Entity Use Cases The following Entity Use Cases are optional and are not currently implemented: • Approving and Denying Subscription Requests • Configure Subscription Options • Discover Nodes • Discover Items for a Node Create a new node Presence implementation currently does not support “ instant nodes,” where an entity requests a new node without providing a node identifier. This is a may implement feature. Presence implementation currently does not support sending an initial item to publish with the node creation request. This is a should implement feature. Subscribe Presence implementation does not deliver any items when a user subscribes to a node. They must perform the “ Get Items” use case to fetch the current items. This is a may implement feature. Delete items Presence implementation does not allow nodes to be configured to send notification messages when items are deleted. This is a may implement feature. Owner Use Cases The following use case is optional and not currently implemented: Configure a Node Implementation Notes Categories Presence implementation places a hierarchy on node identifiers. The system allows the administrator to configure multiple categories. All nodes in a single category have the same configuration. Administering Presence Services XCP Controller August 2010 125 Access Disco support The InfoBroker component responds to disco#info and disco#item requests. The response to disco#items is a list of the configured categories. Each category responds to a disco#info request with the configured features. Meta-nodes Presence implementation does not support Meta-Nodes. This is a should implement feature. Example Implementations This section describes some ways in which you can implement the InfoBroker functionality Related topics: Protocols for Extended Presence on page 126 Creating a Node Hierarchy for Extended Presence on page 126 Protocols for Extended Presence The following lists current work in the XMPP Standards Foundation to define acceptable protocols for some extended presence attributes using the InfoBroker protocol. • XEP-080 – User Geolocation • XEP-084 – User Avatar • XEP-107 – User Mood • XEP-108 – User Activity • XEP-118 – User Tune Note: The protocols outlined in these XEPs have not been standardized. However, the XEPs describe possible ways in which you can implement these protocols using the InfoBroker technology. Creating a Node Hierarchy for Extended Presence This section describes a possible implementation of extended presence functionality using InfoBroker. It is intended as an example of how to structure categories in InfoBroker for handling a particular application. 126 Administering Presence Services XCP Controller August 2010 InfoBroker Problem statement Create a hierarchy of InfoBroker categories that: • Provides extended presence attributes for network connectivity, geolocation, and mood • Provides different access controls for different attributes Network connectivity may be globally accessible whereas geolocation is available only to allowed subscribers. Permits discovery of supported attributes for a given user of the system For example, a user may access more features of the system through a PC-based client than through a cell-phone client. It must be possible to discover which features that client supports. Categories The configuration for each attribute is likely to be the same among users of that particular feature; therefore, the categories are created hierarchically based first on the extended presence attribute and then on the particular MSISDN using that feature. The following node identifiers illustrate how you may structure the information for Users A and B: /Wireless/Network/UserA/Wireless/Network/UserB/Wireless/Geoloc/UserA/Wireless/Geoloc/ UserB/Wireless/Mood/UserA/Wireless/Mood/UserB Network presence is made available to anyone, stores only the last published item so that it can be queried to retrieve the last availability information, allows publishing only by the network service, and allows only administrators to create new nodes. Geolocation is available only to subscribers, and stores the last two items (the user’s current and previous location). Mood is not considered an essential function, so this category stores only the last item in memory rather than storing it in a database. In addition to these three categories, a meta-category is created to permit searching for supported features. Read access is granted to everyone for this category: /UserData/UserA/UserData/UserB Process flow The process flow is provided as follows: 1. UserA has been using the mood service for awhile. When the user was added to the system, items were published to the UserData node to indicate which services he or she is using. UserA has the following nodes: /Wireless/Mood/UserA (happy)/Wireless/Network/UserA (online)/UserData/UserA (/Wireless/Mood) (/Wireless/Network) 2. UserA decides to activate the geolocation service. 3. The geolocation service creates the following node: /Wireless/Geoloc/UserA 4. The geolocation service also publishes to the UserData node to reflect that UserA is using an additional service: Administering Presence Services XCP Controller August 2010 127 Access /UserData/UserA (Wireless/Mood) (Wireless/Network) (Wireless/Geoloc) 5. The geolocation service publishes to the Geoloc node: /Wireless/Geoloc/UserA (denver) Anyone who wants to discover what nodes are available for UserA may simply send an InfoBroker ’get’ request to UserData/UserA. InfoBroker Parameter Reference This section describes the parameters associated with the InfoBroker component. The parameters are divided into subsections based on the configuration view in which they display. Related topics: Intermediate Parameters on page 128 Advanced Parameters on page 130 Intermediate Parameters The following table describes the parameters that are displayed in the controller’s Intermediate configuration view. These parameters are sufficient to configure an operational InfoBroker component. Parameter Description Description The description is displayed in the Components area on the controller’s main page and should help you distinguish between components of the same type when you have more than one configured. You can change the description as needed. Router Outbound Connection Information Select this option only if you want the XCP router to connect to the component. For example, if the component is running outside your firewall, this option allows the router to connect to the component safely rather than introducing security risks by letting the component connect to it. By default, components connect to the router using the router’s Master Accept Port. Component IP Enter the IP address or host name of the system on which the component is installed. Port Enter the port that the component uses for communications. Password Enter the password that the router uses to authenticate the component. Execute an External Command This option allows the router to start the component automatically. If you prefer to start the component from a command line, disable this option. 128 Administering Presence Services XCP Controller August 2010 InfoBroker Parameter Command line to run Description A command that runs the component automatically is provided by default. You can modify it if needed. Note: Do not use the -B argument with this component. Since IPS logger is already a daemon process, its children must not be daemons. You should not redirect output, because all output to STDOUT and STDERR will be redirected to /dev/null. Hostnames for this Component This option specifies the hosts for which this component will handle packets. Specify a host filter only if you want the component to be externally addressable; for example, if you want clients and other components or programs to communicate with it. This is because the mod_disco module in JSM uses host filters to return the component as something that should be discoverable. Host Filters By default, the XCP server’s host name prepended by “ info-broker” is provided in the textbox. Enter the host names or IP addresses for which you want this component to handle packets. Separate each host name or address with a line break. Host filters must be host names, or IPv4 or IPv6 addresses. If you use an IP address, the packet address must also use this IP address. Note: If you configure SDNS to run in front of this component, leave this field blank. Because the host name for which this component handles packets must be specified in the SDNS component’s configuration, if you add the host name in this configuration as well, the same packets are sent to the host twice. InfoBroker Configuration InfoBroker Administrators InfoBroker administrators can create, configure, and delete categories and nodes by sending appropriate protocol stanzas to the InfoBroker component. Enter the JIDs of users who can administer categories and nodes; for example, [email protected]. Separate each ID with a line break. InfoBroker Categories Default category An InfoBroker category is a name that is used as a prefix for organizing nodes of information. Enter the node prefix of the category that acts as the default when a user adds a node without specifying a particular category. You can create multiple categories, each of which can contain many nodes. You should always have at least one category. Component Logging (Jlog) Select the Component Logging (Jlog) option only if you want to configure filtered level loggers that log messages to syslog and to a stream (stderr or stdout). You can enable either or both the syslog and stream loggers. These parameters are displayed in the controller’s Intermediate and Advanced configuration views. Administering Presence Services XCP Controller August 2010 129 Access Parameter Description For descriptions of Component Logging parameters, see “ Component Logging (Jlog)” on page 407. SNMP Configuration Select this option if you want to configure SNMP for the component. Enable SNMP Leave this parameter set to Yes. Advanced Parameters The following table describes the parameters that are displayed in the controller’s Advanced configuration view. Advanced parameters are used for adjusting the performance of the XCP system. We recommend that you call technical Support if you need to change these parameter settings. Parameter Description Runlevel Enter the order in which this component shuts down. The runlevel must be an integer value greater than or equal to zero. Component shutdown is executed in reverse order of the specified runlevel; components with the highest level (typically 70) shut down first. Do not change the runlevel unless you know exactly what you are doing and understand the effects that changing it will have. The default runlevel is provided to help the system shut down as smoothly as possible, and is based on this component’s dependencies upon other components. Timeout for shutdown Enter the number of seconds that the server waits to receive acknowledgement from the component that the shutdown process has completed. If the component has not shut down by the time this time period has elapsed, the router leaves the process in its current state and continues shutting down other processes. Component Properties Number of Enter the number of packets bound for the component that should be packets buffered buffered if the component goes down. when component is down Bounce error packets to stderr Select Yes if you want the router to send warnings to stderr when the component is down. Router Outbound Connection Information Buffer size in Enter the number of bytes the router should buffer when it sends bytes for outgoing information to the component. You may want to modify this element data when working on performance enhancements. 130 Administering Presence Services XCP Controller August 2010 InfoBroker Parameter Description Buffer size in bytes for incoming data Enter the number of bytes the router should buffer when it receives information from the component. You may want to modify this element when working on performance enhancements. Send keepalives Select Yes if you want the router to send keep-alives to the component. The keep-alive helps prevent firewalls from dropping an unused connection to the component. If this option is set to No, keep-alives are disabled. Log the delivery of packets to this component Select Yes if you want to log the data that the router delivers to the component. The information is logged to the logger(s) you set up during IPS Logger configuration (syslog, file, or stderr). Socket-level logging happens only at the debug level. Execute an External Command Maximum interval in seconds to wait before restarting component Enter the maximum number of seconds after which the router tries to restart the component. If the component goes down, the router tries to restart it after one second. If the component does not start, the router multiplies the wait time by 1.5, and tries again. Once the maximum time interval that you specify for this parameter is reached, the router continues to retry after waiting this amount of time. Maximum number of times to restart component Enter the total number of restarts allowed. The default setting, -1, means unlimited. Interval in Enter the number of seconds that the component has been up and seconds at which running, after which to set the restart time back to one second. to reset this value to 1 second Path to binary Enter the directory path to the shell that launches the component. You can change the default setting if needed. InfoBroker Configuration Number of threads to dedicate to InfoBroker tasks Enter the number of threads that you want to have processing tasks in the component. Increasing this value enables the component to handle more tasks at a time. However, it spends more time scheduling the tasks as this number increases. We recommend that you set this number to one more than the number of processors on your system. Number of Enter the number of queues that you want this component to use. This managed queues number reflects the concurrent number of anticipated InfoBroker nodes to dedicate to divided by 20. InfoBroker tasks Enable stanza Select this option to enable stanza optimization support for the optimization component. support (XEP-33) Administering Presence Services XCP Controller August 2010 131 Access Parameter Description Number of Enter the number of recipients required to cause an extended address publish recipients stanza to be used rather than individual packets. to trigger an extended address stanza Multiple optimizer address threshold Note: This option is to be used mainly for fine-tuning your system. The default value that is supplied should be sufficient in most cases. Enter the number of recipients per found stanza optimizer to warrant separating a single packet into many. Take the following scenario, for example: In this case, each stanza optimizer would handle approximately 133 recipients, warranting three extended stanza packets rather than one. Using the same scenario but with only 200 recipients, each optimizer would then handle approximately 66 recipients each. This situation does not warrant splitting the packet. Therefore, only one packet will be sent to one optimizer for local delivery. Probe presence Select Yes if, upon component startup, you want the system to query for all subscribers the presence status of all entities that are subscribed to nodes under at startup? presence-enabled categories. Also, select Yes if you are starting the component or system after an extended period of downtime in order to refresh the presence information. Component Logging (Jlog) Add a new custom logger If you have created a custom logger for logging component information using the libjcore library, click Go to access the Custom Logger Configuration page. SNMP Configuration Count errors Select Yes only if you want to enable SNMP error counting. This option takes a great deal of server resource, so use it with caution. Category Parameter Reference This section describes the parameters associated with InfoBroker categories. The parameters are divided into subsections based on the configuration view in which they display. Related topics: Intermediate Parameters on page 133 Advanced Parameters on page 134 132 Administering Presence Services XCP Controller August 2010 InfoBroker Intermediate Parameters The following table describes the parameters that are displayed in the controller’s Intermediate configuration view. Parameter Description Node prefix for this category Enter a name for the category. InfoBroker driver Leave this box blank unless you are using a custom driver. Load function The load function loads the driver. Select a function in the list. The ps_memdriver function stores published items in memory; The ps_databasedriver function writes published items to a database. When you select the ps_databasedriver function, nodes contained in the category are not deleted from the database when you delete the category through the controller. Deliver published Select Yes if you want details to accompany the notification that items with something has been published. If you select No, only the notification is notification? sent to users. Notify Select Yes to notify subscribers when items in the category are subscribers when deleted. items are deleted? Allow anyone to subscribe to nodes in this category? Select Yes to allow any user to subscribe to nodes in this category. If you select No , only InfoBroker administrators can subscribe to nodes in the category. Allow anyone to create nodes in this category? Select Yes to allow any user to create nodes in this category. If you select No , only InfoBroker administrators can create nodes in the category. Database Setup Select this option if you want to configure a database that is different from the one configured for the core router in the Global Settings Configuration page. Datasource Name For the PostgreSQL database, this is the name of the component’s datasource as specified in the .odbc.ini file. For Oracle, the datasource is specified in the ORACLE_SID environment variable or in the tsnames.ora file. For DB2, this is typically the database alias. Database User Name Enter the username used to connect to the database. Database User’s Password Enter the password used to connect to the database. Confirm Password Enter the password again to confirm it. Administering Presence Services XCP Controller August 2010 133 Access Parameter Database Type Description Select the type of database you are using from the list. Note: If you select postgresql-odbc, you must add the line, “ MaxVarcharSize=4000” to the datasource definition used in the .odbc.ini file. Number of Connections to the database Enter the number of connections that you want the component to use for processing requests. Time in seconds between database connection heartbeats Enter the number of seconds after which the database connection should refresh. Do not set this value to zero without contacting technical support. Advanced Parameters The following table describes the parameters that are displayed in the controller’s Advanced configuration view. Parameter Description Only send notifications to subscribers who are online? Select Yes to if you do not want users who are offline to receive notifications of new or changed information in this category. Selecting Yes presence-enables the category. If you select No, notifications are sent to everyone who is subscribed to nodes in this category regardless of whether they are online. JIDs for Proxy Entities Enter the JIDs of the users whom you want to administer this particular category. Maximum items for each node Enter the maximum number of items that can be contained in each node in the category. Maximum subscriptions for each node Enter the maximum number of subscriptions that can occur for each node in the category. Maximum affiliations for each node Enter the maximum number of users who can be affiliated with the node. Affiliations include Owner, Publisher, None, and Outcast. Database Setup Is database debug logging enabled? 134 Select ’1’ to log database debug information. Database logging uses the XCP router’s logging facility, the IPS Logger. The log level must be set to debug for database logging to occur. Administering Presence Services XCP Controller August 2010 InfoBroker Administering Presence Services XCP Controller August 2010 135 Access 136 Administering Presence Services XCP Controller August 2010 Chapter 7: Connection managers The Connection Manager (Communication Manager) enables IM clients to connect to the Presence Services server. You can configure an additional instance of the Communication Manager to increase the number of connections your server can handle. When you install the Presence Services server, one Connection Manager is already configured for handling XMPP connections from XMPP IM clients. You may want to configure another Communication Manager to increase the scalability of your system. Each Communication Manager has a maximum number of connections that it can handle. The XMPP client Communication Manager can handle only 10,000 concurrent client connections. Your system can handle more client connections (up to 20,000 connections) if you add an additional Communication Manager to also handle XMPP client connections. Important: 10,000 connections is a practical limit for a Communication Manager. There is nothing preventing you from configuring more; however, more connections may cause performance to suffer. Note: In this chapter when we refer to a Communication Manager component we specifically mean a Communication Manager component that is configured to handle incoming XMPP client connections. If you have chosen to perform a full installation at install time, (for example, you have chosen to install the OCS Gateway to allow integration with a Microsoft Office Communication Manager (OCS) domain) then a Communication Manager component (called OCS Connection Manager) with a different type of configuration has been added for this purpose. In this case the Connection Manager component is essentially configured as a SIP Gateway to allow communication with a Microsoft OCS domain. This type of Communication Manager should not be confused with a Communication Manager for handling XMPP connections as discussed in this chapter. This Chapter consists of the following topics: • Verifying Connection Manager certificates on page 137 • Adding and configuring an additional Connection Manager on page 138 Verifying Connection Manager certificates Before adding an additional Communication Manager verify that the appropriate certificates to be used by the Communication Manager have been successfully created during installation of the Presence Services server. The certificates would failed to have been created at installation Administering Presence Services XCP Controller August 2010 137 Connection managers time if the System Manager Trust Management (TM) Service was not available. If the appropriate certificates do not exist then they must be created. To verify whether the certificates exist: 1. Open a terminal into the Presence Services server and change directory to $PRES_HOME/jabber/xcp/certs. 2. Enter the 'ls' command in this directory. 3. If the list of files includes Avaya-host-key.pem and Avaya-ip-key.pem in addition to files similar to export-123123123.pem, export-123123123.pem.jabber, export-123123123.pem.private and export-123123123.trusts then it can be assumed that the files were successfully created at installation time. Result If the certificates do not exist, follow the steps to create the certificate: 1. $PRES_HOME/presence/bin/prescert reconfigureAll. 2. Restart PS by running the $PRES_HOME/presence/bin/stop.sh script followed by running the $PRES_HOME/presence/bin/start.sh script. 3. Verfiy that the certificates listed above have been created in the $PRES_HOME/ jabber/xcp/certs directory. Adding and configuring an additional Connection Manager This section describes how to add and configure an additional Connection Manager component. Adding an additional Communication Manager allows the system to handle more client connections than can be supported by a single Communication Manager (i.e. > 10,000 connections). The configuration parameters of the second Communication Manager must be the similar to the first Communication Manager except for the listening ports of the directors associated with each Communication Manager. Each Communication Manager director must have its own independent listening port. The following instructions describe how to configure the Connection Manager using the parameters provided in the Presence XCP Controller’s Advanced configuration view. For descriptions of all of the Communication Manager parameters, see the Connection Manager Configuration page’s online help. To configure an additional Communication Manager 138 Administering Presence Services XCP Controller August 2010 Adding and configuring an additional Connection Manager 1. Change to the Presence XCP Controller’s Advanced configuration view. 2. In the Components area on the Presence XCP Controller’s main page, click Go to add a Connection Manager. 3. In the Connection Manager Configuration page, change the Description so that it describes this particular Communication Manager, e.g. Connection Manager 2. 4. In the Connection Manager Configuration page, under the Connection Manager Configuration section change the Maximum number of sockets to be 10000. 5. To enable logging for the Communication Manager, select the Component Logging (Jlog) option;select the Logger option and then select the Filtered Syslog Logger option. The Level should default to INFO. Specify the pipe file to be written in the Pile file field (For example, /opt/Avaya/Presence/jabber/xcp/var/log/xmppcm2.pipe) and provide an identifier in the Identity field (For example, XMPPCM2). 6. Under Add a New Command Processor, select the JSM Command Processor in the list, and then click Go. 7. In the JSM Command Processor Configuration page, click Details beside the first XMPP Director. 8. On the XMPP Director Configuration page change the value in the Port field from the default value of 5222 to some other port number that is not currently in use (for example, 6222). This port will be used to listen for incoming connections on the second Communication Manager. 9. On the SSL Settings section, you need to clear and then re-select SSL Settings (this is in order to enable certain sub-fields under SSL Setting). 10. In the SSL Settings section set both the Full path to SSL key file field and the Full path to SSL cert file field to /opt/Avaya/Presence/jabber/xcp/certs/ Avaya-host-key.pem. 11. Set the Full path to root CA cert file field to point to the the CA cert file. The format of the path is /opt/Avaya/Presence/jabber/xcp/certs/<CAcert-file> where the appropriate value to use for <CA-cert-file> can be determined by locating a file of the form export-xxx.trusts in the /opt/ Avaya/Presence/jabber/xcp/certs/ directory (The xxx is a numeric string specific to your particular installation). 12. Scroll to the bottom of the page and set Enable XMPP Stream Compression to No. 13. Click Submit to save the director’s configuration. Administering Presence Services XCP Controller August 2010 139 Connection managers You are returned to the JSM Command Processor Configuration page. 14. Under Director Configuration, click Details beside the second XMPP director, and repeat the previous six steps (that is from step 8 to step 13) with the following proviso: The Port field of the second XMPP director must be set to a port value that is not currently in use (For example, 6223). 15. Click Submit on each configuration page until you have returned to the Presence XCP Controller’s main page. 16. Restart the Presence XCP system. Result Note: If you are using Active Directory for user authentication and you have configured Kerberos on the first Communication Manager then follow steps 10-16 from Kerberos authentication and Microsoft Active Directory on page 215 to configure kerberos for the Communication Manager that has just been added. 140 Administering Presence Services XCP Controller August 2010 Chapter 8: File Transfer Proxy T he File Transfer Proxy component allows you to enable server-based file transfer capabilities via a SOCKS5 proxy. The component acts as a SOCKS5 proxy server, and allows byte streams to be transferred between your XCP server and Presence clients that are external to your system. Figure 22 illustrates how the external Presence clients communicate with the File Transfer Proxy component. During configuration, you must specify the IP addresses of both the firewall router and the host on which the File Transfer Proxy component is installed. You must also specify the port on which connections are made to the component. Configuring the Basic File Transfer Proxy This section describes how to configure the File Transfer Proxy component using the parameters provided in the controller’s Basic configuration view. These parameters are sufficient to configure a functional File Transfer Proxy. To see descriptions of all of the parameters, see File Transfer Proxy Parameter Reference . Related topics: To configure the File Transfer Proxy on page 141 To configure the File Transfer Proxy 1. Change to the controller’s Basic configuration view. 2. In the Components area on the controller’s main page, select File Transfer Proxy in the list, and then click Go . 3. On the File Transfer Proxy Configuration page, configure the Basic parameters using the descriptions provided in the ”Basic Parameters” section. 4. Click Submit to save your configuration. Administering Presence Services XCP Controller August 2010 141 File Transfer Proxy File Transfer Proxy Parameter Reference This section describes the parameters associated with the File Transfer Proxy component. The parameters are divided into subsections based on the configuration view in which they display. Related topics: Basic Parameters on page 142 Intermediate Parameters on page 143 Advanced Parameters on page 144 Basic Parameters The following table describes the parameters that are displayed in the controller’s Basic configuration view. These parameters are sufficient to configure an operational File Transfer Proxy component. Parameter Description Description The description is displayed in the Components area on the controller’s main page and should help you distinguish between components of the same type when you have more than one configured. You can change the description as needed. File Transfer Proxy Configuration SOCKS5 server host Enter the external IP address on which external systems can connect to the XCP server. Is Server Behind a NAT firewall? Select this option if your XCP server is behind a firewall that is performing Network Address Translation (NAT). Host or address Enter the host name or IP address of the host on which the File Transfer bound to physical Proxy component is installed. interface SOCKS5 server listen port 142 Enter the port on which connections are made to the File Transfer Proxy component. If you are using a NAT firewall, it should forward bytes streams to this port. Administering Presence Services XCP Controller August 2010 File Transfer Proxy Parameter Reference Intermediate Parameters The following table describes the parameters that are displayed in the controller’s Intermediate configuration view. Parameter Description Router Outbound Connection Information Select this option only if you want the XCP router to connect to the component. For example, if the component is running outside your firewall, this option allows the router to connect to the component safely rather than introducing security risks by letting the component connect to it. By default, components connect to the router using the router’s Master Accept Port. Component IP Enter the IP address or host name of the system on which the component is installed. Port Enter the port that the component uses for communications. Password Enter the password that the router uses to authenticate the component. Execute an External Command This option allows the router to start the component automatically. If you prefer to start the component from a command line, disable this option. Command line to run A command that runs the component automatically is provided by default. You can modify it if needed. Note: Do not use the -B argument with this component. Since IPS logger is already a daemon process, its children must not be daemons. You should not redirect output, because all output to STDOUT and STDERR will be redirected to /dev/null. Hostnames for this Component This option specifies the hosts for which this component will handle packets. Specify a host filter only if you want the component to be externally addressable; for example, if you want clients and other components or programs to communicate with it. This is because the mod_disco module in JSM uses host filters to return the component as something that should be discoverable. Host Filters Enter the host names or IP addresses for which you want this component to handle packets. Separate each host name or address with a line break. Host filters must be host names, or IPv4 or IPv6 addresses. If you use an IP address, the packet address must also use this IP address. Component Logging (Jlog) Select the Component Logging (Jlog) option only if you want to configure filtered level loggers that log messages to syslog and to a stream (stderr or stdout). You can enable either or both the syslog and stream loggers. These parameters are displayed in the controller’s Intermediate and Advanced configuration views. Administering Presence Services XCP Controller August 2010 143 File Transfer Proxy Parameter Description SNMP Configuration Select this option if you want to configure SNMP for the component. Enable SNMP Leave this parameter set to Yes. Advanced Parameters The following table describes the parameters that are displayed in the controller’s Advanced configuration view. Advanced parameters are used for adjusting the performance of the XCP system. We recommend that you call technical Support if you need to change these parameter settings. Parameter Description Runlevel Enter the order in which this component shuts down. The runlevel must be an integer value greater than or equal to zero. Component shutdown is executed in reverse order of the specified runlevel; components with the highest level (typically 70) shut down first. Do not change the runlevel unless you know exactly what you are doing and understand the effects that changing it will have. The default runlevel is provided to help the system shut down as smoothly as possible, and is based on this component’s dependencies upon other components. Timeout for shutdown Enter the number of seconds that the server waits to receive acknowledgement from the component that the shutdown process has completed. If the component has not shut down by the time this time period has elapsed, the router leaves the process in its current state and continues shutting down other processes. Component Properties Number of Enter the number of packets bound for the component that should be packets buffered buffered if the component goes down. when component is down Bounce error packets to stderr Select Yes if you want the router to send warnings to stderr when the component is down. Router Outbound Connection Information Buffer size in Enter the number of bytes the router should buffer when it sends bytes for outgoing information to the component. You may want to modify this element data when working on performance enhancements. Buffer size in bytes for incoming data 144 Enter the number of bytes the router should buffer when it receives information from the component. You may want to modify this element when working on performance enhancements. Administering Presence Services XCP Controller August 2010 File Transfer Proxy Parameter Reference Parameter Description Send keepalives Select Yes if you want the router to send keep-alives to the component. The keep-alive helps prevent firewalls from dropping an unused connection to the component. If this option is set to No, keep-alives are disabled. Log the delivery of packets to this component Select Yes if you want to log the data that the router delivers to the component. The information is logged to the logger(s) you set up during IPS Logger configuration (syslog, file, or stderr). Socket-level logging happens only at the debug level. Execute an External Command Maximum interval in seconds to wait before restarting component Enter the maximum number of seconds after which the router tries to restart the component. If the component goes down, the router tries to restart it after one second. If the component does not start, the router multiplies the wait time by 1.5, and tries again. Once the maximum time interval that you specify for this parameter is reached, the router continues to retry after waiting this amount of time. Maximum number of times to restart component Enter the total number of restarts allowed. The default setting, -1, means unlimited. Interval in Enter the number of seconds that the component has been up and seconds at which running, after which to set the restart time back to one second. to reset this value to 1 second Path to binary Enter the directory path to the shell that launches the component. You can change the default setting if needed. File Transfer Proxy Configuration Number of threads to dedicate to file transfer proxy tasks Enter the number of threads that you want the component to use. Maximum number of connections Enter the maximum number of connections that can be made to this component at one time. Duration of inactivity for connection timeout (seconds) Enter the number of seconds that the XCP server waits for a response from external systems before timing out. Component Logging (Jlog) Administering Presence Services XCP Controller August 2010 145 File Transfer Proxy Parameter Add a new custom logger Description If you have created a custom logger for logging component information using the libjcore library, click Go to access the Custom Logger Configuration page. SNMP Configuration Count errors 146 Select Yes only if you want to enable SNMP error counting. This option takes a great deal of server resource, so use it with caution. Administering Presence Services XCP Controller August 2010 Chapter 9: OCS Gateway The OCS gateway allows the exchange of messages and presence between XMPP users and users of Microsoft Office Communications Server. The gateway does not require XMPP client users to have authorization on remote systems; from a user’s perspective, it is completely transparent. Using the gateway, XMPP users can add OCS contacts to their rosters in the same way they add XMPP contacts. OCS contact IDs use the same format as Jabber contacts; for example, [email protected]. At installation time, if “Complete” installation has been chosen then the OCS Gateway will already be configured as the components (OCS Connection Manager and OCS Open Port). Only if OCS Connection Manager and OCS Open Port components does not exist, you should proceed adding the components as described in this chapter. . This Chapter consists of the following topics: • Verifying OCS Gateway certificates on page 147 • Configuring a Server-to-Server Connection Manager on page 148 • Configuring the OCS Gateway on page 149 • Adding an Outgoing Connection Attempt Rule in the S2SCP on page 152 • Configuring an OpenPort connection on page 153 • Configuring Jabber administrators on page 153 Verifying OCS Gateway certificates Before proceeding to add the OCS Gateway it is important to verify that the appropriate certificates to be used by the OCS Communication Manager have been successfully created during installation of the Presence Services server. The certificates would failed to have been created at installation time if the System Manager Trust Management Service was not available. If the appropriate certificates do not exist then they must be created. To verify whether the certificates exist: Administering Presence Services XCP Controller August 2010 147 OCS Gateway 1. Open a terminal into the Presence Services server and change directory to $PRES_HOME/jabber/xcp/certs. 2. Enter the 'ls' command in this directory. 3. If the list of files includes Avaya-host-key.pem and Avaya-ip-key.pem in addition to files similar to export-123123123.pem, export-123123123.pem.jabber, export-123123123.pem.private and export-123123123.trusts then it can be assumed that the files were successfully created at installation time. Result If the certificates do not exist, follow the steps to create the certificate: 1. $PRES_HOME/presence/bin/prescert reconfigureAll. 2. Restart PS by running the $PRES_HOME/presence/bin/stop.sh script followed by running the $PRES_HOME/presence/bin/start.sh script. 3. Verfiy that the certificates listed above have been created in the $PRES_HOME/ jabber/xcp/certs directory. Configuring a Server-to-Server Connection Manager To configure the S2S Connection Manager 1. Access the Presence XCP controller on the Presence Services server on which the OCS Gateway is to be added. 2. Change to the controller’s Intermediate configuration view. 3. In the Components area on the controller’s main page, click Go to add a new Connection Manager. 4. In the Connection Manager Configuration page, change the Description so that it describes this particular Communication Manager, (For example, OCS Connection Manager). 5. In the Connection Manager Configuration page, under the Connection Manager Configuration section change the Maximum number of sockets to be 5000. 6. To enable logging for the Communication Manager, select the Component Logging (Jlog) option; select the Logger option and then select the Filtered Syslog Logger option. The Level should default to INFO. Specify the pipe file to be written in the Pile file field (For example, /opt/Avaya/Presence/jabber/xcp/var/log/ocs- 148 Administering Presence Services XCP Controller August 2010 Configuring the OCS Gateway cm.pipe) and provide an identifier in the Identity field (For example, OCSCommunication Manager) 7. Under Add a New Command Processor, select S2S Command Processor in the list, and then click Go. 8. On the S2S Command Processor Configuration page, remove the two default XMPP directors. 9. Under Outgoing Connection Attempt Rules, remove the three default rules. 10. Add and configure the OCS gateway as described in the next section. Configuring the OCS Gateway The OCS gateway is configured within the S2S Command Processor as a SIP/SIMPLE Gateway director. To configure the gateway: 1. In the S2S Command Processor Configuration page under Director Configuration, select SIP/SIMPLE Gateway in the list, and then click Go. 2. In the SIP/SIMPLE Gateway Configuration page, make a note of the ID. You will need to use this ID later on in the gateway’s configuration. 3. Configure a SIP host as follows: a. Ensure you are in the controller’s Intermediate configuration view. b. Select Local Configuration, and then click Go to display the SIP Host Configuration page. c. In the SIP Host Configuration page, configure the following parameters. Table 2: SIP Host Configuration parameters Parameter Description Remote server hostname Enter the FQDN of the OCS Access Edge Server to which the gateway is connecting; for example: ocsproxy.example.com Server Type Select ocs in the list. Hostname Mapping Enter the host names that map to the remote server hostname. You should Administering Presence Services XCP Controller August 2010 149 OCS Gateway Parameter Description enter the Enterprise SIP domain of the OCS server here. d. When you have finished configuring the SIP Host, click Submit. You are returned to the SIP/SIMPLE Gateway Configuration page. 4. Under Add a new SIP Transport, select TLS transport in the list, and then click Go. 5. In the TLS Transport Configuration page, configure the transport using the parameter descriptions provided in the following table. Table 3: The TLS transport parameters Parameter Description Hostname of external interface Enter the primary Jabber XCP server’s JSM hostname. This is the JID domain of the PS server, for example, example.com IP Address Enter the IP address of the server on which this component is running. SIP servers will use this address to connect to the component. Port Enter the port on which this component listens for connections from SIP connectors. Use this transport by default for TLS This should be set to Yes. requests Domain used for TLS certificate Enter the domain used when creating the certificate. This value is contained in the common name field in the certificate. This should be set to the FQDN of the Presence Services server, for example, chat.example.com. Full path to certificate file Enter the full path to the location of the certificate file. The path will take the form / opt/Avaya/Presence/jabber/ xcp/certs/<Cert-file> where the appropriate value to use for <Cert-file> can be determined by locating a file of the form export-xxx.pem.jabber in the / opt/Avaya/Presence/jabber/ xcp/certs/ directory. Note: xxx is a numeric string specific to your particular installation. 150 Administering Presence Services XCP Controller August 2010 Configuring the OCS Gateway Parameter Full path to the CA certificate file Description Enter the full path to the CA certificate file that is used to verify incoming client certificates. The path will take the form / opt/Avaya/Presence/jabber/ xcp/certs/<CA-cert-file> where the appropriate value to use for <CA-cert-file> can be determined by locating a file of the form exportxxx.trusts in the /opt/Avaya/ Presence/jabber/xcp/certs/ directory. Note: xxx is a numeric string specific to your particular installation. Routes for this Transport You do not need to add a route in this TLS transport configuration. 6. Perform the following configuration: a. Change to the controller’s Advanced configuration view. b. Define an external contact for SIP servers to use to contact this transport by configuring the following two parameters: Table 4: Define an external contact for SIP servers Parameter Description External hostname that SIP servers will use for contact Enter the fully qualified domain name of the local system on which the gateway is running, for example, chat.example.com. External port that SIP servers will use Enter the port on which the firewall is for contact listening for incoming traffic. For example, 5061. 7. When you have finished configuring the transport, click Submit to save your configuration. You are returned to the SIP/SIMPLE Gateway Configuration page. 8. On the S2S Command Processor Configuration page set TLS connection strict checking of hostname to No, set TLS connection strict certificate usage to No, set Enable logging of SIP packets to Yes and set Enable full SIP stack logging to Yes. 9. Click Submit again to return to the S2S Command Processor Configuration page. Administering Presence Services XCP Controller August 2010 151 OCS Gateway Adding an Outgoing Connection Attempt Rule in the S2SCP On the S2S Command Processor Configuration page, you must add an outgoing connection attempt rule that is specific to your gateway. To add an outgoing connection attempt rule 1. On the S2S Command Processor Configuration page, scroll down to the Outgoing Connection Attempt Rules area. Important: The S2SCP configuration includes three XMPP rules by default. If you have not done so already, remove each existing rule before adding the new rule. 2. Click Go to display the Rule Configuration page. 3. Configure the following parameters: Table 5: Rule Configuration parameters Parameter Director ID Description Enter the gateway director’s ID without the realm; for example: cm-1_s2scp-1_sipsd-1 The director's ID to be specified here was recorded as part of step 3 in the Configuring the OCS Gateway section above. DNS SRV lookup to use Enter any string; for example: abcdefg 4. Click Submit to save the rule. You are returned to the S2S Command Processor Configuration page. 5. Click Submit to save your configuration. You are returned to the Connection Manager Configuration page. 6. Click Submit to save your configuration. 152 Administering Presence Services XCP Controller August 2010 Configuring an OpenPort connection Configuring an OpenPort connection You must add an OpenPort connection to allow the S2S Command Processor to connect to the router. Tip: In the steps below the ID of the gateway’s S2S Command Processor is needed. If you do not know the ID, access the gateway’s XCP controller, and click the Edit link beside 'OCS Connection Manager'. The entry that appears in the Name column under Add a New Command Processor is of the form 'ID.realm' (e.g. cm-1_s2scp-1.presence) where the ID part is the ID of the gateway’s S2S Command Processor. To configure an OpenPort: 1. Using the controller on the gateway’s computer, change to the Intermediate configuration view. 2. In the Components area on the controller’s main page, select OpenPort in the list, and click Go. 3. When you are asked for the ID of the OpenPort, enter the ID of the gateway’s S2S Command Processor without the realm; for example: cm-1_s2scp-1 4. Click OK. 5. On the OpenPort Configuration page, enter a new Description, for example, OCS Open Port. 6. Enter an asterisk (*) in the Host Filters box. 7. Click Submit to save your configuration. You are returned to the controller’s main page. Configuring Jabber administrators To add the S2SCP as a Jabber administrator Administering Presence Services XCP Controller August 2010 153 OCS Gateway 1. On your primary Jabber XCP server, change to the controller’s Intermediate configuration view. 2. In the Router area on the controller’s main page, click Edit beside Jabber Session Manager. 3. In the Optional Modules section on the Jabber Session Manager Configuration page, make sure that the check box beside mod_admin is checked. 4. Scroll down to the Jabber Administrators section, and enter the ID and realm of the OCSgateway’s S2S Command Processor in the Administrator(s) text box. For example: cm-1_s2scp-1.presence Tip: If you do not know the gateway server’s realm, access the gateway’s controller, and click the Edit link beside Global router settings in the Router area. The Realm is the second parameter on the Global Settings Configuration page. 5. Scroll to the bottom of the Jabber Session Manager Configuration page, and click Submit to save your configuration. 6. Restart your Presence Services system. 154 Administering Presence Services XCP Controller August 2010 Chapter 10: Server-to-Server connections The Server-to-Server connection manager (S2S Communication Manager) enables Presence Services servers to communicate with remote servers across domains. It also supports the Presence dialback protocol, which determines whether or not to trust a connection from another server. The following figure illustrates the S2S Connection Manager configuration. This Chapter consists of the following topics: • Configuring the Basic S2S Connection Manager on page 155 • Configuring the OpenPort connection on page 156 • Configuring the dialback password on page 157 • Blacklisting and Whitelisting Hosts and IP Addresses on page 158 • Discovery Protocol for Querying the S2S Command Processor on page 159 Configuring the Basic S2S Connection Manager The S2S Connection Manager is configured with an S2S Command Processor, which contains an XMPP incoming director and an XMPP outgoing director for XMPP server-to-server communications. These directors allow you to black-list and white-list specific hosts that are inside or outside of your Presence XCP system. The incoming director handles incoming packets that are being sent to the Presence XCP router from remote servers; the outgoing director handles packets that are being sent from the router to remote servers. The figure illustrates the handling of packets that are sent to or received from blacklisted hosts. We recommend that you configure a new separate server-to-server connection manager in order to maximize the efficiency with which the Presence Services server can handle S2S communication. To configure the basic S2S Communication Manager 1. Change to the Presence XCP Controller’s Basic configuration view. 2. In the Components area on the Presence XCP Controller’s main page, click Go to add a new Connection Manager. 3. On the Connection Manager Configuration page under Add a New Command Processor, select S2S Command Processor in the list, and click Go. 4. An outgoing director and an incoming director have been provided by default. Administering Presence Services XCP Controller August 2010 155 Server-to-Server connections The outgoing director handles packets that are being sent from the core router to remote servers. The incoming server director handles packets being sent to the router from remote servers. 5. Three Outgoing Connection Attempt Rules have been provided by default. These rules specify the order and DNS lookup properties for each outbound director. By default, these three rules are configured with the ID of the XMPP outgoing server director and the DNS SRV lookup or port to use for the connection. The default rules are configured as follows, where n is the number of the Communication Manager. Director ID DNS SRV lookup cm-n_s2scp-1_xmppsoutd-1 _xmpp-server._tcp cm-n_s2scp-1_xmppsoutd-1 _Presence._tcp cm-n_s2scp-1_xmppsoutd-1 Port 5269 Each time a new outbound connection is required, the S2SCP goes through the rules asking the specified director to attempt the outgoing connection. If a director successfully establishes a connection, then that director will always handle stanzas bound for that particular host. Otherwise, the S2SCP asks the next director (using the defined rules) to attempt an outbound connection for the host. You only need to add a new rule if you want to change how the DNS lookups happen for outbound servers. Configuring the OpenPort connection You must configure an OpenPort connection to enable the S2S command processor to connect to the Presence XCP router. To configure the OpenPort connection 1. Change to the Presence XCP Controller’s Intermediate configuration view. 2. In the Components area on the Presence XCP Controller’s main page, select OpenPort in the list, and click Go. 3. Enter the S2S Command Processor’s ID, without the realm, as the ID of the OpenPort. for example: cm-2_s2scp-1 156 Administering Presence Services XCP Controller August 2010 Configuring the dialback password 4. The OpenPort must use the opposite connection type than that used by the S2S command processor. If you used the default connection type of connect for the S2S command processor, skip to step 5 on page 0 . If you configured the S2S command processor with an accept connection type, you must select the Router Outbound Connection Information option for the OpenPort, and specify the same Component IP, Port, and Password that you used for the command processor. 5. Under Hostnames for this Component, enter a host filter to allow packets destined for external domains to reach the S2S command processor. In most cases, you should enter an asterisk (*) in the Host Filters field. 6. Click Submit to save your configuration. 7. Restart your Presence XCP system. Configuring the dialback password The S2S Communication Manager supports the Presence dialback protocol, which determines whether or not to trust a connection from another server. To configure the dialback password 1. Change to the Presence XCP Controller’s Basic configuration view. 2. In the Components area on the Presence XCP Controller’s main page, click Go to add a new Connection Manager. 3. On the Connection Manager Configuration page under Add a New Command Processor, select S2S Command Processor in the list, and click Go. 4. In the Dialback secret field, enter the password used to prove the authenticity of another server. By default, the dialback secret is set to the Presence XCP router’s password. If you have multiple S2S command processors in your Presence XCP system, they must all have the same dialback secret. Administering Presence Services XCP Controller August 2010 157 Server-to-Server connections Blacklisting and Whitelisting Hosts and IP Addresses If you want to blacklist and whitelist certain hosts and IP addresses from sending and receiving packets, you can configure one or more of the authorized outgoing and incoming, to and from addresses. These four configuration options, which are displayed in the Presence XCP Controller’s Intermediate configuration view, allow you to specify exactly which hosts and IP addresses may or may not send or receive incoming or outgoing packets. Each authorization option has a Default behavior parameter, which controls how you want your system to handle packets for all hosts or IPs except for those listed under Host Filters and IP addresses. Specified hosts and IP addresses will behave in a manner opposite the default behavior. To blacklist and whitelist hosts and IP addresses 1. Change to the Presence XCP Controller’s Intermediate configuration view. 2. Configure one or more of the following authorization options: Result • Authorized Outgoing From Addresses - lets you specify the hosts and IP addresses within your organization from which outgoing packets can be sent. If you set the default behavior to allow, all hosts and IPs except for those listed are allowed to send outgoing packets. If you set the default behavior to deny, only the listed hosts and IPs can send outgoing packets. Outgoing from addresses are usually paired with incoming to addresses. • Authorized Outgoing To Addresses - lets you specify the hosts and IP addresses to which users within your organization can send outgoing packets. If you set the default behavior to allow, users can send packets to all hosts and IPs except for those listed. If you set the default behavior to deny, users can send packets only to the hosts and IPs listed. Outgoing to addresses are usually paired with incoming from addresses. • Authorized Incoming From Addresses - lets you specify the hosts and IP addresses from which incoming packets can be received by users in your organization. If you set the default behavior to allow, users can receive packets from all hosts and IPs except for those listed. If you set the default behavior to deny, users can receive packets only from the hosts and IPs listed. Incoming from addresses are usually paired with outgoing to addresses. • Authorized Incoming To Addresses - lets you specify which hosts and IP addresses within your organization can receive incoming packets. If you set the default behavior to allow, all hosts and IPs except for those listed can receive packets. If you set the default behavior to deny, only the listed hosts and IPs can receive packets. Incoming to addresses are usually paired with outgoing from addresses. 158 Administering Presence Services XCP Controller August 2010 Discovery Protocol for Querying the S2S Command Processor Discovery Protocol for Querying the S2S Command Processor Following are XMPP protocol examples, based on XEP-0030: Service Discovery, of how to disco the inbound and outbound S2S connections. See XEP-0030 for more information. Related topics: Example: Querying the S2SCP for information on page 159 Example: Querying for outbound and inbound lists on page 159 Example: Querying S2CP for all items on page 160 Example: Querying the S2SCP for information The following XMPP query asks for information about the S2SCP whose ID is cm-2_s2scp-1.jabber: <iq id='disco-info-10' to='cm-2_s2scp-1.jabber' type='get'> <query xmlns=' http://jabber.org/protocol/disco#info '/> </iq> The following response from the server identifies the S2SCP as a component of type s2s. <iq xmlns='Presence:client' from='cm-2_s2scp-1.jabber' id='disco-info-10' to=' [email protected] /Presence Messenger Desktop Corp' type='result' xml:lang='en'> <query xmlns=' http://jabber.org/protocol/disco#info '> <identity category='component' type='s2s'/> </query> </iq> Example: Querying for outbound and inbound lists <iq id='disco-info-10' to='cm-2_s2scp-1.jabber' type='get'> <query xmlns=' http://jabber.org/protocol/disco#items' node='-outbound'/> </iq> <iq id='disco-info-10' to='cm-2_s2scp-1.jabber' type='get'> Administering Presence Services XCP Controller August 2010 159 Server-to-Server connections <query xmlns=' http://jabber.org/protocol/disco#items' node='-inbound'/> </iq> Example: Querying S2CP for all items The following XMPP query asks for a list of all items associated with the S2SCP: <iq id='disco-info-10' to='cm-2_s2scp-1.jabber' type='get'> <query xmlns=' http://jabber.org/protocol/disco#items'/ > </iq> The following response received from the server lists the items, which include an inbound node and an outbound node: <iq xmlns='Presence:client' from='cm-2_s2scp-1.jabber' id='disco-info-10' to=' [email protected] /Presence Messenger Desktop Corp' type='result' xml:lang='en'> <query xmlns=' http://jabber.org/protocol/disco#items '> <item jid='cm-2_s2scp-1.jabber' name='Inbound Connections' node='-inbound'/> <item jid='cm-2_s2scp-1.jabber' name='Outbound Connections' node='-outbound'/> </query> </iq> 160 Administering Presence Services XCP Controller August 2010 Chapter 11: Active Directory This chapter provides information about setting up the Active Directory component. This component has been preconfigured to provide most of the settings that you need for setting up the Presence Services server to work with Active Directory. Important: If you are using OpenLDAP for user authentication, see Chapter 9. Jabber Directory and LDAP for instructions on configuring the Presence Services server to work with LDAP. Chapter 9. Jabber Directory and LDAP also contains information about Jabber LDAP objectClasses and Attributes. This Chapter consists of the following topics: • Configuring the Jabber Directory component on page 167 • Configuring the JSM to use the Jabber Directory Component on page 172 Note: After configuring the Active Directory component as detailed in this chapter, if you wish to set up Kerberos to enable more secure authentication then you should refer to Kerberos authentication and Microsoft Active Directory on page 215 Configuring the Active Directory component To enable the Presence Services server to use Microsoft Active Directory, you must first configure the Active Directory component, which contains a directory server and a database. After you have configured the Active Directory component, you must then configure the Presence Session Manager (JSM) to use it. To configure the Active Directory component 1. Change to the Presence XCP Controller’s Intermediate configuration view. 2. In the Components area on the Presence XCP Controller’s main page, select Active Directory Component in the list, and then click Go. 3. In the Active Directory Component Configuration page, scroll down to the XDB Filters section. Administering Presence Services XCP Controller August 2010 161 Active Directory The namespaces that are most commonly used by the Active Directory component are selected by default. 4. Under Hostnames for this Component, ldapsearch.yourJIDDomain (for example, ldapsearch.example.com) is provided by default, which configures the Active Directory component to accept user search requests. You can add other hostnames as needed for hosts that will handle non-XDB packet. Related topics: Configuring a Directory Server to work with Active Directory on page 162 Configuring a database on page 163 Configuring a Directory Server to work with Active Directory You must now configure the connection to your directory server. To configure the directory server 1. Make sure you are still using the Presence XCP Controller’s Intermediate configuration view. 2. In the Active Directory Component Configuration page, scroll down to the JDS Configuration area and click Detail under Add a new Directory Server. The Directory Server Configuration page is shown in the following figure. 3. In the Directory Server Configuration page, configure the following parameters: Parameter 162 Description Directory server hostname Enter the fully qualified domain name of the Active Directory server. Directory server port Port 3268 is the standard port used for Active Directory. Read-only Select Yes if you want only read operations to be performed on the Active Directory server. A setting of Yes disables community group subscriptions. This option is used typically in master/slave configurations where the slave is a read-only copy of the master. Follow Referrals Select Yes if you want to enable referrals, which allow Active Directory servers to reference each other for information. Administering Presence Services XCP Controller August 2010 Configuring the Active Directory component Parameter Description In large networks, enabling this option can cause problems with time-outs due to excessive server chaining. Directory Server user Enter the distinguished name for a AD user, e.g. cn=presenceuser,cn=users,dc=example,dc=com, to allow the Presence Server to access user account details on the Active Directory server. If your directory server has security enabled and requires authentication, enter the distinguished name of the administration account for the Active Directory server. Password for directory Enter the password associated with the user account service user specified as the Directory Server user. Confirm Password Enter the password again to confirm it. 4. Use the online help in the Directory Server Configuration page to configure the remaining parameters if needed. 5. Click Submit to save your configuration. You are returned to the Active Directory Component Configuration page. Configuring a database You must now configure the Active Directory database. In the Database Configuration page, many default values have been supplied for Active Directory. To configure the LDAP Database 1. In the JDS Configuration area under Databases, click Detail under Add a new Database. 2. In the Database Configuration page, the default directory server, ads-1_server-1, has already been added. If you have multiple directory servers configured for this database, click Go to add each server, supplying its ID in the Server Configuration page. Administering Presence Services XCP Controller August 2010 163 Active Directory Important: The system automatically fails over to a working directory server. If you have multiple directory servers configured for this database, the first one listed is used by default. If that server fails, the next one in the list is used, and so on. 3. On the Database Configuration page under Jabber User Configuration, configure the Base context for this LDAP class parameter. Default values have been supplied for the other parameters. The following table describes the parameters for the LDAP object class.. Parameter Description LDAP object class for users The LDAP object class that represents a user. For Active Directory, this value is: user Base context for this LDAP class Enter the top level of the LDAP tree that contains user entries. For example: cn=users,dc=example,dc=com LDAP attribute to use for the Jabber display name Enter the LDAP attribute used to display each user’s name in the Jabber client interfaces. For Active Directory, this value is: displayName Static User JID This option is used for Active Directory, since the schema contains a host attribute that can be used for all Jabber IDs. User Attribute - SamAccountName is the name of the user attribute for Active Directory. Host - The JID domain of your Presence Services server is supplied by default; for example: example.com 4. Scroll down to view the JDS Command Definitions section if you want. Several commands have been preconfigured for Active Directory. They are described as follows: • The Authentication command has been selected and set to Plain-Text Authentication. • The Register Check command has been selected, which enables the Active Directory component to validate Jabber users. • The ldapSearchcommand has been selected, and four search attributes for Active Directory have been configured. This command enables Jabber users to search for other users. (This is not the same thing as vCard information.) 5. Click Submit on the Database Configuration page to save your configuration. You are returned to the Active Directory Component Configuration page. 6. Click Submit on the Active Directory Component Configuration page to save your configuration and return to the Presence XCP Controller’s main page. 164 Administering Presence Services XCP Controller August 2010 Configuring the JSM to use the Active Directory component Configuring the JSM to use the Active Directory component You must now configure the Presence Session Manager to use the Active Directory component. To configure the Presence Session Manager 1. Change to the Presence XCP Controller’s Basic configuration view. 2. In the Router area on the Presence XCP Controller’s main page, click Edit beside Presence Session Manager. 3. Under Optional modules, select the mod_jds module, and clear the check boxes next to mod_auth_plain and mod_auth_digest. These settings enable the Active Directory component for authentication and disable the default authentication. 4. Select the JDS Configuration option. Make sure that both Digest Authentication and Community Groups are set to No. 5. Scroll down to the Registration Requirements option and clear the check box to disable it. 6. Click Submit to save your configuration. 7. Restart your Presence Services system. Result Important: The Troubleshooting information for diagnosing issues with the Active Directory configuration is available in the Presence Services 5.2 Troubleshooting Guide in the chapter Active Directory Checklist. Please perform the diagnostic tests outlined there before escalating any issue on Active Directory configuration. Administering Presence Services XCP Controller August 2010 165 Active Directory 166 Administering Presence Services XCP Controller August 2010 Chapter 12: Jabber Directory and LDAP This chapter provides instructions for setting up the Presence Services XCP server to use OpenLDAP. You do this by configuring the Jabber Directory Component. See Appendix B. Configuring OpenLDAP Schema for details on adding some Jabber specific user, and object classes to your schema. Important: If you are using Microsoft Active Directory, see Appendix 8. Active Directory for instructions on configuring the Presence Services server to work with AD. Note: We do not provide installation instructions for LDAP directory servers. See the directory server’s product documentation for this information. This Chapter consists of the following topics: • Configuring the Jabber Directory component on page 167 • Configuring the JSM to use the Jabber Directory Component on page 172 • Jabber LDAP objectClasses and Attributes on page 173 • Directory Server optimization on page 174 Configuring the Jabber Directory component To enable the Presence Services server to use LDAP, you must first configure the Jabber Directory Component, which contains a directory server and an LDAP database. After you have configured the Jabber Directory Component, you must then configure the Presence Session Manager (JSM) to use it. To configure the Jabber Directory Component 1. Change to the Presence XCP Controller’s Intermediate configuration view. 2. In the Components area on the Presence XCP Controller’s main page, select Jabber Directory Component in the list, and then click Go. 3. In the Jabber Directory Component Configuration page, scroll down to the XDB Filters section, and select the namespaces that are appropriate for your directory server. Administering Presence Services XCP Controller August 2010 167 Jabber Directory and LDAP The most commonly used namespaces for directory servers are jabber:iq:auth, jabber:iq:register, and http://www.jabber.com/schemas/jds.xsd. 4. Under Hostnames for this Component, enter the host names or IP addresses for which you want the Jabber Directory Component to handle non-XDB packets. Separate each host name or address with a line break.If you want the Jabber Directory component to accept user search requests then you should add ldapsearch.yourJIDDomain, for example, ldapsearch.example.com Related topics: Configuring a Directory Server on page 168 Configuring an LDAP Database on page 169 Configuring a Directory Server You must now configure the connection to your directory server. To configure the directory server 1. Make sure you are still using the Presence XCP Controller’s Intermediate configuration view. 2. In the Jabber Directory Component Configuration page, scroll down to the JDS Configuration area and click Go beside Add a new Directory Server. 3. In the Directory Server Configuration page, make a note of the Unique server ID. You will need to use this value in the next section when you configure the LDAP database. If the Unique server ID is not already specified then enter one, (For example, jds-1_server-1) and note this value. 4. Configure the following parameters. Parameter 168 Description Directory server hostname Enter the fully qualified domain name of the LDAP server. Directory server port Port 389 is the standard port used for LDAP with TLS. If you are using LDAPS, change the port to 636. Read-only Select Yes if you want only read operations to be performed on the LDAP server. A setting of Yes disables community group subscriptions. This option is used typically in master/slave configurations where the slave is a read-only copy of the master. Administering Presence Services XCP Controller August 2010 Configuring the Jabber Directory component Parameter Follow Referrals Description Select Yes if you want to enable referrals, which allow LDAP servers to reference each other for information. Important: In large networks, enabling this option can cause problems with time-outs due to excessive server chaining. Directory Server user If your directory server requires authentication, enter the distinguished name of the administration account for the LDAP server. Password for directory Enter the password of the administration account for the service user LDAP server. Confirm Password Enter the password again to confirm it. 5. Use the online help to configure the remaining parameters if needed. 6. Click Submit to save your configuration. You are returned to the Jabber Directory Component Configuration page. Configuring an LDAP Database You must now configure your LDAP database. To configure the LDAP Database 1. In the JDS Configuration area under Databases, click Go beside Add a new Database. 2. In the Database Configuration page, click Go beside Add a new Server. 3. In the Server Configuration page, enter the unique server ID of the directory server that you configured in the previous section. For example: jds-1_server-1 Important: The system automatically fails over to a working directory server. If you have multiple directory servers configured for this database, the first one listed is used by default. If that server fails, the next one in the list is used, and so on. 4. Click Submit to save your configuration. You are returned to the Database Configuration page. Administering Presence Services XCP Controller August 2010 169 Jabber Directory and LDAP 5. On the Database Configuration page under Jabber User Configuration, configure the parameters to specify your LDAP setup. The parameters are described as follows. Parameter Description LDAP object class for users Enter the LDAP object class that represents a user. For example: inetOrgPerson Base context for this LDAP class Enter the top level of the LDAP tree that contains user entries. For example: cn=users,dc=example,dc=com LDAP attribute to use for the Presence display name Enter the LDAP attribute used to display each user’s name in the Presence client interfaces; for example, cn 6. Select one of the options to define how the Jabber Directory Component will build your Jabber IDs. The parameters are described as follows. Parameter Full JID Description Select this option if your schema contains an attribute that can be used as the full Jabber ID. Attribute - Enter the name of the attribute to use as the Jabber ID; for example: jabberID Note: This attribute must be of the form of a full Jabber ID, e.g. [email protected], where the domain associated with the attribute must be the JID domain of the Presence Services server. Static User ID Select this option if your schema contains a host attribute that can be used for all Jabber IDs. User Attribute - Enter the name of the user attribute; for example: uid Host - Enter the JID domain of your Presence Services server; for example: example.com User Host JID Select this option if user Jabber IDs must be constructed from two separate LDAP attributes. User attribute - Enter the name of the user attribute; for example: uid Host attribute - Enter the name of the attribute that contains the JID domain of your Presence Services server. 7. If your LDAP schema contains an attribute whose value signifies a valid Presence user, you can configure the Jabber Active Attribute option. When this attribute exists in your schema and has been configured in the Jabber Directory Component, you can disable a user’s account by modifying its value for 170 Administering Presence Services XCP Controller August 2010 Configuring the Jabber Directory component that user in your schema. Users whose accounts have been disabled can no longer log into the Presence Services server. To configure the Jabber Active Attribute: a. Select the Jabber Active Attribute option. b. Configure the parameters as follows. Parameter Description Type Select positive if the value you specify in the Value field must be in your LDAP schema for the user to be considered a valid Presence user. If you select negative, the Value you specify must not be in your LDAP schema. Attribute Enter the name of the LDAP attribute that contains the value that ensures a user is a valid Presence user; for example:jabberActive Value Enter the value that the LDAP attribute must or must not contain for a user to be a valid Presence user; for example:true 8. Scroll down to the JDS Command Definitions section, and select the Authentication command. 9. Select the option that you want to use for authentication. 10. If you want the Jabber Directory Component to validate Presence users, select the Register Check check box.. 11. If you want to enable Presence users to search for other users, select ldapSearch command. (This is not the same thing as vCard information.) Note: To allow user search requests you must add an entry under Hostnames for this Component on the Jabber Directory Component Configuration page (for example, ldapsearch.example.com) as described earlier. 12. Configure searchable LDAP attributes as follows: • Click Go to display the Searchable LDAP Attribute Configuration page. • Add an LDAP attribute and its description. Do not enter spaces in the description. • Click Submit. You are returned to the Database Configuration page, from which you can add additional attributes as needed. Administering Presence Services XCP Controller August 2010 171 Jabber Directory and LDAP Note: It may be useful to configure multiple rules. The following 3 rules are provided for example: • Description:lastname, LDAP attribute:sn • Description:fullname, LDAP attribute:cn • Description:email, LDAP attribute:mail The LDAP attributes that are specified in the rules should be indexed appropriately for searching in the slapd.conf file in the /etc/openldap directory (for example, index cn,mail,sn eq,pres,sub). 13. Click Submit on the Database Configuration page to save your configuration. You are returned to the Jabber Directory Component Configuration page. 14. Click Submit on the Jabber Directory Component Configuration page to save your configuration and return to the Presence XCP Controller’s main page. Configuring the JSM to use the Jabber Directory Component You must now configure the Presence Session Manager to use the Jabber Directory Component. To configure the Presence Session Manager 1. Change to the Presence XCP Controller’s Basic configuration view. 2. In the Router area on the Presence XCP Controller’s main page, click Edit beside Presence Session Manager. 3. Under Optional modules, select the mod_jds module, and clear the check boxes next to mod_auth_plain, mod_auth_digest, and mod_register. These settings enable the Jabber Directory Component for authentication and disable the default authentication. 4. Select the JDS Configuration option. Make sure that both Digest Authentication and Community Groups are set to No. 5. Scroll down to the Registration Requirements option and clear the check box to disable it. 172 Administering Presence Services XCP Controller August 2010 Jabber LDAP objectClasses and Attributes 6. Click Submit to save your configuration. 7. Restart your Presence XCP system. Jabber LDAP objectClasses and Attributes See Appendix B. Configuring OpenLDAP Schema for details on adding some Jabber specific user attributes, and object classes to your schema. The following information is also provided in the jabber.schema file. The following information is also provided in the jabber.schema file, which is located in $JABBER_HOME/schemas/ldap. Jabber LDAP objectClasses objectClass: jabberperson description: Jabber user OID: 1.3.6.1.4.1.13466.2.2.1.2 objectClass: jabbercggroup description: Jabber community group OID: 1.3.6.1.4.1.13466.2.2.1.3 Jabber LDAP Attributes attribute: jabberID description: Jabber Identifier OID: 1.3.6.1.4.1.13466.2.1.2.18 attribute: jabberActive description: flag to determine if a Jabber user is active OID: 1.3.6.1.4.1.13466.2.1.2.21 attribute: jabberHost description: Jabber ID host mapping OID: 1.3.6.1.4.1.13466.2.1.2.25 attribute: jabberCGSubscriber description: Jabber community group subscriber OID: 1.3.6.1.4.1.13466.2.1.2.3 attribute: jabberCGGroupcast description: Groupcast permission flag OID: 1.3.6.1.4.1.13466.2.1.2.7 attribute: jabberCGViewMembers description: View community group members permission flag OID: 1.3.6.1.4.1.13466.2.1.2.8 attribute: jabberCGPresence Administering Presence Services XCP Controller August 2010 173 Jabber Directory and LDAP description: Jabber community group presence permission flag OID: 1.3.6.1.4.1.13466.2.1.2.9 attribute: jabberCGSubscribe description: Jabber community group subscribe permission flag OID: 1.3.6.1.4.1.13466.2.1.2.24 Directory Server optimization For large installations, we recommend that you index several attributes to improve LDAP performance with the Jabber Directory Component. Here it is assumed that you have updated your schema to include the jabberID and jabberActive attributes as indicated in Appendix B. Configuring OpenLDAP Schema. • For all large installations, you should index the jabberID attribute for equality (not for substring). • jabberActive should be indexed for presence & equality Your LDAP directory service should contain tools to enable you to perform this indexing, for example the slapindex command line tool is typically available with OpenLDAP installations under Linux - please consult the slapindex documentation for using this tool as you may need to stop your LDAP service before using the tool in order to protect the integrity of the LDAP directory. 174 Administering Presence Services XCP Controller August 2010 Chapter 13: LaunchBroker T he LaunchBroker component integrates with the WebEx and Adobe Acrobat Connect Professional collaboration applications. The component also allows you to add your own custom commands. For example, you could create a command to allow users to request vacation time or to enter timecard information, or even to perform user administration. Commands that you create must comply with XEP-0050: Ad-Hoc Commands . Configuring the LaunchBroker Component The parameters provided in the controller’s Basic configuration view are sufficient to configure the LaunchBroker component’s WebEx Collaboration command and the Adobe Acrobat Connect Professional command For descriptions of all of the parameters associated with the component, see LaunchBroker Parameter Reference . Related topics: To configure the LaunchBroker component on page 175 To configure the LaunchBroker component 1. Change to the controller’s Basic configuration view. 2. In the Components area on the controller’s main page, select LaunchBroker in the list, and then click Go . The LaunchBroker Configuration page is displayed 3. To configure the WebEx Collaboration command, follow the instructions in Configuring the WebEx Collaboration Command . 4. To configure the Adobe Acrobat Connect Professional command, follow the instructions in Configuring the Adobe Acrobat Connect Professional Command . 5. If you want to configure a custom command, follow the instructions in Configuring a Custom LaunchBroker Command . Administering Presence Services XCP Controller August 2010 175 LaunchBroker Configuring the WebEx Collaboration Command This section describes how to configure the WebEx Collaboration Command feature, which allows Presence client users to create WebEx meetings and to send meeting invitations to contacts. The WebEx collaboration command sends two jabber:x:data forms to the user. The first form requests the user’s WebEx username and password, and the second form requests the meeting topic and the list of JIDs of those to invite to the meeting. Related topics: To configure the WebEx Collaboration Command on page 176 To configure the WebEx Collaboration Command Prerequisites Before you can configure the WebEx command, you must have the following in place: • You must be provisioned by WebEx. • You must have the following information from WebEx: Hostname prefix, WebEx PID, Site ID, Default meeting type. • Port 443 must be open on your firewall, since the WebEx command makes an outbound connection to https://<host_prefix >/webex.com:443. These steps describe how to perform a basic configuration of the WebEx Collaboration Command. 1. In the LaunchBroker Configuration page, select WebEx Collaboration Command to activate the parameters. 2. Configure the basic WebEx parameters using the following descriptions. Parameter Node Description Enter a unique identifier for the command. The following options require information that you receive from WebEx. Hostname prefix Enter the host prefix used to access the WebEx server. The WebEx command makes an outbound connection to https:// [hostname_prefix ].webex.com:443. 176 WebEx PID Enter your WebEx partner ID. Site ID Enter your site ID. Administering Presence Services XCP Controller August 2010 Configuring the Adobe Acrobat Connect Professional Command Parameter Default Meeting Type Description Enter the numeric code that denotes the meeting type. The default value or '3' indicates WebEx Meeting Center Pro. 3. Click Submit to save your configuration. Configuring the Adobe Acrobat Connect Professional Command This section describes how to configure the Adobe Acrobat Connect Professional Command feature, which allows Jabber Messenger 3.x users to locate and create online meetings on the Adobe Connect server. To integrate Adobe Acrobat Connect Professional with the XCP server, you must be running Adobe Connect, version 6.03. Related topics: Setting up Adobe Connect Server on page 177 To configure the Adobe Acrobat Connect Professional command on page 178 Setting up Adobe Connect Server These steps set up your Adobe Connect server for external authentication via HTTP header. 1. On your Adobe Connect server, change to the AdobeConnect_InstallDir \appserv \conf\WEB_INF directory. 2. Open the web.xml file in a text editor. 3. Locate the HeaderAuthenticationFilter section, and add comment delimiters around the <init-param> entry as shown here: <!-<init-param> <param-name>ignore-pattern-0</param-name> <param-value>/api/</param-value> </init-param> --> 4. Add comment delimiters around the <filter-mapping> entry as shown here: Administering Presence Services XCP Controller August 2010 177 LaunchBroker <!-<filter-mapping> <filter-name>NtlmAuthenticationFilter</filter-name> <url-pattern>/*</url-pattern> </filter-mapping> --> 5. Verify that the remainder of the HeaderAuthenticationFilter section is not commented, and save the web.xml file. 6. Change to the AdobeConnect_InstallDir directory. 7. Open the custom.ini file in a text editor. 8. Add the following attribute at the end of the file: HTTP_AUTH_HEADER=<header_name> where <header_name> is the name of the HTTP header populated by your external authentication system when a successful login has occurred; for example: HTTP_AUTH_HEADER=X-User-Id 9. Save the custom.ini file. 10. Restart your Adobe Connect server. To configure the Adobe Acrobat Connect Professional command 1. In the LaunchBroker Configuration page, select Adobe Acrobat Connect Professional to activate the parameters. 2. Configure the Basic parameters using the following descriptions. Parameter 178 Description Node Enter a unique identifier for the command. Adobe Connect SML API URL Enter the URL for the Adobe Connect XML API. For example: http://adobeconnect.server/api/xml Adobe Connect Admin User Enter the Adobe Connect administrator account. For example: [email protected] Administering Presence Services XCP Controller August 2010 Configuring a Custom LaunchBroker Command Parameter Description Admin Password Enter the Adobe Connect administrator’s password. Confirm Password Enter the password again to confirm it. 3. Click Submit to save your configuration. Configuring a Custom LaunchBroker Command The LaunchBroker allows you to add your own custom commands. For example, you could create a command to allow users to request vacation time or to enter timecard information, or even to perform user administration. Commands that you create must comply with XEP-0050:Ad-Hoc Commands. Related topics: To configure a custom command on page 179 To configure a custom command 1. Change to the controller’s Advanced configuration view. 2. Click Go beside Add a new Custom LaunchBroker Command . 3. In the Custom LaunchBroker Command Configuration page, configure the following parameters. Parameter Description Custom library Enter the name of the library for the custom command. Load Enter the load function for the command’s library. Node Enter a unique identifier for the command. Custom command configuration Add additional XML configuration for the custom command within the <config/> tag as needed. Do not change the toplevel configuration element. 4. Click Submit to save your configuration. Administering Presence Services XCP Controller August 2010 179 LaunchBroker LaunchBroker Parameter Reference This section describes the parameters associated with the LaunchBroker component. The parameters are divided into subsections based on the configuration view in which they display. Related topics: Basic Parameters on page 180 Intermediate Parameters on page 181 Advanced Parameters on page 182 Basic Parameters The following table describes the parameters that are displayed in the controller’s Basic configuration view. These parameters are sufficient to configure an operational LaunchBroker component. Parameter Description Description The description is displayed in the Components area on the controller’s main page and should help you distinguish between components of the same type when you have more than one configured. You can change the description as needed. WebEx Collaboration Command The WebEx Collaboration command allows Presence client users to create WebEx meetings and to send meeting invitations to contacts. The WebEx collaboration command sends two jabber:x:data forms to the user. The first form requests the user’s WebEx username and password, and the second form requests the meeting topic and the list of JIDs of those to invite to the meeting. Node Enter a unique identifier for the command. Hostname prefix Enter the host prefix used to access the WebEx server. The WebEx command makes an outbound connection to https:// [hostname_prefix ].webex.com:443. WebEx PID Enter your WebEx partner ID. Site ID Enter your site ID. Default Meeting Type Enter the numeric code that denotes the meeting type. The default value, 3, indicates WebEx Meeting Center Pro. Adobe Acrobat Connect Professional The Adobe Acrobat Connect Professional Command allows Jabber Messenger 3.x users to locate and create online meetings on the Adobe Connect server. 180 Administering Presence Services XCP Controller August 2010 LaunchBroker Parameter Reference Parameter Description Node Enter a unique identifier for the command. Adobe Connect XML API URL Enter the URL for the Adobe Connect XML API. For example: http://adobeconnect.server/api/xml Adobe Connect Admin User Enter the Adobe Connect administrator account. For example: [email protected] Admin Password Enter the Adobe Connect administrator’s password. Confirm Password Enter the password again to confirm it. Intermediate Parameters The following table describes the parameters that are displayed in the controller’s Intermediate configuration view. Parameter Description Router Outbound Connection Information Select this option only if you want the XCP router to connect to the component. For example, if the component is running outside your firewall, this option allows the router to connect to the component safely rather than introducing security risks by letting the component connect to it. By default, components connect to the router using the router’s Master Accept Port. Component IP Enter the IP address or host name of the system on which the component is installed. Port Enter the port that the component uses for communications. Password Enter the password that the router uses to authenticate the component. Execute an External Command This option allows the router to start the component automatically. If you prefer to start the component from a command line, disable this option. Command line to run A command that runs the component automatically is provided by default. You can modify it if needed. Note: Do not use the -B argument with this component. Since jabberd is already a daemon process, its children must not be daemons. You should not redirect output, because all output to STDOUT and STDERR will be redirected to /dev/null. Hostnames for this Component This option specifies the hosts for which this component will handle packets. Specify a host filter only if you want the component to be externally addressable; for example, if you want clients and other components or programs to communicate with it. This is because the Administering Presence Services XCP Controller August 2010 181 LaunchBroker Parameter Description mod_disco module in JSM uses host filters to return the component as something that should be discoverable. Host Filters By default, the XCP server’s host name prepended by ”eci” is provided. Enter the host names or IP addresses for which you want this component to handle packets. Separate each host name or address with a line break. Host filters must be host names, or IPv4 or IPv6 addresses. If you use an IP address, the packet address must also use this IP address. WebEx Collaboration Command HTTP Proxy Select this option if you want all WebEx traffic to go through an HTTP proxy. Host Enter the proxy’s IP address or FQDN. Port Enter the proxy’s port number. Adobe Acrobat Connect Professional HTTP Proxy Select this option if you want all Adobe Connect traffic to go through an HTTP proxy. Host Enter the proxy’s IP address or FQDN. Port Enter the proxy’s port number. Component Logging (Jlog) Select the Component Logging (Jlog) option only if you want to configure filtered level loggers that log messages to syslog and to a stream (stderr or stdout). You can enable either or both the syslog and stream loggers. These parameters are displayed in the controller’s Intermediate and Advanced configuration views. SNMP Configuration Select this option if you want to configure SNMP for the component. Enable SNMP Leave this parameter set to Yes. Advanced Parameters The following table describes the parameters that are displayed in the controller’s Advanced configuration view. Advanced parameters are used for adjusting the performance of the XCP system. We recommend that you call Technical Support if you need to change these parameter settings. Parameter Runlevel 182 Description Enter the order in which this component shuts down. The runlevel must be an integer value greater than or equal to zero. Component Administering Presence Services XCP Controller August 2010 LaunchBroker Parameter Reference Parameter Description shutdown is executed in reverse order of the specified runlevel; components with the highest level (typically 70) shut down first. Do not change the runlevel unless you know exactly what you are doing and understand the effects that changing it will have. The default runlevel is provided to help the system shut down as smoothly as possible, and is based on this component’s dependencies upon other components. Timeout for shutdown Enter the number of seconds that the server waits to receive acknowledgement from the component that the shutdown process has completed. If the component has not shut down by the time this time period has elapsed, the router leaves the process in its current state and continues shutting down other processes. Component Properties Number of packets Enter the number of packets bound for the component that should be buffered when buffered if the component goes down. component is down Bounce error packets to stderr Select Yes if you want the router to send warnings to stderr when the component is down. Router Outbound Connection Information Buffer size in bytes Enter the number of bytes the router should buffer when it sends for outgoing data information to the component. You may want to modify this element when working on performance enhancements. Buffer size in bytes Enter the number of bytes the router should buffer when it receives for incoming data information from the component. You may want to modify this element when working on performance enhancements. Send keepalives Select Yes if you want the router to send keep-alives to the component. The keep-alive helps prevent firewalls from dropping an unused connection to the component. If this option is set to No, keepalives are disabled. Log the delivery of packets to this component Select Yes if you want to log the data that the router delivers to the component. The information is logged to the logger(s) you set up during Jabberd Logger configuration (syslog, file, or stderr). Socketlevel logging happens only at the debug level. Execute an External Command Maximum interval in seconds to wait before restarting component Enter the maximum number of seconds after which the router tries to restart the component. If the component goes down, the router tries to restart it after one second. If the component does not start, the router multiplies the wait time by 1.5, and tries again. Once the maximum time interval that you specify for this parameter is reached, the router continues to retry after waiting this amount of time. Administering Presence Services XCP Controller August 2010 183 LaunchBroker Parameter Description Maximum number of times to restart component Enter the total number of restarts allowed. The default setting, -1, means unlimited. Interval in seconds at which to reset this value to 1 second Enter the number of seconds that the component has been up and running, after which to set the restart time back to one second. Path to binary Enter the directory path to the shell that launches the component. You can change the default setting if needed. LaunchBroker Configuration Number of threads to dedicate to LaunchBroker tasks Enter the number of threads that you want to have processing tasks in the component. Increasing this value enables the component to handle more tasks at a time. However, it spends more time scheduling the tasks as this number increases. We recommend that you set this number to one more than the number of processors on your system. WebEx Collaboration Command Command time-out Enter the number of seconds that the LaunchBroker should wait for form results before timing out. Adobe Acrobat Connect Command Command time-out Enter the number of seconds that the LaunchBroker should wait for form results before timing out. Should new Adobe Connect users be created Select Yes or No depending on whether you want the LaunchBroker to create new user accounts when it services requests from nonexistent users. HTTP header for effective ID Enter the HTTP header name that is used to set the effective user during proxy authentication requests. This field contains ”X-User-Id” by default, and should match the configuration of the Adobe Connect server. Local host Enter the names of one or more hosts that are treated as local to the server and for which accounts may be automatically created. By default, this field contains the host name of the server on which the XCP server is installed. Component Logging (Jlog) Add a new custom logger If you have created a custom logger for logging component information using the libjcore library, click Go to access the Custom Logger Configuration page. SNMP Configuration Count errors 184 Select Yes only if you want to enable SNMP error counting. This option takes a great deal of server resource, so use it with caution. Administering Presence Services XCP Controller August 2010 Chapter 14: Message Archiver The Message Archiver component stores all inbound and outbound messages to a Presence-supported database where they can be indexed and searched. It also logs file transfer requests, although it does not log the transferred files themselves. Shutting down the Message Archiver may require several minutes. This is especially true if there is a queue of messages waiting to be stored in the database. The Message Archiver attempts to ensure that all messages are written before the system shuts down. To determine whether it is still storing pending messages after you have shut it down, check to see if the archiver threads are still busy. If the threads are running, the Message Archiver is still working. Important: This chapter provides information about how to add and configure a message archiver component, and provide instructions to allow you to retrieve archived messages from the database. A message archiver component has been automatically pre-installed and configured with the Presence Server installation. So, you need not necessary have to follow the detailed procedure for adding or configuring the message archiver component but the information may be useful if you wish to customize the message archiver to your needs This Chapter consists of the following topics: • Configuring Message Archive on page 185 • Configuring the Presence Session Manager on page 186 • Retrieving Message Archiver Data on page 187 Configuring Message Archive To configure the Message Archiver component, you must use at least the Presence XCP Controller’s Intermediate configuration view. The Intermediate parameters are sufficient to configure an operational Message Archiver. The following instructions describe only the intermediate parameters that are specific to the Message Archiver component. For descriptions of all of the parameters associated with the component, see the online help provided in the Message Archiver Configuration page’s online help. To configure the Message Archiver Administering Presence Services XCP Controller August 2010 185 Message Archiver 1. Change to the Presence XCP Controller’s Intermediate configuration view. 2. In the Components area on the Presence XCP Controller’s main page, select Message Archiver in the list, and then click Go. 3. In the Message Archiver Configuration page under Log, select one or both Namespace(s). Message Archiver will log the messages associated with the namespace(s) that you choose. The jcs:mod_log:message:in namespace logs incoming messages and file transfer requests as they are received by the server. The jcs:mod_log:message:out namespace logs outgoing messages and file transfer requests as they are sent by the server. The Message Archiver ignores namespaces that are not selected here. Important: If you select both namespaces, each message and file transfer request will be logged twice, once as they are sent by the server and once as they are received by the server. 4. If you want the Message Archiver to log message packets from specific hosts only, enter their host names or IP addresses in the Host Filters field. The asterisk (*) is used to log message packets from every host. Note: Separate each host name or address with a line break. Host filters must be host names, or IPv4 or IPv6 addresses. If an IP address is used, the packet address must also use this IP address. 5. The Message Archiver requires a database; Oracle, PostgreSQL, or DB2. If you configured one of these databases when you installed the Presence Services server, you do not have to configure one here. However, if you want to use a different database for the Message Archiver, or if you selected SQLite during installation, select the Database Setup option, under the Message Archiver Configuration section and configure the parameters. Descriptions of the database parameters are provided in the Message Archiver Configuration page’s online help. 6. Click Submit to save your configuration. Configuring the Presence Session Manager In addition to configuring the Message Archiver component, you must configure the Presence Session Manager as described in this section. 186 Administering Presence Services XCP Controller August 2010 Retrieving Message Archiver Data To configure the Presence Session Manager 1. Make sure you are still using the Presence XCP Controller’s Intermediate configuration view. 2. In the Router area on the Presence XCP Controller’s main page, click Edit beside Presence Session Manager. 3. In the Presence Session Manager Configuration page, ensure that mod_message_archiver check box is cleared under Optional modules. The mod_message_archiver module is an independent archival mechanism that always logs messages to the local database when enabled. If the mod_message_archiver module is enabled while the message archiver component is also running (and configured to log to the local database) then both mechanisms will log messages to the local database. However, if the message archiver component is configured to log to a remote database then the mod_message_archiver module when enabled can be used to log to the local database. 4. Scroll down toward the bottom of the page, and select JSM Logging. 5. Select Yes for one or both types of message packets. The options you choose here must match the namespaces that you choose in the Message Archiver configuration (step 3 in the previous section). 6. Click Submit to save your configuration. 7. Restart your Presence XCP system. Retrieving Message Archiver Data The following command can be used at a terminal to access messages that have been archived to the local database (assuming that the default configuration has not been modified to archive the message to a different database). psql -U postgres -d xcp -c "select * from jm" Note: For a co-resident installation, use the following command: psql -U postgres -d xcp -c "select * from public.jm" Administering Presence Services XCP Controller August 2010 187 Message Archiver Note: The jm table is not purged automatically. The System Administrator needs to administer this table and perform backups or purges of the information as approapriate to ensure that the table does not grow without limit. A tool is provided to assist in this process - see Chapter 13:IM Database Management Tool The following information describes the fields used in the jm database table, this may be useful for forming SQL statements to retrieve specific conversations involving a particular user. This information details the following cases: • Incoming and Outgoing Messages • File Transfer Requests Important: In the tables below the message 'direction' field indicates whether a message is Incoming (I) or Outgoing (O). An Incoming message is a message on the path from the Presence Server to a particular client - the message is incoming from the client's perspective. An Outgoing message is a message on the path from a particular client to the Presence Server - the message is outgoing from the client's perspective. When the OCS Gateway is used to allow Jabber XMPP clients to communicate with Microsoft Office Communicator clients certain messages are not recorded by the message archiver component (or module). Assuming that both Incoming and Outgoing messages are configured to be recorded then the following messages will not be logged to the database: • For a message from a Microsoft Office Communicator client to a Jabber client the message on the path from the Microsoft Office Communicator client to the Presence Server is not logged, though the same message on the path from the Presence Server to the Jabber client is logged. That is the Outgoing message is not logged. • For a message from a Jabber client to a Microsoft Office Communicator client the message on the path from the Jabber client to the Presence Server is logged, but the message on the path from the Presence Server to the Microsoft Office Communicator client is not logged. That is the Incoming message is not logged. • However, all Incoming and Outgoing messages between two Jabber clients are logged to the database. Specifically, when a Jabber client sends a message to another Jabber client then both an Incoming and Outgoing entry should be logged to the database for the message in question. Related topics: Incoming and outgoing messages on page 188 Files transfer requests on page 189 Incoming and outgoing messages The following information pertaining to incoming and outgoing messages is stored in the JM table. 188 Administering Presence Services XCP Controller August 2010 Retrieving Message Archiver Data Column Description to_jid Stores the Jabber ID of the person who is receiving the message. This field cannot be left blank. from_jid Stores the Jabber ID of the person from whom the message was sent. This field cannot be left blank. subject Stores the subject line of the message, if available. thread_id Stores the thread ID of the message, if available. sent_date Stores the date on which the Presence server received the message. This field cannot be left blank. msg_type Stores the type of the message. C indicates that the message is a Chat, while G indicates that it is a Group message. Presence protocol supports additional message types. These types are indicated with an N for normal. direction Stores an indicator that tells where the message was generated. I indicates inbound messages, while O indicates outbound messages. body_len Stores the number of characters in the message’s body. The system uses this field to determine whether to store the text of the message in body_text or body_string. body_text If the length (body_len) is greater than 4000 characters, the text of the message body is stored in body_text. body_string If the length (body_len) is less than or equal to 4000, the text of the message body is stored in body_string. message_len The message fields store the entire XML packet of the message. Custom clients may include things that are not in the body’s text. This captures everything, even if it cannot be indexed. It stores the number of characters in the message. The system uses this field to determine whether to store the text of the message in message_text or message_string. message_text If the length (message_len) is greater than 4000 characters, the text of the entire message is stored in message_text. message_string If the length (message_len) is less than or equal to 4000, the text of the entire message is stored in message_string. Files transfer requests File transfer requests are also stored in the JM table with the following differences. Column subject Description Stores the URL of the message, if available. Administering Presence Services XCP Controller August 2010 189 Message Archiver Column Description thread_jid Stores the thread ID of the message, if available. sent_date Stores the date on which the Presence server received the message. This field cannot be left blank. body_len Stores the number of characters in the message body. The system uses this field to determine whether to store the text of the message in body_text or body_string. body_text If the length (body_len) is greater than 4000 characters, the text of the message is stored in body_text. body_string If the length (body_len) is less than or equal to 4000, the text of the message is stored in body_string. message_len The message fields store the entire XML packet of the message. Custom clients may include things that are not in the body’s text. This captures everything, even if it cannot be indexed. It stores the number of characters in the message. The system uses this field to determine whether to store the text of the message in message_text or message_string. message_text If the length (message_len) is greater than 4000 characters, the text of the message is stored in message_text. message_string If the length (message_len) is less than or equal to 4000, the text of the message is stored in message_string. Either body_text or body_string contains the message bodies, depending on the length of the messages. If the message body was greater than 4000 characters in length, it is stored in body_text; otherwise it is in body_string. Whichever of these two fields is not used is set to null. The entire message packet in raw form is stored in message_string or message_text field of the JM table. 190 Administering Presence Services XCP Controller August 2010 Chapter 15: OpenPort To get the OpenPort up and running, follow the instructions in Configuring the OpenPort . Then, if you want to fine tune your configuration, you can configure the parameters displayed in the Controller's Intermediate and Advanced configuration views. The OpenPort component allows you to configure a custom component or a component used for testing purposes. Configuring the OpenPort Perform the configuration described in this section first. This section provides instructions for getting the OpenPort component up and running quickly by configuring the parameters provided in the Controller's Basic configuration view. The parameters provided in the Basic view are sufficient to configure an operational component. 1. Change to the Controller's Basic configuration view. 2. Change the Description to something specific for this OpenPort. 3. Click Submit to save your configuration. Intermediate Configuration Parameters Configuration parameters that are provided in the Controller's Intermediate configuration view are described below in their respective sections. These parameters allow you to refine your configuration to some degree, and provide logging configuration capabilities. Default values have been provided for required parameters. Router Outbound Connection Information Select the Router Outbound Connection Information option only if you want to configure parameters that allow the router to connect to the component. For example, if the component is installed on a system that is running outside your firewall, this option allows the XCP router to connect to the component safely rather than introducing security risks by having the component connect to the router. (If you do not configure this option, the component will connect to the router using the Master Accept Port that is configured for the Core Router.) Administering Presence Services XCP Controller August 2010 191 OpenPort Component IP Enter the IP address or hostname of the system on which the component is installed. Port Enter the port that the component uses for communications. Password Enter the password that the router uses to authenticate the component. Execute an External Command This option is enabled by default, and allows the router to start the component. Disable the option if you prefer to start the component from a command line. Command line to run A command that runs the component automatically is provided by default. You can modify it if needed. Caution: Do not use the -B argument with this component. Since the PS logger is already a daemon process, its children must not be daemons. You should not redirect output, because all output to STDOUT and STDERR will be redirected to /dev/null. Hostnames for this Component Specify a host filter only if you want the component to be externally addressable; for example, if you want clients and other components or programs to communicate with it. This is because the mod_disco module in JSM uses host filters to return the component as something that should be discoverable. This option specifies the hosts for which the component will handle packets. Important: If you are configuring this open port for an S2SCP, you must specify a Host Filter so that packets destined for external domains reach the S2S component. In most cases, you should enter an asterisk (*) in the text box. Host Filters Enter the hostnames or IP addresses for which you want this component to handle packets. Separate each hostname or address with a line break. Enter an asterisk (*) in the textbox to enable the component to handle data from any host. Note: Host filters must be hostnames, or IPv4 or IPv6 addresses. If an IP address is used, the packet address must also use this IP address. 192 Administering Presence Services XCP Controller August 2010 Advanced Configuration Parameters Advanced Configuration Parameters Configuration parameters that are provided in the Controller's Advanced configuration view are described below in their respective sections. These parameters let you configure advanced settings such as runlevel, buffer sizes, thread counts, and custom loggers. They require a more advanced level of XCP server knowledge and can be used for fine tuning your XCP system. Runlevel The order in which this component shuts down. The runlevel must be an integer value greater than or equal to 0. (Component shutdown is executed in reverse order of the specified runlevel; components with the highest level (typically 70) shut down first.) Caution: Do not change the runlevel unless you know exactly what you are doing and understand the effects that changing it will have. The default runlevel is provided to help the system shut down as smoothly as possible, and is based on this component's dependencies upon other components. Timeout for Shutdown The number of seconds that the server waits to receive acknowledgement from the component that the shutdown process has completed. Note: If the component has not shut down by the time this time period has elapsed, the XCP core router leaves the process in its current state and continues shutting down other processes. Component Properties Select the Component Properties option if you want to configure the number of packets that are buffered when the component is down and whether to send error packets to stderr. Number of packets buffered when component is down Enter the number of packets bound for the component that should be buffered if the component goes down. Bounce error packets to stderr Select Yes if you want the router to send warnings to stderr when the component is down. Router Outbound Connection Information Buffer size in bytes for outgoing data Enter the number of bytes the router should buffer when it sends information to the component. You may want to modify this element when working on performance enhancements. Administering Presence Services XCP Controller August 2010 193 OpenPort Buffer size in bytes for incoming data Enter the number of bytes the router should buffer when it receives information from the component. You may want to modify this element when working on performance enhancements. Keep-alive interval in seconds Enter the number of seconds after which the router sends a keep-alive to the component. The keep-alive helps prevent firewalls from dropping an unused connection to the component. If this option is set to 0 or left empty, keep-alives are disabled. Log delivery of packets to this component Select Yes if you want the data that the router delivers to the component to be logged. The information is logged to the logger(s) you set up during IPS Logger configuration (syslog, file, or stderr). Socket-level logging happens only at the debug level. Execute an External Command Maximum interval in seconds to wait before restarting component Enter the maximum number of seconds after which the router tries to restart the component. If the component goes down, the router tries to restart it after 1 second. If the component is not running yet, the router multiplies the wait time by 1.5, and retires after the longer time. Once the maximum time interval that you specify in this field is reached, the router continues to retry after waiting this amount of time. Maximum number of times to restart component Enter the total number of restarts allowed. The default setting, -1, means unlimited. Note: If you want to be able to kill the component from the command line and prevent it from starting again automatically, you must set this number to something other than -1. For example, if you set it to 1, the component will not restart once you have killed it; if you set it to 2, the component will only restart once, and so on. Interval in seconds at which to reset this value to 1 second The number of seconds that the component has been up and running, after which to set the restart time back to 1 second. Path to Binary The directory path to the shell that launches the component. You can change the default setting if needed. XDB Select the XDB option if you want to set this component up to receive XDB packets. Namespace Filters 194 Enter an asterisk (*) to indicate that this XDB will handle the namespaces that are not handled by another XDB plugin. If you want the XDB to handle specific namespaces only, enter them Administering Presence Services XCP Controller August 2010 Advanced Configuration Parameters in the textbox separating each with a line break. All other namespaces will be ignored. Caution: You can specify an asterisk for only one XDB plugin. Host Filters Enter the hostnames for which you want this XDB instance to handle XDB packets. Separate each hostname with a line break. Enter an asterisk (*) in the textbox to enable this XDB instance to handle XDB packets from any host. Log Select the Log option if you want to set this component up to receive log packets. Namespace Filters Leave the namespaces for which you want data to be logged by this component. Remove those that you do not wish to use. Note: You can delete or modify any of the namespaces in the list, and you can add namespaces at the bottom of the list if needed. Host Filters Enter the hostnames for which you want this OpenPort component to handle packets. Separate each hostname with a line break. Enter an asterisk (*) in the textbox to enable the component to handle data from any host. OpenPort Configuration By default, the OpenPort configuration field contains an empty <config/> element in the openport namespace. Do not change the top-level configuration element. You can add any additional XML configuration for the open port; for example, a configuration for SNMP. When you add an element, the string "xmlns="http://www.jabber.com/config" is added inside the tag. Adding additional XML is helpful when you are creating an open port for a custom component that does not have a .jig or an .xsd file. Administering Presence Services XCP Controller August 2010 195 OpenPort 196 Administering Presence Services XCP Controller August 2010 Chapter 16: Presence Mirror The Presence Mirror component, which is installed with the “extras” installation package, stores a copy of all of the presence packets that the XCP server sends to IM users in your database. The server uses the Blind Carbon Copy feature to send presence packets to the database. Each packet includes the user’s JID, presence status, and a status message. In addition to configuring the Presence Mirror component, you must also configure some settings in the presence Session Manager. Note: To retrieve a user’s presence from the database, you must use your standard database tools. Configuring the Presence Mirror Component To configure the Presence Mirror component, you must use at least the controller’s Intermediate configuration view. The Intermediate parameters are sufficient to configure an operational Presence Mirror. The following instructions describe only the intermediate parameters that are specific to the Presence Mirror component. For descriptions of all of the parameters associated with the component, see Presence Mirror Parameter Reference . Related topics: To configure the Presence Mirror on page 197 To configure the Presence Mirror 1. Change to the controller’s Intermediate configuration view. 2. In the Components area on the controller’s main page, select Presence Mirror in the list, and then click Go . 3. Write down the Presence Mirror component’s ID and keep it near by. You will need to use the ID when you configure the Presence Session Manager to use the Presence Mirror. 4. The Presence Mirror requires a database —Oracle, PostgreSQL, or DB2. If you configured one of these databases when you installed the Presence XCP server, you do not have to configure one here. However, if you want to use a different Administering Presence Services XCP Controller August 2010 197 Presence Mirror database for the Presence Mirror, or if you selected SQLite during installation, select the Database Setup option and configure the parameters. Descriptions of the database parameters are provided in the Database Setup section in the “ Intermediate Parameters” table provided in Presence Mirror Parameter Reference . 5. Click Submit to save your configuration. Configuring the Presence Session Manager In addition to configuring the Presence Mirror, you must configure the Presence Session Manager as described in this section. Related topics: To configure the Presence Session Manager on page 198 To configure the Presence Session Manager 1. Make sure you are still in the controller’s Intermediate configuration view. 2. In the Router area on the controller’s main page, click Edit beside Presence Session Manager . 3. In the Presence Session Manager Configuration page under Optional Modules , select mod_presence_bcc . This module sends presence packets to the Presence Mirror so that it can store them in the database using the Blind Carbon Copy (BCC) feature. 4. Scroll down toward the bottom of the page, and select Mirroring Presence . 5. Enter the ID of the Presence Mirror component. For example: presence-mirror-1.presence 6. Click Submit to save your configuration. 7. Restart your XCP system. 198 Administering Presence Services XCP Controller August 2010 Presence Mirror Parameter Reference Presence Mirror Parameter Reference This section describes the parameters associated with the Presence Mirror component. The parameters are divided into subsections based on the configuration view in which they display. Related topics: Intermediate Parameters on page 199 Advanced Parameters on page 201 Intermediate Parameters The following table describes the parameters that are displayed in the controller’s Intermediate configuration view. These parameters are sufficient to configure an operational Presence Mirror component. Parameter Description Description The description is displayed in the Components area on the controller’s main page and should help you distinguish between components of the same type when you have more than one configured. You can change the description as needed. Router Outbound Connection Information Select this option only if you want the XCP router to connect to the component. For example, if the component is running outside your firewall, this option allows the router to connect to the component safely rather than introducing security risks by letting the component connect to it. By default, components connect to the router using the router’s Master Accept Port. Component IP Enter the IP address or host name of the system on which the component is installed. Port Enter the port that the component uses for communications. Password Enter the password that the router uses to authenticate the component. Execute an External Command This option allows the router to start the component automatically. If you prefer to start the component from a command line, disable this option. Command line to run A command that runs the component automatically is provided by default. You can modify it if needed. Administering Presence Services XCP Controller August 2010 199 Presence Mirror Parameter Description Note: Do not use the -B argument with this component. Since the IPS logger is already a daemon process, its children must not be daemons. You should not redirect output, because all output to STDOUT and STDERR will be redirected to /dev/null. Hostnames for this Component This option specifies the hosts for which this component will handle packets. Specify a host filter only if you want the component to be externally addressable; for example, if you want clients and other components or programs to communicate with it. This is because the mod_disco module in JSM uses host filters to return the component as something that should be discoverable. Host Filters Enter the host names or IP addresses for which you want this component to handle packets. Separate each host name or address with a line break. Host filters must be host names, or IPv4 or IPv6 addresses. If you use an IP address, the packet address must also use this IP address. Database Setup Select this option if you want to configure a database that is different from the one configured for the core router in the Global Settings Configuration page. Datasource Name For the PostgreSQL database, this is the name of the component’s datasource as specified in the .odbc.ini file. For Oracle, the datasource is specified in the ORACLE_SID environment variable or in the tsnames.ora file. For DB2, this is typically the database alias. Database User Name Enter the username used to connect to the database. Database User’s Password Enter the password used to connect to the database. Confirm Password Enter the password again to confirm it. Database Type Select the type of database you are using from the list. If you select postgresql-odbc, you must add the line, “ MaxVarcharSize=4000” to the datasource definition used in the .odbc.ini file. Number of Enter the number of connections that you want the component to use connections to the for processing requests. database Time in seconds Enter the number of seconds after which the database connection between database should refresh. Do not set this value to zero without contacting connection technical support. heartbeats Component Logging (Jlog) 200 Administering Presence Services XCP Controller August 2010 Presence Mirror Parameter Reference Parameter Description Select the Component Logging (Jlog) option only if you want to configure filtered level loggers that log messages to syslog and to a stream (stderr or stdout). You can enable either or both the syslog and stream loggers. These parameters are displayed in the controller’s Intermediate and Advanced configuration views. SNMP Configuration Select this option if you want to configure SNMP for the component. Enable SNMP Leave this parameter set to Yes. Advanced Parameters The following table describes the parameters that are displayed in the controller’s Advanced configuration view. Advanced parameters are used for adjusting the performance of the XCP system. We recommend that you call technical Support if you need to change these parameter settings. Parameter Description Runlevel Enter the order in which this component shuts down. The runlevel must be an integer value greater than or equal to zero. Component shutdown is executed in reverse order of the specified runlevel; components with the highest level (typically 70) shut down first. Do not change the runlevel unless you know exactly what you are doing and understand the effects that changing it will have. The default runlevel is provided to help the system shut down as smoothly as possible, and is based on this component’s dependencies upon other components. Timeout for shutdown Enter the number of seconds that the server waits to receive acknowledgement from the component that the shutdown process has completed. If the component has not shut down by the time this time period has elapsed, the router leaves the process in its current state and continues shutting down other processes. Component Properties Number of Enter the number of packets bound for the component that should be packets buffered buffered if the component goes down. when component is down Bounce error packets to stderr Select Yes if you want the router to send warnings to stderr when the component is down. Router Outbound Connection Information Administering Presence Services XCP Controller August 2010 201 Presence Mirror Parameter Description Buffer size in Enter the number of bytes the router should buffer when it sends bytes for outgoing information to the component. You may want to modify this element data when working on performance enhancements. Buffer size in bytes for incoming data Enter the number of bytes the router should buffer when it receives information from the component. You may want to modify this element when working on performance enhancements. Send keepalives Select Yes if you want the router to send keep-alives to the component. The keep-alive helps prevent firewalls from dropping an unused connection to the component. If this option is set to No, keep-alives are disabled. Log the delivery of packets to this component Select Yes if you want to log the data that the router delivers to the component. The information is logged to the logger(s) you set up during IPS Logger configuration (syslog, file, or stderr). Socket-level logging happens only at the debug level. Execute an External Command Maximum interval in seconds to wait before restarting component Enter the maximum number of seconds after which the router tries to restart the component. If the component goes down, the router tries to restart it after one second. If the component does not start, the router multiplies the wait time by 1.5, and tries again. Once the maximum time interval that you specify for this parameter is reached, the router continues to retry after waiting this amount of time. Maximum number of times to restart component Enter the total number of restarts allowed. The default setting, -1, means unlimited. Interval in Enter the number of seconds that the component has been up and seconds at which running, after which to set the restart time back to one second. to reset this value to 1 second Path to binary Enter the directory path to the shell that launches the component. You can change the default setting if needed. Database Setup Is database debug logging enabled? Select ’1’ to log database debug information. Database logging uses the XCP router’s logging facility, the IPC Logger. The log level must be set to debug for database logging to occur. Component Logging (Jlog) Add a new custom logger If you have created a custom logger for logging component information using the libjcore library, click Go to access the Custom Logger Configuration page. SNMP Configuration 202 Administering Presence Services XCP Controller August 2010 Presence Mirror Parameter Reference Parameter Count errors Description Select Yes only if you want to enable SNMP error counting. This option takes a great deal of server resource, so use it with caution. Administering Presence Services XCP Controller August 2010 203 Presence Mirror 204 Administering Presence Services XCP Controller August 2010 Chapter 17: Presence Configuration Reference This section provides a reference for all of the parameters associated with the Presence component. The parameters are divided into subsections based on the configuration view in which they display. Basic Parameters The following table describes the parameters that display in the controller’s Basic configuration view. The basic parameters are sufficient to configure an operational Presence component. Parameter Description Description The description is displayed in the Components area on the controller’s main page and should help you distinguish between components of the same type when you have more than one configured. You can change the description as needed. Metrics File (full path) The full path to a file to which the IPS Publisher will write metrics values pertaining to the operational activity within the server Metrics enabled Boolean indicator to turn on or off metrics reporting Metrics Reporting Interval The time interval, in seconds, at which metrics reporting will take place Default AES Username The default username used when logging into an AES. This field must be filled in. When the IPS connects to an AES to monitor an extension it will use this username unless an Override by AES item has been created for the AES, in which case the username supplied on the Override By AES page will be used. Default AES Password The default password used when logging into an AES. This field must be filled in. When the IPS connects to an AES to monitor an extension it will use this password unless an Override by AES item has been created for the AES, in which case the password supplied on the Override By AES page will be used. User Name The User Name used by the RTC Collector when subscribing to Microsoft Office Clients SIP Domain The SIP Domain used by the RTC Collector when subscribing to Microsoft Office Clients Administering Presence Services XCP Controller August 2010 205 Presence Configuration Reference Parameter Description Transport Transport (TCP or TLS) used by the RTC collector Port Port the RTC Collector listens on for Notifications Expires Expires value for a Subscription from the RTC Collector Subscription Failure Retry The time to wait before attempting another subsription to a Microsoft client when the previous subscription failed Server Failure Retry The period used by the RTC Collector to check failed connections to the Enterprise domain (Domain of the MOC clients) SES Transport Transport (TCP or TLS) used by the SES collector SES Port This is the port the SES collector listens on for communications WS Host Hostname on which the UMS server is running WS Port Port number for UMS WS Service The service name URL for the UMS JMS Host JMS broker hostname JMS Port JMS broker port Login Login user id for UMS service Password Login password for UMS service Secure connection Boolean indicator to enable or disable secure (TLS) communications Page Size The number of records in a response message. Resync interval(seconds) Time period for which the UMC will perform a resync to the UMS Retry interval(seconds) UMC connection retry period to UMS Intermediate Parameters The following table describes the parameters that display in the Presence component’s Intermediate configuration view. Parameter Description Router Outbound Connection Information Select this option only if you want the XCP router to connect to the component. For example, if the component is running outside your firewall, this option allows the router to connect to the component safely rather than introducing security risks by letting the component connect to it. By default, components connect to the router using the router’s Master Accept Port. 206 Administering Presence Services XCP Controller August 2010 Advanced Parameters Parameter Description Buffer size in bytes for outgoing data Enter the number of bytes the router should buffer when it sends information to the component. You may want to modify this element when working on performance enhancements. Buffer size in bytes for incoming data Enter the number of bytes the router should buffer when it receives information from the component. You may want to modify this element when working on performance enhancements. Component IP Enter the IP address or host name of the system on which the component is installed. Port Enter the port that the component uses for communications. Password Enter the password that the router uses to authenticate the component. Execute an External Command This option allows the router to start the component automatically. If you prefer to start the component from a command line, disable this option. Command line to run A command that runs the component automatically is provided by default. You can modify it if needed. Note: Do not use the -B argument with this component. Since the IPS logger is already a daemon process, its children must not be daemons. You should not redirect output, because all output to STDOUT and STDERR will be redirected to /dev/null. Hostnames for this Component This option specifies the hosts for which this component will handle packets. Specify a host filter only if you want the component to be externally addressable; for example, if you want clients and other components or programs to communicate with it. This is because the mod_disco module in JSM uses host filters to return the component as something that should be discoverable. Host Filters Enter the host names or IP addresses for which you want this component to handle packets. Separate each host name or address with a line break. Host filters must be host names, or IPv4 or IPv6 addresses. If you use an IP address, the packet address must also use this IP address. Advanced Parameters The following table describes the parameters that are displayed in the Presence component’s Advanced configuration view. Most of the advanced parameters are used for adjusting the Presence server’s performance. Default values have been provided for these parameters, and Administering Presence Services XCP Controller August 2010 207 Presence Configuration Reference in most cases, these values are sufficient. We recommend contacting technical Support if you want to change the values. Parameter Description Runlevel Enter the order in which this component shuts down. The runlevel must be an integer value greater than or equal to 0. Component shutdown is executed in reverse order of the specified runlevel; components with the highest level (typically 70) shut down first. Do not change the runlevel unless you know exactly what you are doing and understand the effects that changing it will have. The default runlevel is provided to help the system shut down as smoothly as possible, and is based on this component's dependencies upon other components. Timeout for shutdown Enter the number of seconds that the server waits to receive acknowledgement from the component that the shutdown process has completed. If the component has not shut down by the time this time period has elapsed, the router leaves the process in its current state and continues shutting down other processes. Number of packets buffered when component is down Enter the number of packets bound for the component that should be buffered if the component goes down. Bounce error packets Select Yes if you want the router to send warnings to stderr when to stderr the component is down. Presence Components 208 Publish DND Status DND or Do Not Disturb feature (the feature button on CM is called SendAllCalls) can be configured for extensions on the Avaya Communication Manager. If an extension is configured so that it has the use of the feature 'SendAllCalls' it may toggle the 'SendAllCalls' button to turn on and off DND status. If 'Publish DND status' is set to 'No' then no DND information will be published in the phone tuple by IPS for any extension regardless of whether 'SendAllCalls' is on or off. If 'Publish DND status' is set to 'Yes' and if 'SendAllCalls' is set to 'on' for an extension IPS will publish the DND activity element and the basic status would be set to 'closed' for that extension. You need AES = 4.1 and CM = 5.0 to guarantee DND updates from AES. Deployments with versions of AES or CM earlier than this should leave 'Publish DND Status' set to the default 'No'. If a deployment with earlier versions of either AES or CM has 'Publish DND status' set to 'Yes' then what may happen is IPS might for example get an initial DND status of 'on' for an extension, publish this information and set the basic status for it to 'closed'. Now if a user updates the 'SendAllCalls' and sets it to 'off' IPS will not be updated and continue to publish DND as on and a basic status of 'closed' Default TSAPI.PRO File Name of an optional text file for configuring Avaya’s JTAPI library. If the name of a file is supplied here, it will apply by default to all IPS Administering Presence Services XCP Controller August 2010 Advanced Parameters Parameter Description to AES connections. Note that a TSAPI.PRO-like file specified in these pages differs from the traditional TSAPI.PRO file in the following respects: It does not need to be called “TSAPI.PRO”, it can be located anywhere in the local file system, and, though lines of the form “<AES IP address>=450” can be entered into it, they will be ignored. Otherwise, Avaya’s JTAPI library will handle the file just as it handles the traditional TSAPI.PRO file. A separate TSAPI.PRO-like file can be configured, or not, for each IPS to AES connection. To use this feature, create an Override by Tlink item and fill in, or don’t, the “TSAPI.PRO file” item on that page. The “TSAPI.PRO file” setting on the override page will determine whether the connection identified by the tlink uses a TSAPI.PROlike file and, if it does, what the file’s name is. The “Default TSAPI.PRO file” setting on this page will apply to those connections for which a tlink override has not been created. Note that these pages do not help you create or maintain TSAPI.PRO-like files. Static Routes If needed static routes can be added for the RTC Collector. Each static route should be added on its own line. Static routes take the form "Domain Next-Hop Next-Hop-Port" so an example would be "mydomain.com destmachine 5061" or an IP address may be used as a Next-Hop "mydomain.com 10.0.0.100 5071" Administering Presence Services XCP Controller August 2010 209 Presence Configuration Reference 210 Administering Presence Services XCP Controller August 2010 Chapter 18: Intra-Domain (Clustered) federation using Single Domain Name Support Clustered federation using Single Domain Name Support (SDNS) This chapter provides instructions for configuring intra-domain federation for a clustered environment using the Single Domain Name Support (SDNS) component. In an intra-domain federated cluster a number of PS instances inter-connect to provide Presence and Instant Messaging services for a single JID domain (for example, example.com). In an intra-domain setup each PS instance should be installed with a unique 'Router Realm' (for example, presence1, presence2, etc), while the 'Router Service Name' should be common across all instances (for example, example.com). The 'Router Service Name' determines the JID domain that is used by the users when logging on, for example, [email protected]. This Chapter consists of the following topics: • Overview on page 0 • Configuring SDNS for Intra-Domain (Clustered) Federation Overview Single Domain Name Support (SDNS) provides a method for distributing the load for a single domain over multiple, equivalent components (for example, multiple JSM components). The SDNS component accomplishes this by allowing you to deploy a single domain name across a network of Presence XCP routers and components on different computers. SDNS allows two components with equivalent capabilities to act side by side, thereby reducing performance bottlenecks and increasing the number of concurrent users that are supported on each system. SDNS is thus useful for customers with demanding scalability requirements. SDNS allows a number of PS instances to service a single user domain. The users may connect to any server in the cluster (by specifying its FQDN or IP address) with a modulo hashing algorithm then being used to home the user to a specific instance. Due to the nature of the modulo algorithm the user is always homed on the same server in the cluster independent of which server they connect to. It may also be useful to set up DNS SRV records so that the client does not need to specify the host to connect to (this option is only applicable if the use of automatic host and port Administering Presence Services XCP Controller August 2010 211 Intra-Domain (Clustered) federation using Single Domain Name Support discovery is supported by One-X agent.). See Configuring DNS SRV records for XMPP Clients to perform load balancing in Appendix A for details on how to do this. The following gives an example of a cluster containing 2 servers (chat1.example.com and chat2.example.com), where the domain of the users is example.com and the SRV records have equal weighting (i.e. 50/50) to perform load balancing of the client connections: _xmpp-client._tcp.example.com has SRV record 0 50 5222 chat1.example.com. _xmpp-client._tcp.example.com has SRV record 0 50 5222 chat2.example.com. Configuring SDNS for Intra-Domain (Clustered) Federation Configuring JSM In order to work correctly with SDNS, the Presence Session Manager configurations on all routers must not contain any host names. The host name that would ordinarily be entered in the JSM configuration is, instead, entered in the SDNS configuration. The following steps need to be performed for all PS instances in the cluster. To configure the JSM plug-ins 1. In the Router area on the Presence XCP Controller’s main page, click Edit beside Presence Session Manager. The Presence Session Manager Configuration page is displayed. 2. In the Presence Session Manager Configuration page, scroll down to the Hostnames for this Component area and remove the host name. 3. Scroll down to the JSM Features area, and select Yes beside Apply Single Domain Name Support semantics to local user lookups. 4. Click Submit to save your configuration. 5. Repeat this procedure for the JSM on all the other routers i.e. PS instances. Configuring SDNS for JSM You must configure an SDNS component on each router. Here the SDNS components are configured using the modulo mapping algorithm. 212 Administering Presence Services XCP Controller August 2010 Configuring SDNS for Intra-Domain (Clustered) Federation To configure SDNS components for JSM 1. In the Components area of the Presence XCP Controller’s main page, select Single Domain Name Support from the list, and click Go. 2. Ensure that the Advanced view is selected. In the Single Domain Name Support Configuration page, scroll down to the Hostnames for this Component area. Enter the JSM host name (for example, the JID domain of your users); for example; example.com. 3. Scroll down to the Single Domain Name Support Configuration area, and select the Database Mapping Algorithm option. Note: The id.realms must be entered in the same order in each cooperating SDNS component’s configuration. 4. Click Submit to save your configuration. 5. Repeat this procedure for the SDNS component on the other routers, i.e. PS instances. Configuring an R2R connection Finally, you need to add Router-to-Router (R2R) connections to inter-connect the PS instances. If there are two PS instances in the cluster then you only need to add a Router-toRouter (R2R) Connection on one of the PS instances - in this case you must configure a Routerto-Router (R2R) Connection on the router that you want to make the outbound connection. For the case where there are n PS instances in the cluster you will need to add n-1 Router-toRouter (R2R) Connections to inter-connect all PS instances. Below we configure a single Router-to-Router (R2R) Connection on the server with the presence1 realm to connect to the server with the presence2 realm. To configure the Router-to-Router Connection on the “presence1” router 1. Change to the Presence XCP Controller’s Advanced configuration view. 2. In the Components area on the Presence XCP Controller’s main page, select Router-to-Router Connection in the list, and then click Go. The Router-to-Router Connection Configuration page is displayed. 3. In the Router-to-Router Connection Configuration page, configure the following parameters. Administering Presence Services XCP Controller August 2010 213 Intra-Domain (Clustered) federation using Single Domain Name Support Parameter Description Component IP Enter the presence2 router’s IP address. Port Enter the port specified for the presence2 router’s Master Accept Port. Password Enter the password specified for the presence2 router’s Master Accept Port. Connection Weight Enter a small integer, such as 1. 4. Click Submit to save your configuration. 214 Administering Presence Services XCP Controller August 2010 Chapter 19: Kerberos authentication and Microsoft Active Directory This chapter provides instructions for configuring the Presence Services server to use Kerberos authentication with Microsoft Active Directory. Important: For Kerberos authentication to succeed, reasonable clock synchronization between the Active Directory Server, the Presence Services server and the client machines is critical due to the checking that is performed on kerberos ticket timestamps. This can achieved by synchronizing all machines against an NTP server. This Chapter consists of the following topics: • Active Directory setup on page 215 • Configuring Kerberos for the Presence Services Server on page 215 Active Directory setup Presence XCP users must be set up in Active Directory as follows: • All Presence XCP users must have a user entry in Active Directory. • All Presence XCP users must be in the same Active Directory forest, and none of the users can be the Active Directory forest root domain. Configuring Kerberos for the Presence Services Server To configure Kerberos authentication Note: In the steps below we assume the following environment for illustration purposes: FQDN of Presence Server services: chat.example.com ROUTER_SERVICE_NAME (that is JID domain): example.com Administering Presence Services XCP Controller August 2010 215 Kerberos authentication and Microsoft Active Directory Active Directory Realm: CORP.EXAMPLE.COM User created in Active Directory: psuser (with password=mypassword) 1. Create an Active Directory user for the Presence Services server. Keep the account options as simple as possible. Make sure that the user’s password does not expire and that the user is not forced to change it the next time user logs in. 2. On the Active Directory server, use the KTPASS utility to generate a keytab for the Presence XCP user as follows: ktpass -princ xmpp/FQDN_of_PS@AD_REALM -pass XCP_PASSWORD out krb5.keytab -mapuser XCP_USERNAME -ptype KRB5_NT_PRINCIPAL Example ktpass -princ xmpp/[email protected] -pass mypassword -out krb5.keytab -mapuser psuser -ptype KRB5_NT_PRINCIPAL To use the ktpass command, you must first download and install Windows Server 2003 R2 support tools (or download a version that matches your server) from the Microsoft web site. The ktpass command is set in the path after installation. You can run the ktpass command from the DOS prompt. The variables are described in the following table. Variable Description FQDN_of_PS The FQDN of the Presence Services server, e.g. chat.example.com. AD_REALM The Windows realm that your Active Directory server supports. The realm should be specified in Uppercase and not lowercase. XCP_PASSWORD The password for the user you created in step 1. XCP_USERNAME The user you created in step 1. 3. Move the generated keytab file to the Presence Services server in the following locations: For Linux installations, /etc/krb5.keytab 4. On the Presence Services server create the Kerberos configuration file as shown below. [libdefaults] default_realm = AD_REALM rnds = false [domain_realm] FQDN_of_PS = AD_REALM 216 Administering Presence Services XCP Controller August 2010 Configuring Kerberos for the Presence Services Server For example: [libdefaults] default_realm = CORP.EXAMPLE.COM rnds = false [domain_realm] chat.example.com = CORP.EXAMPLE.COM Note: For Linux installations, save the file as /etc/krb5.conf. 5. On the Presence Services server create the xmpp.conf file containing the following line: mech_list: gssapi Note: For Linux installations, save the file in $JABBER_HOME/lib/sasl2. 6. Change to the Presence XCP Controller’s Advanced configuration view. 7. In the Router area on the Presence XCP Controller’s main page, click Edit beside the Presence Session Manager. 8. In the Presence Session Manager Configuration page, scroll down to the Hostnames for this Component area, and make sure that the name specified in the Host Filters field matches the JID domain (for example, example.com). 9. Click Submit (or Cancel if you made no changes) to return to the Presence XCP Controller’s main page. 10. In the Components area on the Presence XCP Controller’s main page, click Edit beside the first Connection Manager. 11. In the Connection Manager Configuration page under Add a New Command Processor, click Details to edit the JSM Command Processor. 12. In the JSM Command Processor Configuration page under Director Configuration, click Details beside the first XMPP director. 13. Scroll to the bottom of the XMPP Director Configuration page, and select SASL Settings. Specify the AD_REALM from the krb5.conf file in the SASL Realm field. The SASL realm must be entered using uppercase characters. 14. Click Submit to save the director’s configuration. You are returned to the JSM Command Processor Configuration page. 15. Under Director Configuration, click Details beside the second XMPP director, and repeat the previous two steps. 16. Click Submit on each configuration page until you have returned to the Presence XCP Controller’s main page. Administering Presence Services XCP Controller August 2010 217 Kerberos authentication and Microsoft Active Directory Note: If you have added an additional Communication Manager component to handle additional XMPP client connections as detailed in Connection managers on page 137 then you should repeat steps 10-16 for this additional Communication Manager. 17. Restart the Presence XCP system. 218 Administering Presence Services XCP Controller August 2010 Chapter 17: Services Stanza Optimizer The Stanza Optimizer component implements Extended Stanza Addressing, which is described in XEP-0033 . You can configure the Stanza Optimizer component to work in conjunction with the InfoBroker and Text Conferencing components in order to optimize stanza traffic between XCP servers, thus providing a higher degree of scalability for large numbers of users. This feature allows a single stanza to be sent to multiple recipients rather than separate stanzas being sent to each recipient. Extended stanza addressing is used when packets are being sent to remote domains. However, it is not used when all communication is occurring within the same domain, although multiple stanza optimizers within a domain can split up the packets that are being sent. For example, if four XCP servers are running in the same domain, each configured with a Stanza Optimizer component, and the InfoBroker component sends 1000 packets, each router will then handle 250 packets. The following figure illustrates a XCP system in which four routers share the same cluster. A Stanza Optimizer component has been configured on each router. When the InfoBroker service delivers a stanza to 2000 subscribers, the stanza traffic is distributed evenly between all or the Stanza Optimizer components and then between the XCP routers. Related topics: Configuring the Stanza Optimizer Component on page 219 Configuring Text Conferencing for Stanza Optimization on page 221 Configuring the InfoBroker for Stanza Optimization on page 221 Stanza Optimizer Parameter Reference on page 222 Configuring the Stanza Optimizer Component The Stanza Optimizer component’s configuration parameters display in the controller’s Advanced configuration view. The following instructions describe how to configure only the parameters that are specific to the Stanza Optimizer. For descriptions of all of the parameters, see Stanza Optimizer Parameter Reference. You must configure a Stanza Optimizer component for each of your XCP routers if you want to extend XMPP stanzas to multiple recipients. Administering Presence Services XCP Controller August 2010 219 Services Related topics: To configure the Stanza Optimizer component on page 220 To configure the Stanza Optimizer component 1. Change to the controller’s Advanced configuration view. 2. In the Components area on the controller’s main page, select Stanza Optimizer in the list, and click Go . 3. On the Stanza Optimizer Configuration page, scroll down to the Stanza Optimizer Configuration area, and configure the following parameters. Parameter Description Number of threads to dedicate to stanza optimizer tasks Enter the number of threads that you want to have processing tasks in the component. Increasing this value enables the component to handle more tasks at a time. However, it spends more time scheduling the tasks as this number increases. We recommend that you set this number to one more than the number of processors on your system. Timeout (in seconds) for XEP-033 disco attempts Enter the number of seconds to wait for the server to determine if non-local domains can handle stanza optimization. If a non-local domain cannot handle stanza optimization, one packet is sent per recipient. Disco Cache Timeout (in minutes) Enter the number of minutes that a discovery answer (positive or negative) should exist. The maximum number of minutes that you can specify is 1440 (24 hours). Multiple optimizer address threshold This parameter is to be used mainly for fine tuning your system. In most cases, the default value should be sufficient. The threshold refers to the number of recipients who are located in a remote domain. The value is the maximum number of recipients required for extended stanza addressing to take effect. List of local domains Enter the list of local domains. The Stanza Optimizer dynamically determines which domains are local, but you can enter them here to short circuit this discovery process. The Stanza Optimizer does not send optimized packets to local domains. 4. Click Submit to save your configuration. 220 Administering Presence Services XCP Controller August 2010 Stanza Optimizer Configuring Text Conferencing for Stanza Optimization If you want to extend the XMPP stanzas to multiple recipients in a conference room, you must enable the Stanza Optimizer option in the Text Conferencing component. Related topics: To enable the Stanza Optimizer option on page 221 To enable the Stanza Optimizer option 1. Change to the controller’s Advanced configuration view. 2. In the Components area on the controllers’ main page, click Edit beside Text Conferencing . 3. In the Text Conferencing Configuration page, scroll down to the TC Configuration section, and select Enable stanza optimizer support (XEP-033) . 4. For Number of room members to trigger an extended address stanza , enter the minimum number of room members. 5. Use the default value for Multiple optimizer address threshold . This parameter is intended only for advanced system tuning, and in most cases, the default value should not be changed. 6. Click Submit to save your configuration. 7. Restart your XCP system. Configuring the InfoBroker for Stanza Optimization If you want to extend the XMPP stanzas to multiple subscribers of an InfoBroker service, you must enable the Stanza Optimizer option in the InfoBroker component. Related topics: To enable the Stanza Optimizer option on page 222 Administering Presence Services XCP Controller August 2010 221 Services To enable the Stanza Optimizer option 1. Change to the controller’s Advanced configuration view. 2. In the Components area on the controllers’ main page, click Edit beside InfoBroker . 3. In the InfoBroker Configuration page, scroll down to the InfoBroker Configuration section, and select Enable stanza optimizer support (XEP-033) . 4. For Number of publish recipients to trigger an extended address stanza , enter the minimum number of InfoBroker subscribers. 5. Use the default value for Multiple optimizer address threshold . This parameter is intended only for advanced system tuning, and in most cases, the default value should not be changed. 6. Click Submit to save your configuration. 7. Restart your XCP system. Stanza Optimizer Parameter Reference This section describes the parameters associated with the Stanza Optimizer component. The Stanza Optimizer parameters are available only in the controller’s Advanced configuration view. Parameter 222 Description Description The description is displayed in the Components area on the controller’s main page and should help you distinguish between components of the same type when you have more than one configured. You can change the description as needed. Runlevel Enter the order in which this component shuts down. The runlevel must be an integer value greater than or equal to zero. Component shutdown is executed in reverse order of the specified runlevel; components with the highest level (typically 70) shut down first. Do not change the runlevel unless you know exactly what you are doing and understand the effects that changing it will have. The default runlevel is provided to help the system shut down as smoothly as possible, and is based on this component’s dependencies upon other components. Administering Presence Services XCP Controller August 2010 Stanza Optimizer Parameter Timeout for shutdown Description Enter the number of seconds that the server waits to receive acknowledgement from the component that the shutdown process has completed. If the component has not shut down by the time this time period has elapsed, the router leaves the process in its current state and continues shutting down other processes. Component Properties Number of Enter the number of packets bound for the component that should be packets buffered buffered if the component goes down. when component is down Bounce error packets to stderr Select Yes if you want the router to send warnings to stderr when the component is down. Router Outbound Connection Information Select this option only if you want the XCP router to connect to the component. For example, if the component is running outside your firewall, this option allows the router to connect to the component safely rather than introducing security risks by letting the component connect to it. By default, components connect to the router using the router’s Master Accept Port. Component IP Enter the IP address or host name of the system on which the component is installed. Port Enter the port that the component uses for communications. Password Enter the password that the router uses to authenticate the component. Buffer size in Enter the number of bytes the router should buffer when it sends bytes for outgoing information to the component. You may want to modify this element data when working on performance enhancements. Buffer size in bytes for incoming data Enter the number of bytes the router should buffer when it receives information from the component. You may want to modify this element when working on performance enhancements. Send keepalives Select Yes if you want the router to send keep-alives to the component. The keep-alive helps prevent firewalls from dropping an unused connection to the component. If this option is set to No, keep-alives are disabled. Log the delivery of packets to this component Select Yes if you want to log the data that the router delivers to the component. The information is logged to the logger(s) you set up during Jabberd Logger configuration (syslog, file, or stderr). Socket-level logging happens only at the debug level. Execute an External Command This option allows the router to start the component automatically. If you prefer to start the component from a command line, disable this option. Maximum interval Enter the maximum number of seconds after which the router tries to in seconds to wait restart the component. If the component goes down, the router tries to restart it after one second. If the component does not start, the router Administering Presence Services XCP Controller August 2010 223 Services Parameter Description before restarting component multiplies the wait time by 1.5, and tries again. Once the maximum time interval that you specify for this parameter is reached, the router continues to retry after waiting this amount of time. Maximum number of times to restart component Enter the total number of restarts allowed. The default setting, -1, means unlimited. Interval in Enter the number of seconds that the component has been up and seconds at which running, after which to set the restart time back to one second. to reset this value to 1 second Path to binary Enter the directory path to the shell that launches the component. You can change the default setting if needed. Command line to run A command that runs the component automatically is provided by default. You can modify it if needed. Note: Do not use the -B argument with this component. Since jabberd is already a daemon process, its children must not be daemons. You should not redirect output, because all output to STDOUT and STDERR will be redirected to /dev/null. Hostnames for this Component This option specifies the hosts for which this component will handle packets. Specify a host filter only if you want the component to be externally addressable; for example, if you want clients and other components or programs to communicate with it. This is because the mod_disco module in JSM uses host filters to return the component as something that should be discoverable. Host Filters By default, the XCP server’s host name prepended by ”stanzaoptimizer” is provided. Enter the host names or IP addresses for which you want this component to handle packets. Separate each host name or address with a line break. Host filters must be host names, or IPv4 or IPv6 addresses. If you use an IP address, the packet address must also use this IP address. Stanza Optimizer Configuration 224 Number of threads to dedicate to stanza optimizer tasks Enter the number of threads that you want to have processing tasks in the component. Increasing this value enables the component to handle more tasks at a time. However, it spends more time scheduling the tasks as this number increases. We recommend that you set this number to one more than the number of processors on your system. Timeout (in seconds) for Enter the number of seconds to wait for the server to determine if nonlocal domains can handle stanza optimization. If a non-local domain cannot handle stanza optimization, one packet is sent per recipient. Administering Presence Services XCP Controller August 2010 Stanza Optimizer Parameter Description XEP-033 disco attempts Disco Cache Timeout (in minutes) Enter the number of minutes that a discovery answer (positive or negative) should exist. The maximum number of minutes that you can specify is 1440 (24 hours). Multiple optimizer This parameter is to be used mainly for fine tuning your system. In most address cases, the default value should be sufficient. threshold The threshold refers to the number of recipients who are located in a remote domain. The value is the maximum number of recipients required for extended stanza addressing to take effect. List of local domains Enter the list of local domains. The Stanza Optimizer dynamically determines which domains are local, but you can enter them here to short circuit this discovery process. The Stanza Optimizer does not send optimized packets to local domains. Database Setup Datasource Name For the PostgreSQL database, this is the name of the component’s datasource as specified in the .odbc.ini file. For Oracle, the datasource is specified in the ORACLE_SID environment variable or in the tsnames.ora file. For DB2, this is typically the database alias. Database User Name Enter the username used to connect to the database. Database User’s Password Enter the password used to connect to the database. Confirm Password Enter the password again to confirm it. Database Type Select the type of database you are using from the list. If you select postgresql-odbc, you must add the line, ”MaxVarcharSize=4000” to the datasource definition used in the .odbc.ini file. Number of connections to the database Enter the number of connections that you want the component to use for processing requests. Time in seconds between database connection heartbeats Enter the number of seconds after which the database connection should refresh. Do not set this value to zero without contacting Technical support. Is database debug logging enabled? Select ’1’ to log database debug information. Database logging uses the XCP router’s logging facility, the Jabberd Logger. The log level must be set to debug for database logging to occur. Component Logging (Jlog) Administering Presence Services XCP Controller August 2010 225 Services Parameter Description Select the Component Logging (Jlog) option only if you want to configure filtered level loggers that log messages to syslog and to a stream (stderr or stdout). You can enable either or both the syslog and stream loggers. These parameters are displayed in the controller’s Intermediate and Advanced configuration views. Add a new custom logger If you have created a custom logger for logging component information using the libjcore library, click Go to access the Custom Logger Configuration page. SNMP Configuration Select this option if you want to configure SNMP for the component. Enable SNMP Leave this parameter set to Yes. Count errors Select Yes only if you want to enable SNMP error counting. This option takes a great deal of server resource, so use it with caution. Text Conferencing The Text Conferencing (TC) component allows Prexence users to chat in online conference rooms. In addition to chatting, users can search for and join existing rooms, create new rooms, manage members and configurations of the rooms they create, and invite other users to rooms. The TC component also supports the use of extended stanza addressing, which enables XMPP stanzas to specify multiple recipients or sub-addresses. (See XEP-0045 and XEP-0033 for more information about text conferencing (also known as “ Multi-User Chat” ) and its ability to use extended stanza addressing.) An operational Text Conferencing component is set up by default when you install the XCP server. It is configured to handle basic text conferencing using ad hoc (or temporary) conference rooms, which are deleted from the system when the last user leaves the room. Other features are also enabled by default, including room membership, presence, occupancy, invitations, passwords, messages, room moderation, and message history. This chapter describes how to configure the features displayed in the controller’s Basic configuration view. These features include persistent rooms, which remain in existence even when all users have left the room, and text conferencing system administrators, who have ownership privileges for every room in your system. For descriptions of the gears that you can configure in other configuration views, see Text Conferencing Gears . For descriptions of all of the text conferencing parameters, see Text Conferencing Parameter Reference . Related topics: Configuring Persistent Conference Rooms on page 227 Configuring Text Conferencing Administrators on page 227 Conference Room User Roles on page 228 226 Administering Presence Services XCP Controller August 2010 Text Conferencing Text Conferencing Gears on page 229 Text Conferencing Parameter Reference on page 232 Configuring Persistent Conference Rooms This section describes how to configure the persistent conference room feature. Persistent rooms remain in existence on your system even after all users have left the room, as opposed to ad hoc rooms, which are removed from the system when the last user leaves. The persistent room feature also enables users to search for rooms. Related topics: To configure persistent conference rooms on page 227 To configure persistent conference rooms 1. Change to the controller’s Basic configuration view. 2. In the Components area on the controller’s main page, click Edit beside Text Conferencing . The Text Conferencing Configuration page is displayed. 3. Select the Persistent Gear option to enable the use of persistent conference rooms. Persistent rooms require one of XCP’s supported databases—Oracle, PostgreSQL, or DB2 (not SQLite). If you configured one of these databases when you installed the server, you are finished configuring the Persistent Gear. 4. If you want to use a different database for persistent rooms, or if you selected SQLite during installation, select the Database Setup option and configure the parameters. Descriptions of the database parameters are provided in the Persistent Gear section in the “ Basic Parameters” table provided in Text Conferencing Parameter Reference . 5. Click Submit to save your configuration. Configuring Text Conferencing Administrators Text Conferencing system administrators automatically become owners of every conference room in your system. Administering Presence Services XCP Controller August 2010 227 Services Related topics: To configure text conferencing administrators on page 228 To configure text conferencing administrators 1. Change to the controller’s Basic configuration view. 2. In the Components area on the controller’s main page, click Edit beside Text Conferencing . 3. In the Text Conferencing Configuration page, select the Sysadmin Gear . 4. Click Go . The TC Administrator Configuration page is displayed. 5. Configure the parameters as follows. Parameter Description Description Enter a description for this administrator. JID Enter the full JID for the administrator. For example, [email protected]. Nickname Enter a nickname for the administrator. Administrators are identified in rooms by this nickname unless they specify a different name within the room. 6. Click Submit to save your configuration. You are returned to the Text Conferencing Configuration page. 7. Add more administrators if needed. 8. When you have finished, click Submit to save your configuration. Conference Room User Roles The privileges that users have when participating in conference rooms depend on their roles in the room. These roles are listed below, and the privileges associated with them are provided in the table. Visitor – a room user who has no voice in the room (cannot chat or send private messages). Participant – a room user who has voice (can chat and send private messages). 228 Administering Presence Services XCP Controller August 2010 Text Conferencing Moderator – a room user who has voice, can kick other users, and can grant and revoke voice from other users. The following table describes the privileges associated with the room user roles: Privilege Visitor Participant Moderator Enter the room Yes Yes Yes Receive messages from others in the room Yes Yes Yes Change availability status in the room Yes Yes Yes Change nickname in the room Yes Yes Yes Send private messages to others in the room Yes* Yes Yes Invite others to the room Yes* Yes* Yes Send messages to everyone in the room No Yes Yes Change the room’s subject No Yes* Yes Kick participants and visitors from the room No No Yes Grant voice No No Yes Revoke voice from room participants No No Yes * This is the default setting, but configuration settings may further restrict this privilege. Text Conferencing Gears The text conferencing features that you can configure are referred to as “ gears” in the Text Conferencing Configuration page. The following table describes the gears and indicates which configuration view you must use to configure them. Gear Description Configuration Views Persistent Enables your users to configure persistent conference rooms for your TC system. Persistent rooms remain in existence on your system even after all users have left the room. To use persistent rooms, you must have a supported database installed. You must configure the persistent gear if you want to enable users to search for rooms. Sysadmin Enables the use of text conferencing Basic, Intermediate, administrators. TC administrators have the Advanced same privileges as room owners for all rooms on the system. Administering Presence Services XCP Controller Basic, Intermediate, Advanced August 2010 229 Services Gear 230 Description Configuration Views Member The Member Gear lets you configure rules for membership in text conference rooms. The Member Gear controls aspects of TC room membership such as whether members of members-only rooms can invite others to the room, and whether membership in a room is restricted or open. This gear is enabled by default. Message The Message Gear controls who can change Intermediate, Advanced the subject in a TC room, who can send private messages in the room, and whether to remove XHTML formatting from room messages. This gear is enabled by default, and cannot be disabled. Moderation The Moderation Gear allows conference rooms Intermediate, Advanced to have moderators. A conference room moderator is a room user who has voice (meaning he or she can send messages in the room), can kick other users from the room, and can grant and revoke voice from other users in the room. This gear is enabled by default. History The History Gear lets you set the maximum Intermediate, Advanced number of previous messages that are displayed in a TC room. This gear is enabled by default. Authorization The Authorization Gear allows you to use a Advanced custom authorization component to control who can and cannot chat with each other in TC rooms. When you enable this gear, everything that the TC component handles goes through the custom component. Your custom authorization component must be running before TC starts. If it is not running, rooms will not load. TC does not pay attention to the time-to-live setting, which is the number of seconds that the results of the custom component are cached. EventBroker The EventBroker Gear allows you to redirect Advanced packets from the Text Conferencing component to one or more external components that have been written in any language. When the TC component receives the packet, it sends it to the external component. After processing the packet, the component can send responses back to TC as needed. When TC receives a packet back from the component, it decides Administering Presence Services XCP Controller Intermediate, Advanced August 2010 Text Conferencing Gear Description Configuration Views whether to cancel the event or to pass it on to the next gear. The protocol used for communication between the external component and TC is described in the“ EventBroker” chapter in the XCP Server Configuration Guide . Room The Room Gear controls the total number of conference rooms (including both ad hoc and persistent) that can exist in your TC system. Config The Config Gear lets you define generic Advanced configuration fields that will display in the Room Configuration dialog box on the client. This gear complies with XEP-0004: Data Forms , which defines a protocol for data forms and generic data description in XMPP. Presence The Presence Gear controls how room users’ Advanced presence is handled in TC rooms. For example, it controls whether rooms can contain anonymous users (users whose presence is indicated only by nicknames). It also controls whether unavailable users display in a room, and whether users of older software versions (1.0 protocol) can participate in TC rooms. This gear is enabled by default and cannot be disabled. Occupancy The Occupancy Gear lets you configure room Advanced occupancy limits. (This gear is enabled by default, and sets the maximum number of users to 50.) The Occupancy Gear lets you restrict the number of users who can be in any given TC room at one time. You can also use this gear to allow room owners to configure the maximum number of users who may be in the rooms they create. This gear is enabled by default. Invite The Invite Gear controls who can invite other users to a conference room. This gear is enabled by default and cannot be disabled. Advanced Password The Password Gear enables room owners to password-protect the rooms they create. This gear is enabled by default. Advanced Log The Log Gear logs conference room transcripts Advanced in HTML format. You can then post room logs to a web site. The log gear is typically not used for enterprisegrade archiving. For true, archival logging of text Administering Presence Services XCP Controller Advanced August 2010 231 Services Gear Description Configuration Views conferencing, you should add the Message Archiving component to your server configuration. The Log Gear has very restrictive file permissions, since the information being logged is sensitive. In order for Apache to be able to retrieve the logs, it should be run as user ’jabber’. A style sheet named style.css, which is located in xcpInstallDir /support/tc, is referenced by the HTML files that the Log gear generates. You must copy this file to the directory that contains the logs that are generated. You can modify the file to suit your needs using standard CSS rules and syntax. Text Conferencing Parameter Reference This section describes the parameters associated with the Text Conferencing component. The parameters are divided into subsections based on the configuration view in which they display. Related topics: Basic Parameters on page 232 Intermediate Parameters on page 233 Advanced Parameters on page 236 Basic Parameters The following table describes the parameters that display in the controller’s Basic configuration view. The basic parameters are sufficient to configure an operational Text Conferencing component. Parameter Description Description The description is displayed in the Components area on the controller’s main page and should help you distinguish between components of the same type when you have more than one configured. You can change the description as needed. Persistent Gear Select this gear if you want to use persistent text conference room. Persistent rooms remain in existence on your system even when all users have left the room. You must also select this gear if you want users to be able to search the system for existing rooms. 232 Administering Presence Services XCP Controller August 2010 Text Conferencing Parameter Database Setup Description The Persistent Gear requires a database—Oracle, PostgreSQL, or DB2—to store persistent room information. Select this option if you want to configure a database that is different from the one configured for the core router in the Global Settings Configuration page. Datasource Name For the PostgreSQL database, this is the name of the component’s datasource as specified in the .odbc.ini file. For Oracle, the datasource is specified in the ORACLE_SID environment variable or in the tsnames.ora file. For DB2, this is typically the database alias. Database User Name Enter the username used to connect to the database. Database User’s Password Enter the password used to connect to the database. Confirm Password Enter the password again to confirm it. Database Type Select the type of database you are using from the list. If you select postgresql-odbc, you must add the line, “ MaxVarcharSize=4000” to the datasource definition used in the .odbc.ini file. Sysadmin Gear Select this gear if you want to use Text Conferencing administrators. TC administrators have the same privileges as room owners for all rooms on the system. Add a new TC Administrator Click Go to access the TC Administrator Configuration page. Intermediate Parameters The following table describes the parameters that display in the controller’s Intermediate configuration view. Parameter Description Router Outbound Connection Information Select this option only if you want the XCP router to connect to the component. For example, if the component is running outside your firewall, this option allows the router to connect to the component safely rather than introducing security risks by letting the component connect to it. By default, components connect to the router using the router’s Master Accept Port. Component IP Enter the IP address or host name of the system on which the component is installed. Port Enter the port that the component uses for communications. Password Enter the password that the router uses to authenticate the component. Administering Presence Services XCP Controller August 2010 233 Services Parameter Description Execute an External Command This option allows the router to start the component automatically. If you prefer to start the component from a command line, disable this option. Command line to run A command that runs the component automatically is provided by default. You can modify it if needed. Note: Do not use the -B argument with this component. Since jabberd is already a daemon process, its children must not be daemons. You should not redirect output, because all output to STDOUT and STDERR will be redirected to /dev/null. Hostnames for this Component This option specifies the hosts for which this component will handle packets. Specify a host filter only if you want the component to be externally addressable; for example, if you want clients and other components or programs to communicate with it. This is because the mod_disco module in JSM uses host filters to return the component as something that should be discoverable. Host Filters By default, the host name of the XCP server prepended by “ conference” is provided. Enter the host names or IP addresses for which you want this component to handle packets. Separate each host name or address with a line break. Host filters must be host names, or IPv4 or IPv6 addresses. If you use an IP address, the packet address must also use this IP address. Persistent Gear 234 Number of connections to the database Enter the number of connections that you want the component to use for processing requests. Time in seconds between database connection heartbeats Enter the number of seconds after which the database connection should refresh. Do not set this value to zero without contacting Technical support. Archive all room joins and exits? Select Yes if you want to archive all instances of users joining and exiting rooms in the database. This option activates the TC_TIMELOG table in your database. Archive all room messages? Select Yes if you want to archive all messages that were sent in the room. How many messages can be retrieved from the archive at once? Enter the number of messages that can be retrieved from the archive at one time. How many messages display Enter the default number of previous messages that should display in a room. Administering Presence Services XCP Controller August 2010 Text Conferencing Parameter Description in the room by default? Timeout value for persistent rooms (minutes) Enter the number of minutes that can occur with no activity before a persistent room is deleted. The default setting of ’0’ disables this feature, preventing room cleanup. Member Gear The Member Gear lets you configure rules for membership in text conference rooms. The Member Gear controls aspects of TC room membership such as whether members of members-only rooms can invite others to the room, and whether membership in a room is restricted or open. Are rooms for members only by default? Select Yes only if you want all rooms that are created to be for members only by default. Can room owners change this setting when configuring a room? Select Yes to enable room owners to configure this option. Only moderators Select Yes if you want moderators to be the only ones who can invite can invite people to others to members-only rooms. If you select No, any user can invite members-only others. rooms? Can users add themselves to rooms as members? Select Yes if you want to let users add themselves to conference rooms as members. Message Gear The Message Gear controls who can change the subject in a TC room and who can send private messages in the room. What is the lowest participation level a user can have to change a room's subject? Select the default privilege level that users must have to change the subject in a room. The choices are: Participant - a room user who has voice (can chat in the room). Moderator - a room user who has voice, can kick other users, and can grant and revoke voice from other users. Can room owners change this setting when configuring a room? Select Yes to enable room owners to configure this option. What is the lowest participation level a user can have to send a private message from within the room? Visitor - a room user who has no voice in the room (cannot chat in the room). Participant - a room user who has voice (can chat in the room). Moderator - a room user who has voice, can kick other users, and can grant and revoke voice from other users. Administering Presence Services XCP Controller August 2010 235 Services Parameter Description Remove all XHTML Select Yes if you want to remove formatting from the messages sent formatting from in TC rooms. messages? Moderation Gear The Moderation Gear enables the use of moderators in conference rooms. A moderator is a room user who has voice, meaning he or she can send messages in the room. The moderator can also remove other users from the room, and can grant and revoke voice from other users in the room. Are rooms moderated by default? Select Yes if you want to allow rooms to have moderators by default. Can room owners change this setting when configuring a room? Select Yes if you want to let room owners enable or disable moderation for the rooms they create. History Gear The History Gear lets you set the maximum number of previous messages that are displayed in a TC room. How many previous Enter the maximum number of messages that can display in the messages can message history for any room on your system. display in a room? How many previous Enter the number of messages that appear in the message history of messages display a room by default. in a room by default? Can room owners change this setting when configuring a room? Select Yes if you want to let room owners set the number of messages that appear in the message history for the rooms they create. Room owners cannot set a number larger than the one you configured above. Component Logging (Jlog) Select the Component Logging (Jlog) option only if you want to configure filtered level loggers that log messages to syslog and to a stream (stderr or stdout). You can enable either or both the syslog and stream loggers. These parameters are displayed in the controller’s Intermediate and Advanced configuration views. SNMP Configuration Select this option if you want to configure SNMP for the component. Enable SNMP Leave this parameter set to Yes. Advanced Parameters The following table describes the parameters that are displayed in the controller’s Advanced configuration view. Advanced parameters are used for adjusting the performance of the XCP 236 Administering Presence Services XCP Controller August 2010 Text Conferencing system. We recommend that you call Technical Support if you need to change these parameter settings. Parameter Description Runlevel Enter the order in which this component shuts down. The runlevel must be an integer value greater than or equal to zero. Component shutdown is executed in reverse order of the specified runlevel; components with the highest level (typically 70) shut down first. Do not change the runlevel unless you know exactly what you are doing and understand the effects that changing it will have. The default runlevel is provided to help the system shut down as smoothly as possible, and is based on this component’s dependencies upon other components. Timeout for shutdown Enter the number of seconds that the server waits to receive acknowledgement from the component that the shutdown process has completed. If the component has not shut down by the time this time period has elapsed, the router leaves the process in its current state and continues shutting down other processes. Component Properties Number of packets Enter the number of packets bound for the component that should be buffered when buffered if the component goes down. component is down Bounce error packets to stderr Select Yes if you want the router to send warnings to stderr when the component is down. Router Outbound Connection Information Buffer size in bytes Enter the number of bytes the router should buffer when it sends for outgoing data information to the component. You may want to modify this element when working on performance enhancements. Buffer size in bytes Enter the number of bytes the router should buffer when it receives for incoming data information from the component. You may want to modify this element when working on performance enhancements. Send keepalives Select Yes if you want the router to send keep-alives to the component. The keep-alive helps prevent firewalls from dropping an unused connection to the component. If this option is set to No, keepalives are disabled. Log the delivery of packets to this component Select Yes if you want to log the data that the router delivers to the component. The information is logged to the logger(s) you set up during Jabberd Logger configuration (syslog, file, or stderr). Socketlevel logging happens only at the debug level. Execute an External Command Maximum interval in seconds to wait before restarting component Enter the maximum number of seconds after which the router tries to restart the component. If the component goes down, the router tries to restart it after one second. If the component does not start, the router multiplies the wait time by 1.5, and tries again. Once the Administering Presence Services XCP Controller August 2010 237 Services Parameter Description maximum time interval that you specify for this parameter is reached, the router continues to retry after waiting this amount of time. Maximum number of times to restart component Enter the total number of restarts allowed. The default setting, -1, means unlimited. Interval in seconds at which to reset this value to 1 second Enter the number of seconds that the component has been up and running, after which to set the restart time back to one second. Path to binary Enter the directory path to the shell that launches the component. You can change the default setting if needed. TC Configuration Number of threads to dedicate to TC tasks Enter the number of database update threads that you want the TC component to use. Number of managed queues to dedicate to TC tasks Enter the number of queues that you want the TC component to use. This number reflects how many expected rooms there will be on a system divided by 20. The recommendation is one queue for every 20 rooms. Timeout (in seconds) for XDB requests Enter the number of seconds to wait before an XDB request that has been sent to the router times out. This setting affects users; the higher the setting, the slower the system runs. Enable Stanza Optimizer Support (XEP-033) Select this option to enable stanza optimization support for the component. Number of room members to trigger an extended address stanza Enter the number of recipients required to cause an extended address stanza to be used rather than individual packets. Multiple optimizer address threshold This option is to be used mainly for fine-tuning your system. The default value that is supplied should be sufficient in most cases. Enter the number of recipients per found stanza optimizer to warrant separating a single packet into many. Take the following scenario, for example: In this case, each stanza optimizer would handle approximately 133 recipients, warranting three extended stanza packets rather than one. Using the same scenario but with only 200 recipients, each optimizer would handle approximately 66 recipients each. This situation does not warrant splitting the packet. Therefore, only one packet will be sent to one optimizer for local delivery. Authorization Gear 238 Administering Presence Services XCP Controller August 2010 Text Conferencing Parameter Description Enable the Authorization Gear if you want to use a custom authorization component to control who can and cannot chat with each other in TC rooms. When you enable this gear, everything that the TC component handles goes through the custom component. Note: Your custom authorization component must be running before TC starts. If it is not running, rooms will not load. TC does not pay attention to the time-to-live setting, which is the number of seconds that the results of the custom component are cached. EventBroker Gear EventBroker configuration features are available only if you have installed the XCP extras package. The EventBroker Gear allows you to redirect packets from Text Conferencing to one or more external components that have been written in any language. When the TC component receives the packet, it sends it to the external component. After processing the packet, the component can send responses back to TC as needed. When TC receives a packet back from the component, it decides whether to cancel the event or to pass it on to the next gear. The protocol used for communication between the external component and TC is described in the “ EventBroker” chapter in the XCP Server Configuration Guide . Library Leave the default setting (ExternalGear) in this field unless you want to use a custom external gear. Add a new EventBroker Event Click Go to access the EventBroker Event Configuration screen. Persistent Gear Is database debug logging enabled? Select ’1’ to log database debug information. Database logging uses the XCP router’s logging facility, the Jabberd Logger. The log level must be set to debug for database logging to occur. Restrict persistent Select Yes if you want only TC administrators to be able to create room creation to TC persistent rooms. If you select No, all users can create persistent administrators rooms. only? How many messages can be retrieved from the archive at once? Enter the maximum number of archived messages that a client can retrieve at once. What is the Enter the maximum number of persistent conference rooms that can maximum number exist on your TC system. of persistent rooms allowed? Room Gear The Room Gear controls the total number of conference rooms (including both ad hoc and persistent) that can exist on your TC system. Custom library Leave this box blank unless you want to use a custom Room gear. Administering Presence Services XCP Controller August 2010 239 Services Parameter How many rooms can exist on your system? Description Enter the maximum number of conference rooms that can exist on your TC system. Config Gear The Config Gear lets you define generic configuration fields that will display in the Room Configuration dialog on the client. This gear complies with XEP-0004: Data Forms , which defines a protocol for data forms and generic data description in XMPP. Custom library Leave this box blank unless you want to use a custom Config gear. Generic Config Fields Select this option, and then click Go to add a configuration field. Member Gear Custom library Leave this box blank unless you want to use a custom Member gear. Presence Gear The Presence Gear controls how room users’ presence is handled in TC rooms. For example, it controls whether rooms can contain anonymous users (users whose presence is indicated only by nicknames). It also controls whether unavailable users display in a room, and whether users of older software versions (1.0 protocol) can participate in TC rooms. Custom library Leave this box blank unless you want to use a custom Presence gear. Should members Select Yes if you want conference room members and administrators and administrators who are currently not in a room to be visible, displaying a presence who are not in a indicator of unavailable. room still be visible in the room? Can room owners change this setting when configuring a room? Select Yes to enable room owners to configure this option. Should rooms be backwardscompatible with older clients? Select Yes if you want to allow users of older clients (group chat 1.0 protocol) to participate in TC rooms. Should rooms be anonymous by default? Select Yes if you want to make all TC rooms anonymous by default. Anonymous rooms allow users to participate using nicknames; other users in the room cannot see anonymous users’ JIDs. Occupancy Gear The Occupancy Gear lets you configure room occupancy limits. (This gear is enabled by default, and sets the maximum number of users to 50.) The Occupancy Gear lets you restrict the number of users who can be in any given TC room at one time. You can also use this 240 Administering Presence Services XCP Controller August 2010 Text Conferencing Parameter Description gear to allow room owners to configure the maximum number of users who may be in the rooms they create. Custom library Leave this box blank unless you want to use a custom Occupancy gear. How many users Enter the maximum number of users who can be in any given can be in a room at conference room on your TC system at one time. one time? A room owner can still join a room even when the maximum number of users has been reached. How many hidden users can be in a room? Enter the maximum number of hidden occupants who can be in any given conference room on your system. Hidden occupants are those who are filtering on a room but are not in the room. The number of hidden occupants in a room is included in the total number of room occupants. You must set this number to 1 or greater. Setting it to 0 causes an error. What is the default maximum occupancy for a room? Enter the default maximum number of users who can be in a conference room. This number is displayed as the default in the Room parameters window in the clients’ TC interface. Can room owners change this setting when configuring a room? Select Yes if you want to let room owners specify the maximum number of users who can be in a room at one time. Invite Gear The Invite Gear controls who can invite other users to a conference room. Custom library Leave this box blank unless you want to use a custom Invite gear. What is the lowest participation level a user can have to invite others to the room? Select the default privilege level that users must have to invite others to a room. The choices are: Visitor – a room user who has no voice in the room (cannot chat in the room). Participant – a room user who has voice (can chat in the room). Moderator – a room user who has voice, can kick other users, and can grant and revoke voice from other users. Can room owners change this setting when configuring a room? Select Yes if you want to allow room owners to choose the privilege level that users must have to invite others to a room. Password Gear The Password Gear enables room owners to password-protect the rooms they create. Custom library Leave this box blank unless you want to use a custom Password gear. Message Gear Administering Presence Services XCP Controller August 2010 241 Services Parameter Custom library Description Leave this box blank unless you want to use a custom Message gear. Moderation Gear Custom library Leave this box blank unless you want to use a custom Moderation gear. History Gear Custom library Leave this box blank unless you want to use a custom History gear. Log Gear The Log Gear logs conference room transcripts in HTML format. You can then post room logs to a web site. This gear is typically not used for enterprise-grade archiving. For true, archival logging of text conferencing, you should add the Message Archiving component to your server configuration. Note: The Log Gear has very restrictive file permissions, since the information being logged is sensitive. In order for Apache to be able to retrieve the logs, it should be run as user 'jabber'. Library This value is read-only. Location of file where room messages are logged Enter the directory path of the file where messages are logged. Base URL where users can view room logs Enter the URL at which users can view the room logs. The URL should contain a trailing slash (/). This URL is displayed in a text conference room when the log gear is enabled, and the user enters the following in a room: ?? log You can specify a file:/// type URL, but these work only if log files are stored on the local machine. Buffer size to use when writing to the logs Enter the size in bytes of the buffer that you want to use for writing logs. Sysadmin Gear Custom library Leave this box blank unless you want to use a custom Sysadmin gear. Component Logging (Jlog) Add a new custom logger If you have created a custom logger for logging component information using the libjcore library, click Go to access the Custom Logger Configuration page. SNMP Configuration Count errors 242 Select Yes only if you want to enable SNMP error counting. This option takes a great deal of server resource, so use it with caution. Administering Presence Services XCP Controller August 2010 Wait List Service Wait List Service This chapter describes how to configure the Wait List Service component. The Wait List Service allows an IM user to place a contact on a waiting list by specifying information about the contact. The Wait List Service uses this information to “ track” the contact and to notify the Presence user when the contact creates an IM account. To implement the Wait List Service, you must create a library that uses the Wait List interface to enable communication between the IM service and other services. The library must retrieve contact information (in a URI scheme) from the service’s datastore, such as telephone number or email address. Note: The Wait List service’s specification is defined in XEP-0130 . The library that you write must conform to XEP-0130. Related topics: Configuring the Wait List Service Component on page 243 Wait List Service Parameter Reference on page 244 The Wait List Interface on page 248 Creating a JIG File on page 249 Configuring the Wait List Service Component The Wait List Service component’s configuration parameters display in the controller’s Advanced configuration view. The following instructions describe how to configure only the parameters that are specific to the Wait List Service. For descriptions of all of the parameters, see Wait List Service Parameter Reference . Related topics: To configure the Wait List Service component on page 243 To configure the Wait List Service component 1. Change to the Controller’s Advanced configuration view. 2. In the Components area on the controller’s main screen, select Wait List Service in the list, and then click Go . Administering Presence Services XCP Controller August 2010 243 Services 3. In the Wait List Service Configuration page, scroll down to the Wait List component config section. 4. Configure the parameters as follows. Parameter Configuration Number of threads to Enter the number of threads that you want to have dedicate to WaitList tasks processing tasks in the component. Increasing this value enables the component to handle more tasks at a time. However, it spends more time scheduling the tasks as this number increases. We recommend that you set this number to one more than the number of processors on your system. Seconds before IQ requests time out Enter the number of seconds to wait before iq requests that are sent to remote service providers time out. List of Local Service Providers Enter the local domains of the service providers with which the XCP server is communicating; for example, corp.example.com and example.com. List of Interop Partners Enter the domains of the service providers’ Interop partners. Service Provider Library Enter the name of the library that you created using the Wait List Service API, described in the “ Wait List Service API” chapter in the XCP Server Developer Guide. 5. The Wait List Service requires a database —Oracle, PostgreSQL, or DB2. If you configured one of these databases when you installed the XCP server, you do not have to configure one here. However, if you want to use a different database for the Wait List Service, or if you selected SQLite during installation, select the Database Setup option and configure the parameters. Descriptions of the database parameters are provided under Database Setup in the table provided the following section. 6. When you have finished configuring the Wait List Service component, click Submit to save your configuration. Wait List Service Parameter Reference This section describes the parameters associated with the Wait List Service component. The Wait List Service parameters are available only in the controller’s Advanced configuration view. 244 Administering Presence Services XCP Controller August 2010 Wait List Service Parameter Description Description The description is displayed in the Components area on the controller’s main page and should help you distinguish between components of the same type when you have more than one configured. You can change the description as needed. Runlevel Enter the order in which this component shuts down. The runlevel must be an integer value greater than or equal to zero. Component shutdown is executed in reverse order of the specified runlevel; components with the highest level (typically 70) shut down first. Do not change the runlevel unless you know exactly what you are doing and understand the effects that changing it will have. The default runlevel is provided to help the system shut down as smoothly as possible, and is based on this component’s dependencies upon other components. Timeout for shutdown Enter the number of seconds that the server waits to receive acknowledgement from the component that the shutdown process has completed. If the component has not shut down by the time this time period has elapsed, the router leaves the process in its current state and continues shutting down other processes. Component Properties Number of packets buffered when component is down Enter the number of packets bound for the component that should be buffered if the component goes down. Bounce error packets to stderr Select Yes if you want the router to send warnings to stderr when the component is down. Router Outbound Connection Information Select this option only if you want the XCP router to connect to the component. For example, if the component is running outside your firewall, this option allows the router to connect to the component safely rather than introducing security risks by letting the component connect to it. By default, components connect to the router using the router’s Master Accept Port. Component IP Enter the IP address or host name of the system on which the component is installed. Port Enter the port that the component uses for communications. Password Enter the password that the router uses to authenticate the component. Buffer size in bytes Enter the number of bytes the router should buffer when it sends for outgoing data information to the component. You may want to modify this element when working on performance enhancements. Buffer size in bytes Enter the number of bytes the router should buffer when it receives for incoming data information from the component. You may want to modify this element when working on performance enhancements. Administering Presence Services XCP Controller August 2010 245 Services Parameter Send keepalives Description Select Yes if you want the router to send keep-alives to the component. The keep-alive helps prevent firewalls from dropping an unused connection to the component. If this option is set to No, keep-alives are disabled. Log the delivery of Select Yes if you want to log the data that the router delivers to the packets to this component. The information is logged to the logger(s) you set up during component Jabberd Logger configuration (syslog, file, or stderr). Socket-level logging happens only at the debug level. Execute an External Command This option allows the router to start the component automatically. If you prefer to start the component from a command line, disable this option. Maximum interval in seconds to wait before restarting component Enter the maximum number of seconds after which the router tries to restart the component. If the component goes down, the router tries to restart it after one second. If the component does not start, the router multiplies the wait time by 1.5, and tries again. Once the maximum time interval that you specify for this parameter is reached, the router continues to retry after waiting this amount of time. Maximum number Enter the total number of restarts allowed. The default setting, -1, of times to restart means unlimited. component Interval in seconds Enter the number of seconds that the component has been up and at which to reset running, after which to set the restart time back to one second. this value to 1 second Path to binary Enter the directory path to the shell that launches the component. You can change the default setting if needed. Command line to run A command that runs the component automatically is provided by default. You can modify it if needed. Note: Do not use the -B argument with this component. Since jabberd is already a daemon process, its children must not be daemons. You should not redirect output, because all output to STDOUT and STDERR will be redirected to /dev/null. Hostnames for this Component This option specifies the hosts for which this component will handle packets. Specify a host filter only if you want the component to be externally addressable; for example, if you want clients and other components or programs to communicate with it. This is because the mod_disco module in JSM uses host filters to return the component as something that should be discoverable. Host Filters 246 By default, the XCP server’s host name prepended by “ waitlist” is provided. Administering Presence Services XCP Controller August 2010 Wait List Service Parameter Description Enter the host names or IP addresses for which you want this component to handle packets. Separate each host name or address with a line break. Host filters must be host names, or IPv4 or IPv6 addresses. If you use an IP address, the packet address must also use this IP address. Wait List Configuration Number of threads Enter the number of threads that you want to have processing tasks in to dedicate to the component. Increasing this value enables the component to handle WaitList tasks more tasks at a time. However, it spends more time scheduling the tasks as this number increases. We recommend that you set this number to one more than the number of processors on your system. Wait List Tracker Settings Enter the number of seconds to wait before iq requests that are sent to remote service providers time out. List of Local Service Providers Enter the local domains of the service providers with which the XCP server is communicating; for example, corp.example.com and example.com. List of Interop Partners Enter the domains of the service providers’ Interop partners. Service Provider Library Enter the name of the library that you created using the Wait List Service API, described in the “ Wait List Service API” chapter in the XCP Server Developer Guide. Database Setup Datasource Name For the PostgreSQL database, this is the name of the component’s datasource as specified in the .odbc.ini file. For Oracle, the datasource is specified in the ORACLE_SID environment variable or in the tsnames.ora file. For DB2, this is typically the database alias. Database User Name Enter the username used to connect to the database. Database User’s Password Enter the password used to connect to the database. Confirm Password Enter the password again to confirm it. Database Type Select the type of database you are using from the list. If you select postgresql-odbc, you must add the line, “ MaxVarcharSize=4000” to the datasource definition used in the .odbc.ini file. Number of Enter the number of connections that you want the component to use connections to the for processing requests. database Administering Presence Services XCP Controller August 2010 247 Services Parameter Description Time in seconds Enter the number of seconds after which the database connection between database should refresh. Do not set this value to zero without contacting connection Technical support. heartbeats Is database debug Select ’1’ to log database debug information. Database logging uses logging enabled? the XCP router’s logging facility, the Jabberd Logger. The log level must be set to debug for database logging to occur. Component Logging (Jlog) Select the Component Logging (Jlog) option only if you want to configure filtered level loggers that log messages to syslog and to a stream (stderr or stdout). You can enable either or both the syslog and stream loggers. These parameters are displayed in the controller’s Intermediate and Advanced configuration views. Add a new custom If you have created a custom logger for logging component information logger using the libjcore library, click Go to access the Custom Logger Configuration page. SNMP Configuration Select this option if you want to configure SNMP for the component. Enable SNMP Leave this parameter set to Yes. Count errors Select Yes only if you want to enable SNMP error counting. This option takes a great deal of server resource, so use it with caution. The Wait List Interface The ISPLibrary.hpp file (located in xcpInstallDir /include/wlservice) provides the interface around which you must create your Wait List library. It contains the following declarations: • virtual ~ISPLibrary() – The base destructor for ISPLibrary implementations. • virtual bool isValidURI – Checks to make sure that the URI sent from the SP is valid. • virtual jid::Jid *findJidFromURI – Checks to see if the SP user already has a JID in the SP’s datastore. • virtual judo::Element *getDomainsForURI – Retrieves a list of domains that have knowledge of the URI. • virtual judo::Element *getNotification – Gets the notification when a wait-listed contact creates an IM account. • virtual char *getPushBody – Gets the body of the message that is sent to the Presence user when a contact creates an IM account. The library that you write must use all of the declarations in the ISPLibrary.hpp file. An example implementation is provided in the splibrarytemplate.cpp file (located in xcpInstallDir /include/ wlservice). 248 Administering Presence Services XCP Controller August 2010 Web Services Creating a JIG File You must create a JIG file named splib.jig that defines the configuration options for your service provider library. The splib.jig file is referenced in waitlist.jig , which is located in xcpInstallDir / schemas/jig/config/waitlist. The following line in waitlist.jig includes splib.jig in the Wait List Service Configuration page: <xi:include xi:href="${JABBER_HOME}/schemas/jig/config/waitlist/splib.jig"/> If you name your JIG file something else, make sure you change the file name referenced in this line. Related topics: To create the splib.jig file on page 249 To create the splib.jig file 1. Follow the instructions provided in the “ Custom Component Integration” chapter in the XCP Server Developer Guide . 2. Save the file as xcpInstallDir /schemas/jig/config/waitlist/splib.jig. Web Services T he Web Services component enables custom-built Web Services applications and custom components to access and use the XCP services messaging, roster/presence, and infobroker. Applications communicate with the server via SOAP over HTTP, and custom components communicate with the server via SOAP over XMPP as specified in XEP-72 . Related topics: Configuring Web Services on page 250 Web Services Parameter Reference on page 254 Service-Specific Configurations on page 257 Invoking Services from a SOAP-over-HTTP Client on page 259 Web Services Definition Language Files on page 260 Administering Presence Services XCP Controller August 2010 249 Services Configuring Web Services This section describes how to configure Web Services to run in your XCP environment. The configuration involves the following steps: • Configuring the Web Services Component • Configuring a Web Services Connection Manager • Adding Web Services as a Presence Administrator • Configuring a Web Services Administrator Related topics: Configuring the Web Services Component on page 250 Configuring a Web Services Connection Manager on page 251 Adding Web Services as a Presence Administrator on page 253 Configuring a Web Services Administrator on page 253 Configuring the Web Services Component The following instructions describe how to configuring the Web Services component using the parameters provided in the controller’s Intermediate configuration view. These parameters are sufficient to configure an operational component. For descriptions of all of the Web Services parameters, see Web Services Parameter Reference . Related topics: To configure the Web Services component on page 250 To configure the Web Services component 1. Change to the controller’s Intermediate configuration view. 2. In the Components area on the controller’s main page, select Web Services from the list, and then click Go . 3. In the Web Services Configuration page, note the ID of the component. You will need to use this ID later in the configuration. 4. Scroll down to the Services section, and click Go beside Add a New Service . The Service Configuration page is displayed. 5. Configure the parameters as follows: 250 Administering Presence Services XCP Controller August 2010 Web Services Parameter Configuration Namespace for this service Enter the namespace that you want to use for this service. You must use one of the following: http://jabber.com/webservices/ Messaging http://jabber.com/webservices/ RosterPresence http://jabber.com/webservices/ InfoBroker Note: These namespaces are built into the WebServices API and are the only ones currently supported. Do not modify them. Service library Leave this option blank unless you want to use a custom service library. Service load function Depending on the namespace you specified above, enter one of the following corresponding functions: ws_messaging ws_rosterpresence ws_infobroker 6. Click Submit to save your configuration. You are returned to the Web Services Configuration page. 7. On the Web Services Configuration page, add more services if needed. 8. When you have finished, click Submit to save your configuration. Configuring a Web Services Connection Manager Note: In order to facilitate high performance for Web Services, we recommend that you configure a separate Connection Manager for each Web Services component that you add to your XCP configuration. The Web Services Connection Manager is configured with a Web Command Processor (WebCP), which has a SOAPHandler. The WebCP SOAPHandler is used when Web Services applications send SOAP-over-HTTP requests to the XCP server. It provides the ability to map a URL to a dynamically-loaded handler. The SOAPHandler is responsible for taking the SOAPover-HTTP request, authenticating it, and translating it into SOAP over XMPP so that it can be routed to the Web Services Component. When a response comes in from the Web Services Administering Presence Services XCP Controller August 2010 251 Services component, the WebCP SOAPHandler translates it back into SOAP over HTTP, and writes the result back to the requesting application. Related topics: To configure a Web Services Connection Manager on page 252 To configure a Web Services Connection Manager 1. Change to the controller’s Advanced configuration view. 2. In the Components area on the controller’s main page, click Go to add a new Connection Manager. 3. In the Connection Manager Configuration page under Add a New Command Processor , select Web Command Processor in the list, and click Go . 4. In the Web Command Processor Configuration page under Director Configuration , click Go to add an HTTP director. 5. Use the parameter descriptions in the online help to configure the HTTP Director, or use the default settings. Note: The default port number of the director’s external channel is 7335, which implements an HTTP server on port 7335 to serve incoming SOAP requests. You can change the port number if necessary. 6. Click Submit to save the HTTP Director configuration. You are returned to the Web Command Processor Configuration page. 7. On the Web Command Processor Configuration page under Handlers , select Web Services Handler in the list, and click Go . The Web Services Handler enables the Web Command Processor to communicate with the XCP core router. 8. In the Web Services Handler Configuration page, make note of the handler’s ID . You will need to use it later when you configure the Web Services administrator. 9. In the HTTP URI Paths Handled text box, enter the path, /soap as shown in the following figure. This path is referenced in the WSDL. 10. Click Submit to save your configuration. You are returned to the Web Command Processor Configuration page. 11. Click Submit in each page until you return to the controller’s main page. 252 Administering Presence Services XCP Controller August 2010 Web Services Adding Web Services as a Presence Administrator You must add the ID of the Web Services component as a Presence administrator in the Presence Session Manager. Related topics: To edit the JSM configuration on page 253 To edit the JSM configuration 1. Change to the controller’s Interm3ediate configuration view. 2. In the Router area on the controller’s main page, click Edit beside Presence Session Manager . 3. On the Presence Session Manager Configuration page, scroll down to the JSM Configuration section. 4. Add the ID of the Web Services component in the Presence Administrators box. For example: web-services-1.jabber 5. Click Submit to save your configuration. Configuring a Web Services Administrator The Web Services component must be able to authorize requests coming in from the Web Services Handler. For this to happen, the Web Services Handler must be added as an administrator in the Web Services configuration. Related topics: To configure the Web Services administrator on page 253 To configure the Web Services administrator 1. In the Components area on the controller’s main page, click Edit beside Web Services . 2. In the Web Services Configuration page, scroll down to the Web Services Administrators section. Administering Presence Services XCP Controller August 2010 253 Services 3. Add the ID of the Web Services Handler as an administrator. For example: cm-2_webcp-1_websvch-1 4. Click Submit to save your configuration. Web Services Parameter Reference This section describes the parameters associated with the Web Services component. The parameters are divided into subsections based on the configuration view in which they display. Related topics: Intermediate Parameters on page 254 Advanced Parameters on page 256 Intermediate Parameters The following table describes the parameters that are displayed in the controller’s Intermediate configuration view. These parameters are sufficient to configure an operational Web Services component. Parameter Description Description The description is displayed in the Components area on the controller’s main page and should help you distinguish between components of the same type when you have more than one configured. You can change the description as needed. Router Outbound Connection Information Select this option only if you want the XCP router to connect to the component. For example, if the component is running outside your firewall, this option allows the router to connect to the component safely rather than introducing security risks by letting the component connect to it. By default, components connect to the router using the router’s Master Accept Port. Component IP Enter the IP address or host name of the system on which the component is installed. Port Enter the port that the component uses for communications. Password Enter the password that the router uses to authenticate the component. Execute an External Command This option allows the router to start the component automatically. If you prefer to start the component from a command line, disable this option. 254 Administering Presence Services XCP Controller August 2010 Web Services Parameter Command line to run Description A command that runs the component automatically is provided by default. You can modify it if needed. Note: Do not use the -B argument with this component. Since jabberd is already a daemon process, its children must not be daemons. You should not redirect output, because all output to STDOUT and STDERR will be redirected to /dev/null. Hostnames for this Component This option specifies the hosts for which this component will handle packets. Specify a host filter only if you want the component to be externally addressable; for example, if you want clients and other components or programs to communicate with it. This is because the mod_disco module in JSM uses host filters to return the component as something that should be discoverable. Host Filters By default, the XCP server’s host name prepended by ”webservices” is provided. Enter the host names or IP addresses for which you want this component to handle packets. Separate each host name or address with a line break. Host filters must be host names, or IPv4 or IPv6 addresses. If you use an IP address, the packet address must also use this IP address. Web Services Configuration ID of the InfoBroker component An ID for the InfoBroker component is supplied by default. If you plan to use Web Services with the InfoBroker, you must configure the InfoBroker component. Administrator(s) Enter the ID and realm of the Web Services Handler; for example: cm-2_webcp-1_websvch-1.jabber (The Web Services Handler is configured in a Web Services Connection Manager.) Services Click Go to configure a Web service that you want to make available through the Web Services component. You must configure at least one service. Component Logging (Jlog) Select the Component Logging (Jlog) option only if you want to configure filtered level loggers that log messages to syslog and to a stream (stderr or stdout). You can enable either or both the syslog and stream loggers. These parameters are displayed in the controller’s Intermediate and Advanced configuration views. SNMP Configuration Select this option if you want to configure SNMP for the component. Enable SNMP Leave this parameter set to Yes. Administering Presence Services XCP Controller August 2010 255 Services Advanced Parameters The following table describes the parameters that are displayed in the controller’s Advanced configuration view. Advanced parameters are used for adjusting the performance of the XCP system. We recommend that you call Technical Support if you need to change these parameter settings. Parameter Description Runlevel Enter the order in which this component shuts down. The runlevel must be an integer value greater than or equal to zero. Component shutdown is executed in reverse order of the specified runlevel; components with the highest level (typically 70) shut down first. Do not change the runlevel unless you know exactly what you are doing and understand the effects that changing it will have. The default runlevel is provided to help the system shut down as smoothly as possible, and is based on this component’s dependencies upon other components. Timeout for shutdown Enter the number of seconds that the server waits to receive acknowledgement from the component that the shutdown process has completed. If the component has not shut down by the time this time period has elapsed, the router leaves the process in its current state and continues shutting down other processes. Component Properties Number of packets buffered when component is down Enter the number of packets bound for the component that should be buffered if the component goes down. Bounce error packets to stderr Select Yes if you want the router to send warnings to stderr when the component is down. Router Outbound Connection Information Buffer size in bytes Enter the number of bytes the router should buffer when it sends for outgoing data information to the component. You may want to modify this element when working on performance enhancements. Buffer size in bytes Enter the number of bytes the router should buffer when it receives for incoming data information from the component. You may want to modify this element when working on performance enhancements. Send keepalives Select Yes if you want the router to send keep-alives to the component. The keep-alive helps prevent firewalls from dropping an unused connection to the component. If this option is set to No, keep-alives are disabled. Log the delivery of Select Yes if you want to log the data that the router delivers to the packets to this component. The information is logged to the logger(s) you set up during component 256 Administering Presence Services XCP Controller August 2010 Web Services Parameter Description Jabberd Logger configuration (syslog, file, or stderr). Socket-level logging happens only at the debug level. Execute an External Command Maximum interval in seconds to wait before restarting component Enter the maximum number of seconds after which the router tries to restart the component. If the component goes down, the router tries to restart it after one second. If the component does not start, the router multiplies the wait time by 1.5, and tries again. Once the maximum time interval that you specify for this parameter is reached, the router continues to retry after waiting this amount of time. Maximum number Enter the total number of restarts allowed. The default setting, -1, of times to restart means unlimited. component Interval in seconds Enter the number of seconds that the component has been up and at which to reset running, after which to set the restart time back to one second. this value to 1 second Path to binary Enter the directory path to the shell that launches the component. You can change the default setting if needed. Web Services Configuration Number of threads Enter the number of threads that you want to have processing tasks in to dedicate to Web the component. Increasing this value enables the component to handle Services tasks more tasks at a time. However, it spends more time scheduling the tasks as this number increases. We recommend that you set this number to one more than the number of processors on your system. Component Logging (Jlog) Add a new custom If you have created a custom logger for logging component information logger using the libjcore library, click Go to access the Custom Logger Configuration page. SNMP Configuration Count errors Select Yes only if you want to enable SNMP error counting. This option takes a great deal of server resource, so use it with caution. Service-Specific Configurations This section describes the extra steps that are required to configure broadcast messages, offline messages, and the InfoBroker service. Administering Presence Services XCP Controller August 2010 257 Services Related topics: Broadcast Messages on page 258 Offline Messaging on page 258 InfoBroker on page 259 Broadcast Messages The broadcast message function is part of the Messaging service. To enable this function, you must modify the JSM Command Processor’s configuration. Related topics: To enable broadcast messages on page 258 To enable broadcast messages 1. Change to the controller’s Advanced configuration view 2. In the Components area on the controller’s main page, click Edit beside the Connection Manager component that is configured with a JSM Command Processor. The CM component that is installed by default with the XCP server contains a JSM Command Processor. Note: If you have multiple Connection Manager components that are configured with a JSM Command Processor, you must perform this procedure for each one. 3. In the Connection Manager Configuration page under Add a new Command Processor , click Details beside jsmcp . 4. In the lower portion of the JSM Command Processor Configuration page, select Yes beside Enable Broadcast to all online users connected to this CM . 5. Click Submit to save your configuration. Offline Messaging To enable offline messaging to work correctly with Web Services, the mod_offline_pop module in the JSM configuration must be enabled. The module is enabled by default, and is required for XEP-0013: Flexible Offline Message Retrieval functionality. Do not change this setting without first consulting Technical support. Related topics: To verify that the mod_offline_pop module is enabled on page 259 258 Administering Presence Services XCP Controller August 2010 Web Services To verify that the mod_offline_pop module is enabled 1. Change to the controller’s Advanced configuration view. 2. In the Router area on the controller’s main page, click Edit beside Presence Session Manager . 3. In the JSM Configuration page, under Optional modules , ensure that the mod_offline_pop module is enabled as shown in the following figure: 4. If you made any changes, click Submit to save your configuration. InfoBroker The InfoBroker service can create a node and publish information to a node on behalf of a user. To use this service, you must have an InfoBroker component in your XCP server configuration. Related topics: To configure the InfoBroker for Web Services on page 259 To configure the InfoBroker for Web Services 1. Change to the controller’s Intermediate configuration view. 2. In the Components area on the controller’s main page, click Edit beside InfoBroker . 3. In the InfoBroker Configuration page under InfoBroker Administrators , type the ID and realm of the Web Services component in the Administrator(s) box. For example: web-services-1.jabber 4. Click Submit to save your configuration. Invoking Services from a SOAP-over-HTTP Client To invoke Web services from a SOAP-over-HTTP client, the user sends a SOAP-over-HTTP message to the WebCP SOAPHandler; for example, http://user:[email protected]:7336/ soap. User and password must match the username and password that were specified for Web Administering Presence Services XCP Controller August 2010 259 Services Services during the package’s installation. The username and password are stored in $JABBER_HOME/etc/.websvc_passwd. Note: You can modify the password if needed by using the admin password command to access the websvc_passwd file. The WebCP SOAPHandler performs HTTP basic authentication on the message and, if passed, forwards the message to the Web Services component. Web Services Definition Language Files Three Web Service Definition Language (WSDL) files are provided with the Web Services package installation. The WSDL files provide all of the information that a client development environment needs in order to generate the framework to invoke the services. The files are located at: • $JABBER_HOME/htdocs/wsdl/web-services/Messaging.wsdl • $JABBER_HOME/htdocs/wsdl/web-services/RosterPresence.wsdl • $JABBER_HOME/htdocs/wsdl/web-services/InfoBroker.wsdl Assuming that the controller is running and listening on port 7300, you can access these files via HTTP by pointing your browser to, for example: https://server.com:7300/wsdl/web-services/Messaging.wsdl If you have trouble accessing the files through your browser, make sure that you have permissions to access them. 260 Administering Presence Services XCP Controller August 2010 Chapter 20: System Manager Presence Presence administration The presence administration pages of Avaya Aura ™ System Manager allow the administrator to manage: • Presence configuration properties • Presence classes • Presence access levels Presence configuration properties Administering Presence configuration properties 1. Log in to the Avaya Aura ™ System Manager web interface as an administrator. 2. Click Elements > Presence > Configuration in the left navigation pane. You can review all global presence configuration properties on this page. Next steps Modifying a configuration property: 1. Click Edit. 2. Change the value of the property. 3. Click Save. Administering Presence Services XCP Controller August 2010 261 System Manager Related topics: Domain substitution rule on page 262 Domain substitution rule Configuration properties that are currently defined for Domain Substitution Rule. The Domain Substitution Rule defines how to convert a user's Login Name into their Presence Name. The algorithm works as follows: • A user's Login Name is taken and all instances ofDomain Substitution Rule From string are replaced with Domain Substitution Rule To string. So, for example, a rule with @global as Domain Substitution Rule From and @pres as Domain Substitution Rule To will convert a Login Name of [email protected] into Presence Name of [email protected]. • If Domain Substitution Rule Default is defined then all users without a domain in their Login Name will be assigned to this default domain. So, for example, a rule with @default.example.com as Domain Substitution Rule Default will convert a Login Name of mike into Presence Name of [email protected]. Note: Domain Substitution Rule Default can never overlap with Domain Substitution Rule To because the rule must be reversible. Classes Presence classes Presence classes are essentially types of presence information sources. For example, all presence updates from desktop phones are assigned to class Phone, all presence updates from enterprise IM (Instant Messaging) clients are assigned to class Enterprise IM, and so on. The presence classes, once defined, can then be used to define presence access control rules, presence aggregation rules, and so on. Normally, the system comes with a pre-configured set of supported presence classes. However, as new devices are integrated, it might be necessary to add new presence classes. 262 Administering Presence Services XCP Controller August 2010 Presence Viewing Presence classes 1. Log in to the Avaya Aura ™ System Manager web interface as an administrator. 2. Click Elements > Presence > Classes in the left navigation pane. The page displays all currently defined presence classes. Creating Presence classes 1. Log in to the Avaya Aura ™ System Manager web interface as an administrator. 2. Click Elements > Presence > Classes in the left navigation pane. 3. Click Add. 4. Fill in the name of the new class. 5. Click Save. Modifying Presence classes 1. Log in to the Avaya Aura ™ System Manager web interface as an administrator. 2. Click Elements > Presence > Classes in the left navigation pane. 3. Select a row with the class that you want to modify. 4. Click Edit. 5. Change the name of the class. 6. Click Save. Administering Presence Services XCP Controller August 2010 263 System Manager Deleting Presence classes 1. Log in to the Avaya Aura ™ System Manager web interface as an administrator. 2. Click Elements > Presence > Classes in the left navigation pane. 3. Select a row with the class that you want to delete. 4. Click Delete. Access Levels Presence access levels Presence access levels are defined in terms of presence classes. An access level can contain a single presence class or a set of classes. Access rules defined in the Presence ACLs (Access Control Lists) then apply to all classes in an access level. Presence information is partitioned into several areas called presence access levels for the purpose of access control. Examples of presence access levels: • Instant Messaging Presence • Calendar Presence • Telephony • All The All access level is always defined and always includes complete Presence information. Other access levels can be created by administrators as necessary. An access level can also contain an inversion of a set of classes for convenience. In other words, it can be defined to contain all classes that are not in the selected set of classes. This makes it easier to define access levels such as all classes except Phone. Viewing Presence access levels 1. Log in to the Avaya Aura ™ System Manager web interface as an administrator. 2. Click Elements > Presence > Access Levels in the left navigation pane. 264 Administering Presence Services XCP Controller August 2010 Presence The page displays all currently defined presence access levels. Creating Presence access levels 1. Log in to the Avaya Aura ™ System Manager web interface as an administrator. 2. Click Elements > Presence > Access Levels in the left navigation pane. 3. Click Add. 4. Fill in details of the new access level. 5. Click Save. Modifying Presence access levels 1. Log in to the Avaya Aura ™ System Manager web interface as an administrator. 2. Click Elements > Presence > Access Levels in the left navigation pane. 3. Select a row with the access level that you want to modify. 4. Click Edit. 5. Change details of the access level. 6. Click Save. Note: Access level All is predefined and cannot be modified or deleted. Deleting Presence access levels 1. Log in to the Avaya Aura ™ System Manager web interface as an administrator. 2. ClickElements > Presence > Access Levels in the left navigation pane. Administering Presence Services XCP Controller August 2010 265 System Manager 3. Select a row with the access level that you want to delete. 4. Click Delete. Note: Access level All is predefined and cannot be modified or deleted. Presence access level field descriptions The following fields are defined for a presence access level. Name Description Label Unique name of the access level. Classes A set of presence classes that are included in this access level. Adding, removing Presence classes to access level To add presence classes to the access level: 1. Select the new classes in the Available Classes list. 2. Click [>] to include them in the Selected Classes list. Next steps To remove presence classes from the access level: 1. Select the classes in the Selected Classes list. 2. Click [<] to remove them. Note: If you select Match any class but the specified classes then the access level will be assumed to contain all classes that are not in the Selected Classes list. 266 Administering Presence Services XCP Controller August 2010 Access Levels Presence server status Viewing Presence server status 1. Log in to the Avaya Aura ™ System Manager web interface as an administrator. 2. Click Elements > Inventory > Manage Elements in the left navigation pane. 3. Click on the name of the Presence server that you want to check the status of. Next steps • Click Presence Controller: Open to launch the Presence controller GUI for this server (in a separate window). • Click Status: Show to view detailed runtime status information. Access Levels Presence access levels Presence access levels are defined in terms of presence classes. An access level can contain a single presence class or a set of classes. Access rules defined in the Presence ACLs (Access Control Lists) then apply to all classes in an access level. Presence information is partitioned into several areas called presence access levels for the purpose of access control. Examples of presence access levels: • Instant Messaging Presence • Calendar Presence • Telephony • All The All access level is always defined and always includes complete Presence information. Other access levels can be created by administrators as necessary. Administering Presence Services XCP Controller August 2010 267 System Manager An access level can also contain an inversion of a set of classes for convenience. In other words, it can be defined to contain all classes that are not in the selected set of classes. This makes it easier to define access levels such as all classes except Phone. Viewing Presence access levels 1. Log in to the Avaya Aura ™ System Manager web interface as an administrator. 2. Click Elements > Presence > Access Levels in the left navigation pane. The page displays all currently defined presence access levels. Creating Presence access levels 1. Log in to the Avaya Aura ™ System Manager web interface as an administrator. 2. Click Elements > Presence > Access Levels in the left navigation pane. 3. Click Add. 4. Fill in details of the new access level. 5. Click Save. Modifying Presence access levels 1. Log in to the Avaya Aura ™ System Manager web interface as an administrator. 2. Click Elements > Presence > Access Levels in the left navigation pane. 3. Select a row with the access level that you want to modify. 4. Click Edit. 5. Change details of the access level. 6. Click Save. Note: 268 Administering Presence Services XCP Controller August 2010 Access Levels Access level All is predefined and cannot be modified or deleted. Deleting Presence access levels 1. Log in to the Avaya Aura ™ System Manager web interface as an administrator. 2. ClickElements > Presence > Access Levels in the left navigation pane. 3. Select a row with the access level that you want to delete. 4. Click Delete. Note: Access level All is predefined and cannot be modified or deleted. Presence access level field descriptions The following fields are defined for a presence access level. Name Description Label Unique name of the access level. Classes A set of presence classes that are included in this access level. Adding, removing Presence classes to access level To add presence classes to the access level: 1. Select the new classes in the Available Classes list. 2. Click [>] to include them in the Selected Classes list. Next steps To remove presence classes from the access level: Administering Presence Services XCP Controller August 2010 269 System Manager 1. Select the classes in the Selected Classes list. 2. Click [<] to remove them. Note: If you select Match any class but the specified classes then the access level will be assumed to contain all classes that are not in the Selected Classes list. Classes Presence classes Presence classes are essentially types of presence information sources. For example, all presence updates from desktop phones are assigned to class Phone, all presence updates from enterprise IM (Instant Messaging) clients are assigned to class Enterprise IM, and so on. The presence classes, once defined, can then be used to define presence access control rules, presence aggregation rules, and so on. Normally, the system comes with a pre-configured set of supported presence classes. However, as new devices are integrated, it might be necessary to add new presence classes. Viewing Presence classes 1. Log in to the Avaya Aura ™ System Manager web interface as an administrator. 2. Click Elements > Presence > Classes in the left navigation pane. The page displays all currently defined presence classes. 270 Administering Presence Services XCP Controller August 2010 Classes Creating Presence classes 1. Log in to the Avaya Aura ™ System Manager web interface as an administrator. 2. Click Elements > Presence > Classes in the left navigation pane. 3. Click Add. 4. Fill in the name of the new class. 5. Click Save. Modifying Presence classes 1. Log in to the Avaya Aura ™ System Manager web interface as an administrator. 2. Click Elements > Presence > Classes in the left navigation pane. 3. Select a row with the class that you want to modify. 4. Click Edit. 5. Change the name of the class. 6. Click Save. Deleting Presence classes 1. Log in to the Avaya Aura ™ System Manager web interface as an administrator. 2. Click Elements > Presence > Classes in the left navigation pane. 3. Select a row with the class that you want to delete. 4. Click Delete. Administering Presence Services XCP Controller August 2010 271 System Manager 272 Administering Presence Services XCP Controller August 2010 Index A access level field descriptions ...........................266, 269 access level fields .............................................266, 269 access rules ......................................................264, 267 accounts disabling .............................................................169 Active Directory ........................................................161 Active Directory setup ...............................................215 adding an Outgoing Connection Attempt Rule in the S2SCP .........................................................152 adding and configuring an additional Connection Manager ......................................................138 adding Presence classes to access level ..........266, 269 administring Presence ..............................................261 Advanced Performance Tuning options .....................20 attribute reference ....................................................173 Authorization ..............................................................62 Authorization Manager ...............................................74 B blacklisting and whitelisting Hosts and IP Addresses 158 C categories .................................................................110 changing logging levels ..............................................43 cluster .........................................................................17 cnfiguring the OpenPort connection .........................156 Collecting logs ............................................................44 Component level logging examples ...........................44 configuration views in the controller ...........................................11 configuring a database .............................................163 configuring a Directory Server ..................................168 configuring a Directory Server to work with Active Directory ......................................................162 configuring a Server-to-Server Connection Manager 148 configuring an OpenPort connection ........................153 configuring HTTP Digest Module ...............................63 configuring Jabber administrators ............................153 configuring Kerberos for the Presence Services Server ......................................................................215 configuring SNMP ......................................................64 configuring the Active Directory component .............161 Administering Presence Services XCP Controller configuring the Basic S2S Connection Manager ......155 configuring the dialback password ...........................157 configuring the Jabber Directory component ............167 configuring the JSM to use the Active Directory component ...................................................165 configuring the JSM to use the Jabber Directory Component ..................................................172 configuring the OCS Gateway ..................................149 Connection Managers ..............................................137 controller Component area on main page ...........................13 configuration views ...............................................11 Router area on main page ...................................13 creating access levels .......................................265, 268 creating classes ................................................263, 271 creating Presence classes ................................263, 271 D Database setup ..........................................................22 deleting access levels .......................................265, 269 deleting classes .................................................264, 271 deleting Presence classes ................................264, 271 directory servers optimizing ...........................................................174 Discovery Protocol for querying the S2S Command Processor ....................................................159 domain substitution rule ............................................262 downloading license ...................................................78 E enabling SNMP ..........................................................23 enabling StartTLS .......................................................21 EventBroker ................................................................57 example querying for outbound and inbound lists ............159 querying S2CP for all items ................................160 querying the S2SCP for information ...................159 F files transfer requests ...............................................189 August 2010 273 G K global router settings ..................................................16 Kerberos Authentication and Microsoft Active Directory ......................................................................215 I L incoming and outgoing messages ............................188 InfoBroker ..........................................................112, 213 configuring for SDNS .........................................213 InfoBroker Category ..................................................110 InfoBroker component ..............................................112 InfoBroker Configuration ...........................................112 Information Broker Configuration ..............................112 Intra-Domain (Clustered) federation using Single Domain Name Support ................................211 J M Jabber administrators .................................................49 Jabber Directory and LDAP ......................................167 Jabber LDAP attributes ............................................................173 objectClasses .....................................................173 Jabber Session Manager ...........................................47 See also JSM .......................................................47 JDS configuration in JSM ............................................58 JSM agents ..................................................................57 configuring for Message Archiver .......................186 configuring for Presence Mirror ..........................186 configuring for SDNS .........................................212 database setup ....................................................54 features ................................................................56 general configuration ...........................................47 hostnames ...........................................................48 Jabber administrators ..........................................49 JDS configuration .................................................58 legacy redirect to external components ...............57 logging ................................................................186 mirroring presence ...............................................60 optional modules ..................................................48 registration requirements ................................61, 63 roster configuration ..............................................59 sendmail configuration .........................................59 static EventBroker events ....................................57 stats .....................................................................56 system limits ........................................................53 system parameters ..............................................53 JSM Logging ..............................................................62 274 LDAP schema object class and attribute reference .............173 legacy redirection to external components .................57 Licensing Presence Services .....................................78 locating inactive accounts ..........................................50 log level ......................................................................19 logging stats .....................................................................56 through Message Archiver .................................185 Administering Presence Services XCP Controller Master Accept port .....................................................20 MDNS .........................................................................18 Message Archiver .....................................................185 mirroring presence .....................................................60 Mirroring Presence option ........................................186 mod_admin ...........................................................49, 51 mod_agents ................................................................57 mod_auth_digest ........................................................54 mod_auth_plain ..........................................................54 mod_caps ...................................................................63 mod_disco ..................................................................57 mod_eventbroker .......................................................57 mod_jds ......................................................................58 mod_message_archiver ......................................54, 186 mod_offline .................................................................50 mod_offline_smtp .......................................................60 mod_pep ....................................................................63 mod_presence_bcc module .....................................186 mod_presence_mirror ................................................54 mod_redirect ..............................................................57 mod_register ..............................................................61 mod_sendmail ............................................................59 Moderator Definition .................................................228 modifying access levels ....................................265, 268 modifying classes ..............................................263, 271 modifying Presence classes ..............................263, 271 mutually trusted TLS host names ...............................24 N namespaces August 2010 selecting for Message Archiver logging .............185 O object class reference ...............................................173 Obscure Plaintext Passwords ....................................20 OCS Gateway ...........................................................147 Open Port .................................................................191 Open Port Configuration ...........................................191 P parameters .................................................................74 Presence access levels .....................................264, 267 Presence ACLs .................................................264, 267 Presence administration ...........................................261 Presence classes ..............................................262, 270 Presence information sources ...........................262, 270 presence mirroring .....................................................60 Presence server status .............................................267 presence services logging ..........................................42 Presence Session Manager (JSM) .............................47 R realm changing after installation ....................................18 registration requirements ......................................61, 63 removing Presence classes to access level ...... 266, 269 retrieving message archiver data .............................187 roster configuration .....................................................59 Router area ................................................................15 Router-to-Router Connection configuring for JSM and InfoBroker in SDNS setup ...............................................................213 S schema Administering Presence Services XCP Controller object class and attribute reference ...................173 sendmail configuration ...............................................59 Server-to-Server connections ...................................155 Single Domain Name Support configuring for JSM ........................................................212 overview .............................................................211 starting the Presence XCP Controller ..........................9 Statistics Data ............................................................38 substitution rule ........................................................262 system ........................................................................12 T Text Conferencing .....................................................226 U uregistering users .......................................................49 users disabling accounts ..............................................169 using linux ....................................................................9 Using the Presence XCP Controller .............................9 using web access .......................................................10 V verifying connection manager certificates ................137 verifying OCS Gateway certificates ..........................147 view access levels .............................................264, 268 view classes ......................................................263, 270 viewing Log Harvester log ..........................................46 viewing Presence access levels ........................264, 268 viewing Presence classes .................................263, 270 viewing SAL agent log ................................................45 viewing server status ................................................267 viewing system manager alarms ................................46 viewing system manager logs ....................................45 X XCP Controller interface .............................................12 XCP Logging ..............................................................25 August 2010 275
