Requirements  
Prerequisite knowledge Required products
This article assumes you have a basic knowledge of using the CFWEBSOCKET tag, JavaScript, and HTML5 WebSocket. A general understanding of SSL, firewall and otherweb technologies is helpful for getting the most out of this article.

 

User level
All
Adobe ColdFusion Enterprise Edition (2016 release) (Download trial)

 

 
Introduction

While many new features were added to ColdFusion 10, one area that really got lots of reviews was the support for HTML5 WebSocket. WebSocket is a bi-directional, reliable, and scalable client-server communication protocol and is perfect for pushing data from the server to a client in real-time. In ColdFusion 10, the support was added for core WebSocket protocol, channel based messaging framework, CFWEBSOCKET tag, and client side JavaScript functions to communicate to the server.
 
In ColdFusion 11, the WebSocket feature is enhanced further by making it more secure and highly scalable. This article aims to get you familiar with all the new features  added to ColdFusion WebSocket to make it an enterprise-ready solution for real-time messaging.
 

 
WebSocket Enhancement in ColdFusion 11

The WebSocket enhancements in ColdFusion 11 can be grouped in three areas. Each area is meant to improve either the security or the scalability of WebSocket.
 
Here are the three areas of WebSocket enhancements:
 
  1. Proxy support
  2. SSL support
  3. Cluster support

 
Proxy support

ColdFusion uses  a dedicated port (8575)  to start its internal WebSocket Server and listens to a new client request on it. Earlier, in absence of proxy support, this port was required to be always accessible from outside. This set-up is perfectly fine and works well for intranet application. But for a public facing external application, it’s never advisable to keep a port open and let it be accessible from outside. An unprotected port with no firewall placed between server and the internet, puts the whole server at risk and can easily be attacked. Now, with proxy support added in ColdFusion 11, the WebSocket port is no longer required to be exposed to outside world and rather can be configured safely by hiding it behind the firewall.
 
In ColdFusion 11, with proxy configured, a client does not require to connect the server directly and rather it can connect to the proxy instead. The proxy will act as an intermediary and receive the WebSocket request from the client on the server behalf and then redirect it to the server. The best part of this proxy framework is that the same connector, which you generally use for serving HTTP request (a CFM template), is extended to accept the WebSocket request too. You just need to configure the connector to handle WebSocket request. The connector can be configured by following a few steps described in this article.
 
Before we go and configure the proxy, let’s take a look at the following diagram. It shows two strategies of deploying WebSocket Server.
 
WebSocket strategies
Figure 1: WebSocket strategies
 
Any one of the following external servers mentioned can be configured as a proxy with the ColdFusion server for WebSocket request.
 
  • IIS or higher running on Windows 8 or Windows Server 2012
  • Apache 2.2.* on Linux or Windows.
 
Confiiguring Proxy Server
You can configure an IIS or Apache Server as proxy by performing the following steps.
 
 
Step 1- Configure the external server
First step is to enable Websocket protocol to your external server. you need to configure the proxy server as:
 
IIS server: Please, check this document.
 
Apache Server: No configuration required.
 
 
Step 2- Enabling WebSocket Proxy at ColdFusion Administrator.
Perform the following steps:
 
  1. Go to ColdFusion Administrator
  2. Click Server Setting > Web Socket
  3. Click Enable WebSocket Service and select Use Proxy.
Use built-in WebSocket Server
Figure 2: Use built-in WebSocket Server
 
Step 3- Attaching external Web Server to ColdFusion Server
The external Web Server, usually also called a connector, needs to be attached with the ColdFusion Server using the wsconfig tool. Perform the following steps:
 
  1. Go to <CF_INSTALL_HOME>/cfusion/runtime/bin
  2. Run the wsconfig tool
  3. In the GUI, click Add
  4. In the Web Server drop down field, select the external server.
  5. In the Configuration Directory field, browse and select the path to the external server’s configuration directory
  6. Click OK
Add Web Server configuration
Figure 3: Add Web Server configuration
 
  1. If the external server is not running, you will be prompted to start it.
Start the web server
Figure 4: Start the web server
 
  1. Click yes to start the external server
  2. Click Exit
 
Step 4- Setting up the WebSocket proxy Server
  1. Go to <CF_INSTALL_HOME>/cfusion//bin
  2. Run the wsproxyconfig tool
  3. In the GUI, click Add
  4. In the Web Server drop down field, select the external server.
  5. In the Configuration Directory field, browse and select the path to the external server’s configuration directory
Add WebSocket Proxy Configuration
Figure 5: Add WebSocket Proxy Configuration
 
  1. Click OK
  2. If the external server is not running, you will be prompted to start it.
Restart the server
Figure 6: Restart the server
 
  1. Confirm the proxy configuration
WebSocket Proxy Configuration
Figure 7: WebSocket Proxy Configuration
 
  1. Click Close
 
Step 5 – Verify the proxy configuration
Once the WebSocket Proxy is successfully configured, verify that the required proxy files are created at <CF_INSTALL_HOME>/config/wsproxy/1 and a file called config.ini is present there.
 
You can manually modify the setting if required. Also, ensure that a new application, cfws, is created under the application root of the external server.
 
The Set-up is now complete and your proxy is ready to receive and serve WebSocket request at port 80 (or 443 for SSL).
 
 
Step 6 – Tuning proxy configurations
For higher scalability and better performance, it is always advisible to tune the proxy config properties. These properties can be found in config.ini file and are:
 
  1. Connection Pool Size - Connection count between WebSocket proxy module and ColdFusion server WebSocket port. Based on the load, the connection pool size needs to be tuned so that optimal clients are binded with each connection. Default value is 10.
  2. PacketSize -  Based on the message size, the packet size needs to be configured. If application is sending larger messages over WebSocket, the PacketSize needs to be tuned accordingly. Default packet size is 8192 bytes (8KB).
  3. Message Queue Size:- This parameter needs to be tuned based on the message load on the WebSocket connection. Based on the frequency of  messages on the WebSocket connection, this queue size needs to be tuned. Default queue size is 50000 (50K).
 
Step 7 – Logging in WebSocket
Logging needs to be enabled only for debugging purpose. To enable logging at proxy module, open the config.ini and change the EnableLogging to true. And to enable logging at ColdFusion server side change the logging value from warning to debug.
 

 
SSL Support

In ColdFusion 11, WebSocket feature is enhanced to support SSL. SSL, as you might know, is a security protocol to help a client to communicate to the server over a secure channel and vice-varsa. Here, a message is first encrypted and then send to the other end for decryption before it can be meaningfully read. SSL provides a mechanism wherein only a client can decrypt the server data and otherway around. A hacker in no way can read or tamper the data being passed and hence minimizes the security risk while transfering the data.
 
For an enterprise deployment, SSL plays a very important role and become must to have in case you need to host  a sensitive application. In ColdFusion 11, a new attribute  secure is added to CFWEBSOCKET tag which, if set to true, initiates all the server communications, for this particular client,  over a  secure socket (SSL). However, before you start using secure attribute, you need to configure various properties like: SSL port, ceritificates, and keystore to ColdFusion Administrator.
 
 
Setting up SSL support
You first need to set up the SSL properties in ColdFusion Administrator. The WebSocket admin page (Administrator console > Server Setting > WebSocket) has been enhanced to configure following perperties:
 
  • Enable SSL
  • SSL port
  • KeyStore File location
  • KeyStore passward
Enable SSL
Figure 8: Enable SSL
 
Enable SSL: A checkbox to enable Secure Socket Layer (SSL) for running WebSocket over SSL.
 
SSL Port: A numeric value for SSL port. WebSocket will listen on this port for any incoming request. Default value is 8543 which can be changed if required.
 
KeyStore File Location: The location of the keystore in server’s file system. This keystore contains private keys, and the certificates with their corresponding public keys. For instance, the keystore file location is, C:\openSSL\bin\keystore.jks
 
KeyStore passward:  Password to operate the keyStore defined above.
 
Once the SSL is configured, use the secure attribute of cfwebsocket tag as:
 
<cfwebsocket name='webSocketObj'onMessage='messageHandler' secure=true />
The secure attribute tells the server to start the WebSocket-client communication in the SSL mode. If the SSL is not enabled in ColdFusion Adminstrator, as shown above, an error will be  shown to you to start the SSL first before using secure attribute.
 

 
Cluster support

In ColdFusion 11, Cluster support, an another enterprise feature, is added to WebSocket. In multi-instance deployement, where your application runs on various nodes, you would definitely want to keep a client message in sync and get it broadcasted on all the nodes. For instance, when a message is published, rather than just publishing it to the subscribers of that particular node, it should ideally be published to all the subscriber, across the nodes, of the cluster.
 
For example, Node1 has two clients (C1 and C2) subscribed to the “chat” channel. Similarly Node2 has two clients (C3, C4) and Node3 has two clients (C5, C6) also subscribed to the “chat” channel. Now, when client C1 tries to publish a message on the “chat” channel,  rather than just sending this message to C1 and C2 only, the clients from other nodes C3, C4, C5, and C6 must also receive this message.
 
 
Setting up a WebSocket Cluster
You first need to enable the WebSocket cluster in ColdFusion Administrator. Under the WebSocket page in the Administrator, look for “Enable WebSocket Cluster” option (see below figure) and check this checkbox if not already checked.
 
Enable WebSocket Cluster
Figure 9: Enable WebSocket Cluster
 
Once the WebSocker cluster is enabled, make sure that the “Multicast Port” is also defined. It mostly comes configured as 45566 and you don’t need to change it unless this port is not free and being used by some other system. The port is used to broadcast node up/down events. When a node comes up, it needs to intimate its peer about its coming live and joining the cluster. Similarly, when a node is going down, it will first notify its peers about the same before it really become unaccessible.
 
It is important to note that the cluster feature is avaible only in the Enterprise edition of ColdFusion 11. If you are having a standard edition and want to use Cluster then you have to first upgrade your ColdFusion server before you can avail the Cluster functionality.
 
 
Cluster support in JavaScript Function
As described above, the purpose of this feature is to enable a client to publish a message to all its relevant subscribers irrespective of the node they are connected to. The JavaScript functions (publish and subscriber related) that are enhanced to provide cluster functionality are:
 
  • publish
  • getSubscriberCount
  • invokeAndPublish
The cluster support is seemless and does not require any changes in the existing source code. The ColdFusion Server internally figure out if the cluster is enabled and then broadcast a message accordingly. Please refer the WebSocket document if you want to know how to broadcast a message using JavaScript function.
 
 
Cluster support in ColdFusion functions
ColdFusion also provides some in-built function to broadcast a WebSocket message to its subscriber. The following functions are enhanced to auto-support cluster functionality.
 
wsPublish(“channel name”, messageBody [, cluster]) wsGetSubscriber(“channel name” [, cluster] ) wsGetAllChannels(“channel name”[, cluster]);
Like JavaScript function, the cluster support in  the above mentioned functions are seemless. You don’t need to change your code to avail cluster support.  However, a new parameter “cluster” is added to these functions in case you want to control cluster functionallity manually.
 

 
Where to go from here

The goal of this article is to provide a general overview of various WebSocket enterprise features added to the latest version of ColdFusion and thus helping you to use IIS or Apache as proxy to safeguard and protect your underlying WebSocket Server from external attack. It will be nice if you try configuring an IIS or Apache Server at your end to get better understanding on how a WebSocket proxy works. Same is true for SSL and Cluster support also. A basic article on WebSocket is available here. See the ColdFusion 11 documentation for more details on the latest WebSocket features.