Sun Java System Instant Messaging 7.2 Administration Guide

Chapter 7 Optimizing an Instant Messaging Server Pool Using the Redirect Server

Use the redirect service that ships with Instant Messaging to balance the load between servers in a server pool (multi-node deployment). Performance is directly impacted by the amount of communication required between servers in a single deployment, so by increasing the probability that two users who will likely share presence information and messages end up on the same node, you improve performance.

This chapter contains information about using the Instant Messaging redirect server in the following sections:

Overview of Instant Messaging Redirect

The redirect server is an Instant Messaging server instance configured specifically to perform redirect tasks such as assigning connection end-points to Instant Messaging servers. Adding a redirect server to your deployment reduces the amount of communication between servers by grouping users who are likely to communicate with each other on the same host. This reduces the amount of presence notifications sent back and forth between servers in your deployment. Groups of users are determined by contact list contents. Shared entries in contact lists indicate a higher likelihood for communication.

Instant Messaging User Partitioning Algorithm

Instant Messaging determines the best division between users in your deployment and creates groups or partitions of users. The algorithm Instant Messaging uses is as follows:

  1. Determine one or more sets of users, or user network, and their connections in your deployment. The redirect server then creates a table called the user-to-network map that maps each user to a user network.

  2. Partition user networks that are larger than the maximum partition size along weakest ties, such that the maximum size of each weakly connected component is no larger than the configured partition size. Weak ties may be determined by a low number of connections between user networks, however, other parameters such as geographic constraints, number of connections per user network, and other constraints set by administrators may also be taken into account when partitioning user networks.

  3. Distribute the sets into a specified number of partitions of roughly equal size. The redirect server first creates the network-to-partition table as part of this process and finally the user-to-partition table. These tables together make up the redirect database. The redirect database maps each user with a partition ID. You create and manage this database using the rdadmin command line utility.

Example 7–1 Instant Messaging Redirect Sequence of Events

This example describes the sequence of events that occur for a successful client redirect to take place.

  1. Administrator runs rdadmin to generate and/or update the redirect database.

  2. User connects to the redirect server and attempts to authenticate.

  3. Redirect server determines the identity of the user and looks up the corresponding user ID in the redirect database.

  4. If the redirect server does not find the user ID in the redirect database, the redirect server contacts the next redirect server (determined by a round-robin mechanism) to locate the redirect database that contains the user ID. If the user ID is found in the redirect database, the redirect server obtains the partition ID to which the user has been assigned.

  5. Redirect server determines the node to which the user will be redirected based on the assigned partition ID.

  6. Redirect server returns an error to the client that contains the node to which it is being redirected and closes the connection to the client.

    The redirect server uses the see-other-host stream error to return this information to the client. See RFC 3920 for more information.

  7. The client interprets the error and establishes a connection to the node returned with the error.

  8. Redirect server continuously monitors nodes and updates its partition-to-host table as required.

About the Instant Messaging Redirect Database

The database includes only local users. Gateways, components, and remote users are not included in the redirect database.

Instant Messaging Redirect Server Overview

The redirect server is an instance of the Instant Messaging server whose sole function is to redirect client connections. The redirect server does not perform any other service to end users. Upon startup, the redirect server loads the server configuration and partitions file and creates the following data structures:

The redirect server uses both data structures to redirect client connections. See Example 7–1 for an explanation of how the redirect server uses this information.

Instant Messaging Redirect Server and StartTLS

As much of the StartTLS negotiation as is required to establish the identity of the connecting client may take place between the client and the redirect server. The client does not need to verify credentials, instead it only requires the user ID.

Configuring an Instant Messaging Server Instance as a Redirect Server

To specify that a server instance is a redirect server, you need to provide a value for the iim_server.redirect.provider parameter in iim.conf. Once you have designated the instance as a redirect server, you will need to provide further configuration information by specifying values for additional redirect-specific parameters in iim.conf. Table 7–1 describes the redirect configuration parameters.

Table 7–1 Redirect Server Configuration Parameters in iim.conf


Default Value 




Comma-separated list of redirect provider names or classes that implement the interface. Any value for this parameter defines the server instance as a redirect server. Supported values include db, roundrobin, regex, and class names that implement the interface.


Comma-separated list of nodes to which this redirect server may redirect client connections. Node names can be any alphanumeric string. This list may be a superset of the hosts defined in


Where nodename is the name of the node as it exists in This attribute is required for nodename to be used by the redirect server.


If true, then nodename is configured to use legacy SSL. See Overview of Using TLS and Legacy SSL in Instant Messaging for more information.



Name and location of the redirect database. 



Name and location of the redirect partitions file. 



The maximum number of users in a partition. 



Name and location of the redirect partitions file. 



The interval between connections made by the redirect server to the hosts defined in the redirect.hosts file. The redirect server polls these hosts to determine if they are online and able to accept client connections.

ProcedureTo Configure an Instant Messaging Server as a Redirect Server

Before You Begin

You cannot use versions of Instant Messenger older than 2006Q1 with the redirect server. If you use a third party client, ensure that the client supports XMPP redirection.

  1. Gather the information in Table 7–1 above.

  2. Open iim.conf.

    See Appendix A, Instant Messaging Configuration Parameters in iim.conf for instructions on locating and modifying this file.

  3. Modify the parameter values to match your deployment.

    Table 7–1 lists the parameters for which you need to provide values. If the parameters do not exist in iim.conf, add them. The following example shows the section of iim.conf on corresponding to the redirect server parameters you need to modify.

  4. Save your changes and close iim.conf.

  5. Refresh the configuration on the redirect server.

    imadmin refresh server
  6. Configure clients to connect to the redirect server instead of the multiplexor.

Administering the Instant Messaging Redirect Server

Information about administering the Instant Messaging redirect server is described in the following sections:

Stopping, Starting, Restarting, Refreshing, and Checking the Status of the Instant Messaging Redirect Server

The redirect server is an Instant Messaging server instance that has been configured only to redirect. Use the same procedures for stopping, starting, restarting, refreshing, and checking status that you use for a normal server instance. For example, to start the redirect server, you would type:

imadmin start server

See Stopping, Starting, Refreshing, and Checking Instant Messaging Components for more information.

Instant Messaging Redirect Server Logging

The redirect server is an Instant Messaging server instance that has been configured only to redirect. Use the same instructions and logs that you use for a normal server instance. See Chapter 13, Managing Logging for Instant Messaging for more information.

Setting the Partition Size for the Instant Messaging Redirect Server

You can specify the maximum partition size by setting the iim_server.redirect.db.partitionsize parameter in iim.conf. The value for this parameter is equal to the number of users allowed per partition. The default is 5000 (users).

Specifying the List of Partitions for the Instant Messaging Redirect Server

The redirect.partitions file defines the primary node to which users in a particular partition will be redirected and a series of fallback nodes if desired. Each non-empty, non-commented line in the file defines the node list for a partition. Each node in the list must correspond to a node defined as a value for the parameter in iim.conf. If there are more partitions defined than there are lines in the redirect.partitions file, the unspecified partitions are handled by round-robin.

By default, the redirect.partitions file is stored in the following location:


Example 7–2 Redirect.partitions File Configuration

This redirect.partitions file example assumes the following:

In this scenario, redirect.partitions might look as follows:

imserverA, imserverB, imserverC
imserverB, imserverC

That there are two non-empty, non-commented lines indicates that there are at least two user partitions. The first line defines the redirect behavior for partition 1. The redirect server will redirect partition 1 users first to imserverA. If that fails, the redirect server tries imserverB then imserverC. If no nodes are operational, the redirect server returns an error to the client.

Creating and Managing the Instant Messaging Redirect Table Using the rdadmin Utility

Typically, you use the rdadmin utility on an as-needed basis. You do not need to regenerate the table frequently as roster changes are not generally high-volume. However, you should run the utility at least once every two weeks.

ProcedureTo Create a New or Update an Existing Instant Messaging Redirect Database

  1. Stop the redirect server:

    imadmin stop redirect
  2. If you are updating an existing redirect database, obtain the number of partitions previously created by rdadmin:

    1. Open rdadmin.log in a text editor.

      The rdadmin.log file is stored in:

    2. Find the value for “NO OF PARTITIONS RUN”.

  3. Ensure you have at least as many user entries as partitions.

  4. Generate the new redirect database:

    For example:

    rdadmin generate

    See the rdadmin man page for additional rdadmin options.

    The rdadmin utility creates the new database and saves it as im-db-base/ unless you specify a different name.

  5. If you are generating the redirect database for the first time, rename the database as redirect.db.

  6. If you are updating an existing redirect database, replace the old redirect database with the new one:

    For example:

    rm im-db-base/redirect.db
    cp im-db-base/ im-db-base/redirect.db
  7. Start the redirect server:

    imadmin start redirect

Instant Messaging Redirect Server Physical Host Monitoring

The redirect server monitors the operational status of the hosts to which it redirects clients. If the redirect server determines that one of the hosts has failed, it reallocates partitions to subsequent hosts as defined in the redirect.partitions file. In addition, the redirect server detects when a host comes back online so that partitions can be redirected back to the host. The redirect server monitors hosts in two ways:

Procedure Setting the Instant Messaging Redirect Server Host Polling Frequency

  1. On the redirect server, open iim.conf.

    See Appendix A, Instant Messaging Configuration Parameters in iim.conf for instructions on locating and modifying this file.

  2. Set the iim_server.redirect.pollfrequency parameter.

    The value is in minutes. For example:

  3. Save and close iim.conf.

  4. Refresh the redirect server.

    imadmin refresh server

Instant Messaging Redirect Server Best Practices and Troubleshooting

Best practices for using the Instant Messaging redirect server as well as troubleshooting information are described in the following sections:

Redirect Server Certificates

In a deployment that uses certificates for secure authentication, clients may be prompted to accept two certificates every time they connect; one for the redirect server and one for the host to which the client is redirected. To avoid this, use a trusted certificate or the same certificate on both servers.

Instant Messaging Redirect Server Supported Clients

Redirect will not work for clients that do not support RFC 3920 and the see-other-hosts stream error (XMPP redirect) in particular. You can use Instant Messenger 2006Q1 or later with the redirect server. If you use a third party client, ensure that the client that supports XMPP redirection.

Using Redirect Server and Storing User Properties in LDAP

If you are using LDAP to store user properties, that is the, you need to ensure that the values for iim_ldap.usergroupbinddn and iim_ldap.usergroupbindcred have Directory Manager level access to the directory.

Determining the Partition Size for the Redirect Database

The partition size should be as large as possible to avoid having to split user networks wherever possible. However, partitions should also not be larger than that which the smallest system can support.

Using a Redirect Server as a Partition Host

It is possible for a redirect server to also host one or more partitions. You do this by listing the redirect server instance in the redirect.partitions file or as a value for the parameter. However, you should not make more than one redirect server a partition host because unsynchronized redirect.partitions files may cause redirection loops.