This chapter describes how to configure the HTTPBIND Gateway for Oracle Communications Instant Messaging Server.
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 does not permit XMPP traffic. The gateway proxies Instant Messaging traffic to the XMPP server on behalf of HTTP clients.
The XMPP/HTTP Gateway is deployed as a web application on the web container.
The XMPP/HTTP Gateway uses the following files for configuration:
Gateway web application configuration file (web.xml). The contents of this file determine which gateway configuration file to use. See "Configuring the XMPP/HTTP Gateway to Use a Non-default Configuration" for information on using a non-default configuration file.
Gateway configuration file (typically httpbind.conf). See "Configuring the Instant Messaging Server XMPP/HTTP Gateway" for instructions on configuring the gateway. See "XMPP and HTTP Gateway Configuration Parameters" for a description of httpbind.conf file syntax, file location, and a list of configuration parameters in this file.
Gateway logging configuration file (typically httpbind_log4j.conf). See "Managing Logging for the XMPP/HTTP Gateway" for more information on configuring logging. See "XMPP/HTTP Gateway log4j Log Configuration File Syntax" for logging configuration file syntax.
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 "XMPP and HTTP Gateway Configuration Parameters" 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 InstantMessaging_home/work directory and then deploys this file on GlassFish Server in the directory you specified for the code base.
You can also configure the gateway to use a non-default configuration file by modifying the values in the web.xml file, which is deployed with the client resources on the GlassFish Server.
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.
See "Managing Logging for the XMPP/HTTP Gateway" for instructions on configuring logging for the gateway.
You enable the gateway by running the configure utility. You can disable the gateway later by using GlassFish Server tools.
To enable or disable the XMPP/HTTP gateway:
To enable the gateway:
Invoke the configure utility.
For more information, see the topic on configuring Instant Messaging Server after installation in Instant Messaging Server Installation and Configuration Guide.
Choose to deploy the gateway when prompted.
To disable the gateway, use GlassFish Server tools to disable the web application.
The high-level steps to manually configure HTTPBIND include:
Configuring HTTPBIND
Configuring GlassFish Server
Configuring Instant Messaging Server
Deploying HTTPBIND
To manually configure HTTPBIND:
Run the iwadmin command to generate the zip file for HTTPBIND.
iwadmin generatezip httpbind -c /opt/sun/comms/im/config/httpbind.conf -d /tmp/httpbind.zip
See "iwadmin Command Reference" for more information.
Unzip the generated zip file.
unzip /tmp/httpbind.zip -d /tmp/
Copy the config template file from the zipped folders's config directory to the config directory of httpbind. In the following example, /opt/sun/comms/im/config is the config directory of httpbind.
cp /tmp/httpbind/config/httpbind.conf.template /opt/sun/comms/im/config/httpbind.conf
Copy the log template file of httpbind to the config directory
cp /tmp/httpbind/config/httpbind_log4j.conf.template /opt/sun/comms/im/config/httpbind_log4j.conf
See "Managing Instant Messaging Server Logging by Using log4j" for log-related configurations.
Edit the httpbind.conf file (by default, located in the /opt/sun/comms/im/config directory) to set the following properties:
Domain: default.domains=abc.com
Multihosting to false: default.multihosting=false
Host name and port of Instant Messaging Server host: default.hosts=example.com:5269
Component jid of httpbind: default.componentjid=httpbind.abc.com
Password: default.password=password
To set the password in plain text, comment out the following parameters:
#httpbind.component.password.cipher.delegate=DELEGATE_CLASS #httpbind.component.password.cipher=CIPHER_CLASS
See "Using Encrypted Passwords" to use encrypted passwords.
Set the path to the log4j file used by HTTPBIND:
httpbind.log4j.config=/opt/sun/comms/im/config/httpbind_log4j.conf
See the following sections for additional HTTPBIND-related configuration settings.
To configure GlassFish Server for HTTPBIND, on the GlassFish Server, enable Comet support:
asadmin set --user admin --secure=true --host localhost --port 4848 'server.http-service.http-listener.http-listener-1.property.cometSupport=true' asadmin set --user admin --secure=true --host localhost --port 4848 'server.http-service.http-listener.http-listener-2.property.cometSupport=true'
Run the following commands to configure Instant Messaging Server:
imconfutil -u set-listener-prop -c InstantMessaging_home/config/iim.conf.xml s2s protocols=s2s,component,c2s imconfutil -u set-prop -c InstantMessaging_home/config/iim.conf.xml iim_server.useport=true imconfutil add-component -c InstantMessaging_home/config/iim.conf.xml id=httpbind1 jid=httpbind.abc.com password=password
Ensure that the jid and password match with the ones that you previously configured in the httpbind.conf file.
To deploy HTTPBIND, deploy the httpbind.war file, from the unzipped httpbind.zip file previously generated, to Glassfish Server.
Restart GlassFish Server.
Restart Instant Messaging Server.
When you manually configure HTTPBIND, ensure that the files in the config directory, and encryption key files if you are using password encryption, have read permissions set for GlassFish Server. When you run the configure utility, the utility ensures that the permissions are correct when you configure HTTPBIND.
Ensure that you are familiar with the JEP 124 draft standard.
To configure concurrent requests handled by the XMPP/HTTP gateway:
Open httpbind.conf.
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
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 "Setting the JEP 124 hold Attribute for Client Requests to the XMPP/HTTP Gateway" and Table 34-1, "XMPP/HTTP Gateway Configuration Parameters in httpbind.conf" for more information on the httpbind.hold parameter.
Save and close httpbind.conf.
Restart the gateway by using the tools provided by GlassFish Server.
Ensure that you are familiar with the JEP 124 draft standard.
To set the JEP 124 hold attribute for client requests to the XMPP/HTTP gateway:
Open httpbind.conf.
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.
Save and close httpbind.conf.
Restart the gateway by using the tools provided by GlassFish Server.
To specify allowed client inactivity time for the XMPP/HTTP gateway:
Open httpbind.conf.
Set the 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.
Save and close httpbind.conf.
Restart the gateway by using the tools provided by GlassFish Server.
To set the content-type HTTP header for the XMPP/HTTP gateway:
Open httpbind.conf.
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
Save and close httpbind.conf.
Restart the gateway by using the tools provided by GlassFish Server.
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.
To set the round trip delay for the XMPP/HTTP gateway:
Open httpbind.conf.
Set the httpbind.round_trip_delay parameter as required. Setting this value too high might degrade performance. The value is in seconds. The default is one 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.
Save and close httpbind.conf.
Restart the gateway by using the tools provided by the GlassFish Server.
To set the XMPP/HTTP gateway default response time:
Open httpbind.conf.
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.
Save and close httpbind.conf.
Restart the gateway by using the tools provided by GlassFish Server.
To configure an XMPP/HTTP gateway in a gateway pool:
Open httpbind.conf.
To configure the gateway as part of a deployment with an Instant Messaging Server gateway pool:
Set the httpbind.pool.support parameter to true:
httpbind.pool.support=true
Set the httpbind.pool.nodeId parameter to the full URL of the gateway.
The URL is used as the gateway's nodeId. The nodeId must be unique within the server pool. The gateway uses the nodeId to determine whether it must service a received request or forward the request to another gateway in the pool.
To configure the gateway not to work within a gateway pool, set the httpbind.pool.support parameter as follows:
httpbind.pool.support=false
Save and close httpbind.conf.
Restart the gateway by using the tools provided by GlassFish Server.
To configure the list of key IDs for supported XMPP/HTTP gateway domains:
Open httpbind.conf.
Set the httpbind.config parameter to the list of IDs you want the gateway to use.
For each domain you must 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
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 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.
Save and close httpbind.conf.
Restart the gateway by using the tools provided by GlassFish Server.
To configure a non-default configuration for the XMPP/HTTP gateway:
On the web container, edit web.xml.
Use your web container's tools to edit this file.
Change the value for the httpbind.conf file parameter to the location of the configuration file you want the gateway to use.
You can assign encrypted passwords to XMPP/HTTP gateway domains listed in the httpbind.conf file.
To assign an encrypted password to a gateway:
Open the httpbind.conf file and set the httpbind.component.password properties:
httpbind.component.password.cipher.delegate=com.sun.im.tools.passwordtool.Crypto httpbind.component.password.cipher=com.sun.im.tools.passwordtool.CommsClientCipher
From the directory containing the httpbind.conf file, generate a password key and password using the Instant Messaging Server passwordtool command.
See "passwordtool Command Reference" for more information.
For example, the following commands generate an encrypted password from the clear text password abcd:
cd httpbind_config_dir
passwordtool httpbind generate-key
passwordtool httpbind generate abcd
MmHRfLCIB0ej5KGDqLC45Q==
In the httpbind.conf file, set the gwdomain-id.password property to the encrypted password, as in the following example.
The gateway ID is siroe.
siroe.password=MmHRfLCIB0ej5KGDqLC45Q==
The gwdomain-id.multihosting parameter in the httpbind.conf file, if set to true, allows a packet destined to a domain, which is not preconfigured in httpbind.conf, to be sent to Instant Messaging Server. You use this parameter for a hosted domain setup. The default value for this parameter is true.
The XMPP/HTTP Gateway only supports StartTLS for secure communications. The gateway always attempts to use StartTLS if it is available. See Instant Messaging Server Security Guide for more information.
This section describes configuring the level of logging for the XMPP/HTTP Gateway, enabling or disabling logging entirely, and changing the location of the gateway log file or the gateway log configuration file.
For more information about the log4j format supported by Instant Messaging Server, see the Apache Logging Services website, at:
You can enable or disable logging for the gateway in the following ways:
Adding or removing the value for the httpbind.log4j.config parameter in httbind.conf.
(Recommended) Modifying the configuration within the gateway's log4j configuration file (httpbind_log4j.conf).
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.
To enable or disable logging for the XMPP/HTTP gateway:
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 Server instance:
InstantMessaging_cfg/httpbind_log4j.conf
To disable logging for the gateway, set the log4j.logger.httpbind parameter as follows:
log4j.logger.httpbind=OFF
To enable logging, set the log4j.logger.httpbind parameter to the desired logging level.
For example:
log4j.logger.httpbind=ERROR
See Table 14-1, "Logging Levels for Instant Messaging Server Components" for a list of valid logging levels you can use.
Save and close httpbind_log4j.conf.
To change the location of the XMPP/HTTP gateway log configuration file:
Open httpbind.conf.
Set the value of the httpbind.log4j.config parameter to the location of the XMPP/HTTP Gateway log configuration file.
Save and close httpbind.conf.
Restart the gateway by using the tools provided by GlassFish Server.
On Linux systems, after you install and configure the XMPP/HTTP Gateway, you must modify the location of the default log file for the XMPP/HTTP gateway in httpbind_log4j.conf.
To set the XMPP/HTTP gateway log file location on Linux:
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 Server instance:
InstantMessaging_cfg/httpbind_log4j.conf
Set the value of the log4.appender.appender_ID.file parameter to the location where log files are stored.
Ensure that you are familiar with the log4j syntax and general implementation described at Apache Logging Services, at:
To change the location of the XMPP/HTTP gateway log file:
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 Server instance:
InstantMessaging_cfg/httpbind_log4j.conf
Set the value for the log4j.appender.appender-ID parameter to the location where you want to store the log file.
Save and close httpbind_log4j.conf.
Restart the web container.
If you choose to use a location for logs other than the default, you must modify the location of the default log file for the XMPP/HTTP gateway in httpbind_log4j.conf.
To use a non-default log file location for the XMPP/HTTP gateway:
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 Server instance:
InstantMessaging_cfg/httpbind_log4j.conf
Set the value of the log4.appender.appender_ID.file parameter to the location where log files are stored.
Ensure that you are familiar with the log4j syntax and general implementation described at Apache Logging Services, at:
To set the XMPP/HTTP gateway logging level:
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 Server instance:
InstantMessaging_cfg/httpbind_log4j.conf
Set the log4j.logger.httpbind parameter to the desired logging level.
For example:
log4j.logger.httpbind=ERROR
See Table 14-1, "Logging Levels for Instant Messaging Server Components" for a list of valid logging levels you can use.
For more information about the log4j syntax and general implementation, see Apache Logging Services at:
The XMPP/HTTP Gateway log configuration file syntax is as follows.
log4j.logger.httpbind=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
The following is an example of an XMPP/HTTP Gateway log configuration file:
log4j.logger.httpbind=ERROR, A7
# DEFAULT TO RollingFileAppender
log4j.appender.A7=org.apache.log4j.RollingFileAppender
# log4j.appender.A7.file=$(logdir)/httpbind.log
log4j.appender.A7.file=_log-dir_/httpbind.log
log4j.appender.A7.append=true
log4j.appender.A7.maxBackupIndex=7
log4j.appender.A7.maxFileSize=5mb
log4j.appender.A7.layout=org.apache.log4j.PatternLayout
log4j.appender.A7.layout.ConversionPattern=[%d{DATE}] %-5p %c [%t] %m%n