In many cases it is not possible to establish a connection between JMS clients and a SwiftMQ Router if one part stands behind a firewall. Usually it exists a proxy server to which it is allowed exclusively to establish an internet connection by a firewall.
To avoid this fact, an operation called HTTP tunneling is used. This document describes the implementation and the setup of the HTTP tunneling with SwiftMQ.
How SwiftMQ implements HTTP Tunneling
When a HTTP connection is made through a proxy server, the client
(usually the browser) sends the request to the proxy. The proxy opens
the connection to the destination, sends the request, receives the
response and sends it back to the client. The HTTP protocol specifies a
request method called
CONNECT method can be used by the
client to inform the proxy server that a connection to some host on some
port is required. The proxy server, if it allows such connections, tries
to connect to the destination address specified in the requested header.
If the operation fails, it sends a negative HTTP response back to the
client and closes the connection. If the operation succeeds, it sends
back an HTTP positive response and the connection is considered
established. After that, the proxy does not care what data is
transferred between the client requesting the connection and the
destination. It just forwards data in both directions, acting as a
Implementations of these tunneling features are commonly referred to as "SSL tunneling" because HTTPS is implemented in this way, although, it can be used for tunneling any TCP based protocol.
With SwiftMQ it is possible to tunnel plain socket and TLS connections via HTTP.
Setting up HTTP Tunneling
The setup of HTTP tunneling takes place by a property file named
httptunnel.properties. This needs either to exist in the
to be specified while starting the application:
Is the file founded in
CLASSPATH resp. is it specified with
startup, HTTP tunneling will occur, otherwise not.
The file contains the following properties:
|proxy.host||DNS name of the HTTP proxy, by which it should be tunneled.|
|proxy.port||Portnumber of the HTTP proxy, by which it should be tunneled.|
|proxy.username||Only if the access results on the proxy by username/password authentication. Specifies the username to the proxy.|
|proxy.password||Only if the access results on the proxy by username/password authentication. Specifies the password to the proxy.|
|noproxy.host.names||Contains a list of hostnames to which no HTTP tunneling should result. The hostnames might be indicated as SQL-Like predicate. Here, the percent character '%' is considered to be a replacement character to any character, the underscore '_' to a single character. Escape sign is '\'.|
proxy.host=pamela.iit.de proxy.port=3128 proxy.username=muelli proxy.password=secret noproxy.host.names=localhost,dev%.iit.de,mail.iit.de
Tunneling JMS Client Connections
HTTP tunneling of JMS client connections is defined by the corresponding
JMS clients. Concerning the SwiftMQRouter, no further
configuration is required. The JMS client defines its HTTP proxy by the
httptunnel.properties and provides the file either in
or defines it by starting the application with
-D. The tunneling now
takes place automatically.
The property file is loaded once, because the resp. SwiftMQ class is a singleton. However, there is a proprietary way to reload properties, e.g. to try another HTTP proxy without the need to terminate the JMS application:
import com.swiftmq.net.*; import java.util.*; ... Properties prop = new Properties(); // set the new proxy properties ... // reload the properties HttpTunnelProperties.getInstance().reload(prop);
One can also specify a file name for the new property file:
import com.swiftmq.net.*; ... // reload the properties HttpTunnelProperties.getInstance().reload("newproxy.properties");
Tracing HTTP Tunneling
The communication between a JMS client and a HTTP proxy might be
pursued. To this, while calling the JMS client,
put the property
swiftmq.httptunnel.debug to the value
The HTTP requests and responses are reported on the
At any rate, adjust first the debugmode
The JMS client always tries to establish a direct connection
Verify if the file
httptunnel.properties in the
CLASSPATH exists or
define it at your commandline explicitly with
-Dswiftmq.httptunnel.file=<file>. Please verify furthermore if the
host you want to connect is not defined in the property
No connection might be established to a proxy
Verify if the properties
proxy.port are set right.
The values need to point at your HTTP proxy. Please verify if your proxy
demands an authentification and, if necessary, specify
It might also be that your proxy only permits the tunneling by the Standard-SSL Ports. In general, these are the ports 443 and 563. In this case, the JMS resp. the routing listener of the SwiftMQ Router, to which a connection should be established, needs to be listen on one of this ports.
The proxy closes the connection after a while
Normally, a proxy only closes connections if nothing is sent on them. SwiftMQ offers hereto the keep-alive interval. Adjust this to a lower value, e. g. 30000 (30 seconds).