17 Configuring the XMPP WebSocket Gateway

About the XMPP WebSocket Gateway

The XMPP WebSocket Gateway enables the Instant Messaging Server to support the WebSocket protocol for XMPP. XMPP over WebSocket is an efficient solution for HTTP access of Instant Messaging Server other than HTTPBind. The Instant Messaging multiplexor enables scaling of TCP client connections and also provides failover to other Instant Messaging Server nodes. These existing capabilities of the multiplexor can be reused when WebSocket client connections are interfaced with it.A web container is used to create WebSocket end-points. These end-points in turn use the multiplexor to connect with the Instant Messaging Server. This is in contrast to HTTPBind or PresenceAPI components, which use component protocol to connect to Instant Messaging Server. The XMPP WebSocket Gateway uses internal multiplexor protocols to connect with Instant Messaging Server. The gateway implements XMPP over WebSocket, as described by RFC 7395.

Figure 17-1 shows that WebSocket clients connect to the Web App using XMPP over WebSocket which connects with the multiplexor, which in turn, connects with the Instant Messaging Server.

Figure 17-1 XMPP WebSocket Gateway Architecture

Description of ''Figure 17-1 XMPP WebSocket Gateway Architecture''

Configuring the XMPP WebSocket Gateway

To enable the XMPP WebSocket Gateway:

1. Install and configure Instant Messaging Server.

2. Run the following command to create a ZIP file for the XMPP WebSocket Gateway application that you can move to another machine or keep locally:

   iwadmin generatezip websocket -c location_of_config_dir/iim.conf.xml -d /tmp/xmpp_websocket.zip
   

   where:

   • The -c option specifies the future location of the configuration file for the WebSocket application.

   • The -d option specifies a destination directory and name for the ZIP file.

   • The ZIP file's directory structure and contents are:

     • /websocket.war

     • /lib/imcli.jar

     • /lib/imconfutil.jar

     • /lib/imcommon.jar

     • /sbin/functions

     • /sbin/imconfutil

     • /config/iim.conf.xml.websocket.template

     • /config/websocket_log4j.conf.template

   • The ZIP file contains:

     • A deployable WAR file (websocket.war) for the WebSocket application.

     • The XWS configuration file template (iim.conf.xml.websocket.template). The configuration file is the same as the one used by the multiplexor and Instant Messaging Server, and uses the same imconfutil command for configuring properties.

     • The log4j template file (websocket_log4j.conf.template).

     • The utility for configuring properties in the iim.conf.xml file (imconfutil).

3. Extract the contents and deploy the websocket.war file to WebLogic Server:

    unzip /tmp/websocket.zip -d /local/websocket_gateway
   

4. Rename the template files:

   cd /local/websocket_gateway
   cp config/iim.conf.xml.websocket.template InstantMessaging_home/config/iim.conf.xml
   cp config/websocket_log4j.conf.template InstantMessaging_home/config/log4j.conf
   

5. Configure the Instant Messaging Server port to which the multiplexor connects:

   iimconfutil -c InstantMessaging_home/config/iim.conf.xml set-prop im_mux.serverport=hostname1:port,hostname2:port
   

6. Modify the configuration properties for logging, monitoring, and so forth:

   imconfutil -c InstantMessaging_home/config/iim.conf.xml set-prop property-name=property-value
   

   See "Managing the XMPP WebSocket Gateway" for more information.

7. Ignore the following imconfutil warning:

   "Warning: Unable to set file permissions in the dir <path-to-config-dir>, due to Null value for key: iim.user/group"
   

   You can manually modify these file permissions.

8. Start the Instant Messaging Server instance to which the iim_mux.serverport is pointing.

   imadmin start server
   

9. Start Weblogic Server on which the websocket.war file is deployed listening on an HTTP port.

   Weblogic_Instance/bin/startWeblogic.sh
   

   The websocket.log file (from log4j.conf) log the details of the Instant Messaging servers that are connected to this XMPP WebSocket Gateway application. The location of websocket.log is configured through log4j.conf. The log4j.conf template has a default logging of INFO level and is turned on by default.

10. Set the initial values for tuning properties for the XMPP WebSocket Gateway.

    For more information, see "Tuning the XMPP WebSocket Gateway".

Configuring XMPP WebSocket Gateway for Server Pool

You can configure the XMPP WebSocket Gateway for high availability. For more information, see "About Multiplexor Failover".

Enabling Secure Communication Between the XMPP WebSocket Gateway and Instant Messaging Server

To ensure secure communication between the XMPP WebSocket Gateway and Instant Messaging Server, you must configure the Gateway to use an encrypted channel. Channel refers to a logical connection between client and server. The channel data is encrypted after the XMPP WebSocket Gateway receives data from the client and before sending it to the server.

• To enable secure communication between the XMPP WebSocket Gateway and Instant Messaging Server:

  imconfutil -c InstantMessaging_home/config/iim.conf.xml set-prop iim_mux.encrypted_channel=true
  

Secure communication between the XMPP WebSocket Gateway and Instant Messaging Server is enabled by default in the websocket_log4j.conf.template file. See "Configuring the XMPP WebSocket Gateway" for more information.

If the server is configured with trusted certificates then you do not need to configure the Gateway as described in "Activating TLS on XMPP WebSocket Gateway". See the topic on setting up TLS for Instant Messaging Server in Instant Messaging Server Security Guide for configuring the server in TLS mode.

Internal (Software) Token:password