test

Sun Java System Instant Messaging 7.2 Administration Guide

Chapter 10 Using the Instant Messaging XMPP/HTTP Gateway

The XMPP/HTTP Gateway provides Instant Messaging access to non-XMPP based clients, such as HTML based clients, and clients behind firewalls that allow HTTP traffic, but don't permit XMPP traffic. The gateway proxies Instant Messaging traffic to the XMPP server on behalf of HTTP clients.

The XMPP/HTTP Gateway is deployed with the Instant Messenger resource files as a webapp on the web container.

This chapter provides information on configuring and maintaining the XMPP/HTTP Gateway in the following sections:

Instant Messaging XMPP/HTTP Gateway Configuration Files

The XMPP/HTTP Gateway uses the following files for configuration:

Configuring the Instant Messaging XMPP/HTTP Gateway

When you run the configure utility after installation, you can choose to deploy the XMPP/HTTP Gateway or not. If enabled, the configure utility creates a default configuration file (httpbind.conf) for the gateway. You can change the configuration by modifying the values in this file. See Appendix B, Instant Messaging XMPP/HTTP Gateway Configuration Parameters in httpbind.conf for a description of httpbind.conf file syntax, file location, and a list of configuration parameters in this file, or refer to the instructions in this section.

In addition, when you choose to deploy the gateway during initial configuration, the configure utility creates a .war file in the im-svr-base/work directory and then deploys this file on the web or application server in the directory you specified for the codebase.

You can also configure the gateway to use a non-default configuration file by modifying the values in web.xml which is deployed with the client resources on the web container.

The instructions in this section assume the gateway configuration file is httpbind.conf. If you are using a non-default configuration file, substitute your configuration file for httpbind.conf in the instructions.

Any time you make a change to httpbind.conf, you will need to restart the XMPP/HTTP Gateway.

This section contains the following instructions:

For instructions on configuring logging for the gateway, see Managing Logging for the XMPP/HTTP Gateway.

ProcedureTo Enable or Disable the Instant Messaging XMPP/HTTP Gateway

You enable the gateway by running the configure utility and then setting a parameter in iim.conf. You can disable the gateway later using tools provided by your web container or application server.

  1. To enable the gateway:

    1. Run the configure utility.

    2. Choose to deploy the gateway when prompted.

      See Chapter 1, Configuring Instant Messaging After Installation for more information.

    3. In iim.conf, set the iim_agent.httpbind.enable parameter to true.

      For example:


      iim_agent.httpbind.enable=true

  2. To disable the gateway, disable the webapp using the tools provided by the web or application server.

ProcedureTo Configure the Number of Concurrent Requests Handled by the XMPP/HTTP Gateway

Before You Begin

Ensure that you are familiar with the JEP 124 draft standard. More information is available at http://www.jabber.org/jeps/jep-0124.html.

  1. Open httpbind.conf.

    See httpbind.conf File Location for information on finding this file.

  2. Set the httpbind.requests parameter to the maximum number of concurrent requests a single client can send to the gateway.

    The default is 2. For example:


    httpbind.requests=2

    The number of concurrent requests a client can make to the gateway. If the value of this parameter is less than the value for the JEP 124 hold attribute in the client request, the value for this parameter will be set to hold+1. Do not set this parameter to 1, as doing so could severely degrade performance. See To Set the JEP 124 hold Attribute for Client Requests to the XMPP/HTTP Gateway and Table B–1 for more information on the httpbind.hold parameter.

  3. Save and close httpbind.conf.

  4. Restart the gateway using the tools provided by the web or application server.

ProcedureTo Set the JEP 124 hold Attribute for Client Requests to the XMPP/HTTP Gateway

Before You Begin

Ensure that you are familiar with the JEP 124 draft standard. More information is available at http://www.jabber.org/jeps/jep-0124.html.

  1. Open httpbind.conf.

    See httpbind.conf File Location for information on finding this file.

  2. Set the httpbind.hold parameter to the maximum value you want the gateway to allow for the hold attribute in the client request.

    The default is 5. For example:


    httpbind.hold=5

    If the hold value sent by the client is greater than the gateway's hold value, the gateway's hold value is used.

  3. Save and close httpbind.conf.

  4. Restart the gateway using the tools provided by the web or application server.

ProcedureTo Specify the Allowed Client Inactivity Time for the XMPP/HTTP Gateway

  1. Open httpbind.conf.

    See httpbind.conf File Location for information on finding this file.

  2. Set httpbind.inactivity parameter to the time in seconds after which you want the gateway to terminate idle connections.

    The default is 180 seconds. For example:


    httpbind.inactivity=180

    If clients do not poll the gateway before this time elapses, the gateway terminates the connection.

  3. Save and close httpbind.conf.

  4. Restart the gateway using the tools provided by the web or application server.

ProcedureTo Set the content-type HTTP Header for the XMPP/HTTP Gateway

  1. Open httpbind.conf.

    See httpbind.conf File Location for information on finding this file.

  2. Set the httpbind.content_type parameter to the content-type you want the gateway to use if the client does not specify one in its initial request.

    The default is text/xml; charset=utf-8. For example:


    httpbind.content_type=text/xml; charset=utf-8

  3. Save and close httpbind.conf.

  4. Restart the gateway using the tools provided by the web or application server.

ProcedureTo Set the Round Trip Delay for the XMPP/HTTP Gateway

The round trip delay is the amount of time, in seconds, you want to allow in addition to time-outs for round trips between gateway and client. This helps to account for network latencies.

  1. Open httpbind.conf.

    See httpbind.conf File Location for information on finding this file.

  2. Set the httpbind.round_trip_delay parameter as required.

    Setting this value too high may degrade performance. The value is in seconds. The default is 1 second. For example:


    httpbind.round_trip_delay=1

    Setting this value too high may degrade performance. Consider the general latency in your network before changing this parameter.

  3. Save and close httpbind.conf.

  4. Restart the gateway using the tools provided by the web or application server.

ProcedureTo Set the Default Time Within Which the XMPP/HTTP Gateway Will Send a Response to the Client

  1. Open httpbind.conf.

    See httpbind.conf File Location for information on finding this file.

  2. Set the httpbind.wait_time parameter as required.

    The client is guaranteed a response from the XMPP/HTTP Gateway within the wait time you designate with this parameter. Consider the speed of your network when setting this parameter. Do not set the value so low that the XMPP/HTTP Gateway is unlikely to be able to send the request in time.

    The value is in seconds. The default is 120 seconds. For example:


    httpbind.wait_time=120

    If the value set for the client is greater than the value for the gateway, the gateway wait time is used.

  3. Save and close httpbind.conf.

  4. Restart the gateway using the tools provided by the web or application server.

ProcedureTo Configure an XMPP/HTTP Gateway in a Instant Messaging Gateway Pool

  1. Open httpbind.conf.

    See httpbind.conf File Location for information on finding this file.

  2. To configure the gateway as part of a deployment with an Instant Messaging gateway pool:

    1. Set the httpbind.pool.support parameter to true:


      httpbind.pool.support=true

    2. Set the httpbind.pool.nodeId parameter to the full URL of the gateway.

      The URL is used as the gateway's nodeId. This nodeId must be unique within the server pool. The gateway uses this nodeId to determine whether it must service a received request or forward the request to another gateway in the pool.

  3. To configure the gateway not to work within a gateway pool, set the httpbind.pool.support parameter as follows:


    httpbind.pool.support=false

  4. Save and close httpbind.conf.

  5. Restart the gateway using the tools provided by the web or application server.

ProcedureTo Configure the List of Key IDs for Supported XMPP/HTTP Gateway Domains

  1. Open httpbind.conf.

    See httpbind.conf File Location for information on finding this file.

  2. Set the httpbind.config parameter to the list of IDs you want the gateway to use.

    For each domain you need to specify a separate ID for this parameter. For example:


    httpbind.config=gwdomain-id

    Where gwdomain-id is the identifier you want to use for the domain.

    For example:


    httpbind.config=siroe.com

  3. For each gwdomain-id you specify, add the following parameters to the httpbind.conf file:


    gwdomain-id.domain=domain-name
gwdomain-id.hosts=gateway-host
gwdomain-id.componentjid=component-jid
gwdomain-id.password=password

    Where:

    • gwdomain-id is the ID specified for the gateway in httpbind.config in the previous step.

    • domain-name is the domain in which the identified gateway runs.

    • gateway-host is a comma-separated or space-separated list of the fully-qualified domain name (FQDN) and port number of the gateway hosts that support this domain.

    • component-jid is the component JID of the gateway.

    • password is the password of the identified gateway.

    For example, if the gwdomain-id is set to siroe:


    siroe.domain=siroe.com
siroe.hosts=gateway.siroe.com:5222
siroe.componentjid=http.gateway.siroe.com
siroe.password=gatewaypassword

    See Gateway Domain ID Key Parameters for httpbind.config for more information about these key parameters.

  4. Save and close httpbind.conf.

  5. Restart the gateway using the tools provided by the web or application server.

ProcedureTo Configure the Instant Messaging XMPP/HTTP Gateway to Use a Non-default Configuration File

  1. On the web container on which Instant Messenger resource files are deployed, edit web.xml.

    Use your web container's tools to edit this file.

  2. Change the value for the httpbind.config.file parameter to the location of the configuration file you want the gateway to use.

Securing Communication Between the XMPP/HTTP Gateway and Instant Messaging Server Using StartTLS

The XMPP/HTTP Gateway only supports StartTLS for secure communications. If the multiplexor is configured to use legacy SSL, you need to configure the gateway to connect directly to the server, bypassing the multiplexor. The gateway will always attempt to use StartTLS if it is available. See Chapter 12, Securing Instant Messaging Using TLS and Legacy SSL for more information.

Managing Logging for the XMPP/HTTP Gateway

You can configure the level of logging for the XMPP/HTTP Gateway, enable or disable logging entirely, and change the location of the gateway log file or the gateway log configuration file as described in the following sections:

More information about the log4j format supported by Instant Messaging's is described at the Apache Logging Services website.

ProcedureTo Enable or Disable Logging for the XMPP/HTTP Gateway

You can enable or disable logging for the gateway in two ways:

Under most circumstances, you should modify the configuration in the httpbind_log4j.conf file itself, leaving the httpbind.log4j.config parameter set to the location of the httpbind_log4j.conf file. This procedure describes modifying the configuration within the httpbind_log4j.conf file.

  1. Open the httpbind_log4j.conf file.

    This file is stored at the location you specified in httpbind.conf file as the value for the httpbind.log4j.config parameter. By default the file is stored in the following directory under the default Instant Messaging instance:


    im-cfg-base/httpbind_log4j.conf

  2. To disable logging for the gateway, set the log4j.logger.gateway parameter as follows:


    log4j.logger.gateway=OFF

  3. To enable logging, set the log4j.logger.gateway parameter to the desired logging level.

    For example:


    log4j.logger.gateway=ERROR

    See Table 13–1 for a list of valid logging levels you can use.

  4. Save and close httpbind_log4j.conf.

ProcedureTo Change the Location of the XMPP/HTTP Gateway Log Configuration File

  1. Open httpbind.conf.

    See httpbind.conf File Location for information on finding this file.

  2. Set the value of the httpbind.log4j.config parameter to the location of the XMPP/HTTP Gateway log configuration file.

  3. Save and close httpbind.conf.

  4. Restart the gateway using the tools provided by the web or application server.

ProcedureLinux: To Set the Location of the XMPP/HTTP Gateway Log File After Install or Upgrade

On Linux, after you install and configure the XMPP/HTTP Gateway, you need to modify the location of the default log file for the XMPP/HTTP gateway in httpbind_log4j.conf.

  1. Open the httpbind_log4j.conf file.

    This file is stored at the location you specified in httpbind.conf file as the value for the httpbind.log4j.config parameter. By default the file is stored in the following directory under the default Instant Messaging instance:


    im-cfg-base/httpbind_log4j.conf

  2. Set the value of the log4.appender.appender_ID.file parameter to the location where log files are stored.

ProcedureTo Change the Location of the XMPP/HTTP Gateway Log File

Before You Begin

Ensure that you are familiar with the log4j syntax and general implementation described at the Apache Logging Services website.

  1. Open httpbind_log4j.conf.

    This file is stored at the location you specified in httpbind.conf file as the value for the httpbind.log4j.config parameter. By default the file is stored in the following directory under the default Instant Messaging instance:


    im-cfg-base/httpbind_log4j.conf

  2. Set the value for the log4j.appender.appender-ID parameter to the location where you want to store the log file.

  3. Save and close httpbind_log4j.conf.

  4. Restart the web container.

ProcedureTo Use a Non-default Log File Location for the XMPP/HTTP Gateway

If you choose to use a location for logs other than the default, you need to modify the location of the default log file for the XMPP/HTTP gateway in httpbind_log4j.conf.

  1. Open the httpbind_log4j.conf file.

    This file is stored at the location you specified in httpbind.conf file as the value for the httpbind.log4j.config parameter. By default the file is stored in the following directory under the default Instant Messaging instance:


    im-cfg-base/httpbind_log4j.conf

  2. Set the value of the log4.appender.appender_ID.file parameter to the location where log files are stored.

ProcedureTo Set the XMPP/HTTP Gateway Logging Level

Before You Begin

Ensure that you are familiar with the log4j syntax and general implementation described at the Apache Logging Services website.

  1. Open httpbind_log4j.conf.

    This file is stored at the location you specified in httpbind.conf file as the value for the httpbind.log4j.config parameter. By default the file is stored in the following directory under the default Instant Messaging instance:


    im-cfg-base/httpbind_log4j.conf

  2. Set the log4j.logger.gateway parameter to the desired logging level.

    For example:


    log4j.logger.gateway=ERROR

    See Table 13–1 for a list of valid logging levels you can use.

XMPP/HTTP Gateway log4j Log Configuration File Syntax

For more information about the log4j syntax and general implementation, see the Apache Logging Services website. The gateway log configuration file syntax is as follows.


log4j.logger.gateway=logging-level, Appender-ID
# DEFAULT TO RollingFileAppender
log4j.appender.Appender-ID=org.apache.log4j.RollingFileAppender
log4j.appender.Appender-ID.file=log-dir/httpbind.log
log4j.appender.Appender-ID.append=true|false
log4j.appender.Appender-ID.maxBackupIndex=7
log4j.appender.Appender-ID.maxFileSize=max-log-file-size
log4j.appender.Appender-ID.layout=org.apache.log4j.PatternLayout
log4j.appender.Appender-ID.layout.ConversionPattern=log-entry-syntax
Example 10–1 XMPP/HTTP Gateway Log Configuration File (httpbind_log4j.conf)


log4j.logger.gateway=ERROR, A1
# DEFAULT TO RollingFileAppender
log4j.appender.A1=org.apache.log4j.RollingFileAppender
# log4j.appender.A1.file=$(logdir)/gateway.log
log4j.appender.A1.file=/tmp/gatewaylog
log4j.appender.A1.append=true
log4j.appender.A1.maxBackupIndex=7
log4j.appender.A1.maxFileSize=5mb
log4j.appender.A1.layout=org.apache.log4j.PatternLayout
log4j.appender.A1.layout.ConversionPattern=[%d{DATE}] %-5p %c [%t] %m%n