Appendix C HTTP/HTTPS Support

Message Queue, Enterprise Edition includes support for a Java client to communicate with the broker by means of an HTTP or secure HTTP (HTTPS) transport, rather than a direct TCP connection. HTTP/HTTPS support is not available for C clients.

This appendix describes the architecture used to enable this support and explains the setup work needed to allow clients to use HTTP-based connections for Message Queue messaging. It has the following sections:

HTTP/HTTPS Support Architecture

Enabling HTTP Support

Enabling HTTPS Support

Troubleshooting

HTTP/HTTPS Support Architecture

Message Queue messaging can run on top of HTTP/HTTPS connections. Because HTTP/HTTPS connections are normally allowed through firewalls, this allows client applications to be separated from a broker by a firewall.

On the client side, an HTTP or HTTPS transport driver encapsulates the Message Queue message into an HTTP request and makes sure that these requests are sent to the Web server in the correct sequence.

The client can use an HTTP proxy server to communicate with the broker if necessary. The proxy’s address is specified using command line options when starting the client. See Using an HTTP Proxy for more information.

An HTTP or HTTPS tunnel servlet (both bundled with Message Queue) is loaded in the web server and used to pull JMS messages out of client HTTP requests before forwarding them to the broker. The HTTP/HTTPS tunnel servlet also sends broker messages back to the client in response to HTTP requests made by the client. A single HTTP/HTTPS tunnel servlet can be used to access multiple brokers.

Figure C-1 HTTP/HTTPS Support Architecture
Diagram showing how an http proxy and http tunnel servlet enable messages to go through firewalls. Figure explained in text.

On the broker side, the httpjms or httpsjms connection service unwraps and de-multiplexes incoming messages from the corresponding tunnel servlet.

If the Web server fails and is restarted, all connections are restored and there is no effect on clients. If the broker fails and is restarted, an exception is thrown and clients must re-establish their connections. In the unlikely case that both the Web server and the broker fail, and the broker is not restarted, the Web server will restore client connections and continue waiting for a broker connection— without notifying clients. To avoid this situation, always restart the broker.

As you can see from Figure C-1, the architecture for HTTP and HTTPS support are very similar. The main difference is that, in the case of HTTPS (httpsjms connection service), the tunnel servlet has a secure connection to both the client application and broker.

The secure connection to the broker is provided through an SSL-enabled tunnel servlet—Message Queue’s HTTPS tunnel servlet—which passes a self-signed certificate to any broker requesting a connection. The certificate is used by the broker to set up an encrypted connection to the HTTPS tunnel servlet. Once this connection is established, a secure connection between a client application and the tunnel servlet can be negotiated by the client application and the web server.

Enabling HTTP Support

The following sections describe the steps you need to take to enable HTTP support.

To Enable HTTP Support

Deploy the HTTP tunnel servlet on a web server.

Configure the broker’s httpjms connection service and start the broker.

Configure an HTTP connection.

Step 1. Deploying the HTTP Tunnel Servlet on a Web Server

There are two general ways you can deploy the HTTP tunnel servlet on a web server:

deploying it as a jar file—for web servers that support Servlet 2.1 or earlier

deploying it as a web archive (WAR) file—for web servers that support Servlet 2.2 or later

Deploying as a Jar File

Deploying the Message Queue tunnel servlet consists of making the appropriate jar files accessible to the host web server, configuring the web server to load the servlet on startup, and specifying the context root portion of the servlet’s URL.

Any web server with servlet 2.x support can be used to load this servlet. The servlet class name is:

The web server must be able to see the imqservlet.jar file. If you are planning to run the web server and the broker on different hosts, you should place a copy of the imqservlet.jar file in a location where the web server can access it.

It is also recommended that you disable your web server’s access logging feature in order to improve performance.

Deploying as a Web Archive File

Deploying the HTTP tunnel servlet as a WAR file consists of using the deployment mechanism provided by the web server. The HTTP tunnel servlet WAR file (imqhttp.war) is located in the directory containing .jar, .war, and .rar files, and depends on your operating system (see Appendix A, "Operating System-Specific Locations of Message Queue Data").

The WAR file includes a deployment descriptor that contains the basic configuration information needed by the web server to load and run the servlet. Depending on the web server, you might also need to specify the context root portion of the servlet’s URL (see Example 2: Deploying the HTTP Tunnel Servlet on Sun Java System Application Server 7.0).

Step 2. Configuring the httpjms Connection Service

HTTP support is not activated for a broker by default, so you need to reconfigure the broker to activate the httpjms connection service. Once reconfigured, the broker can be started as outlined in Starting Brokers Interactively.

To Activate the httpjms Connection Service

Open the broker’s instance configuration file.

The instance configuration file is stored in a directory identified by the name of the broker instance (instanceName) with which the configuration file is associated (see Appendix A, "Operating System-Specific Locations of Message Queue Data"):

…/instances/instanceName/props/config.properties

Add the httpjms value to the imq.service.activelist property:

imq.service.activelist=jms,admin,httpjms

At startup, the broker looks for a web server and HTTP tunnel servlet running on its host machine. To access a remote tunnel servlet, however, you can reconfigure the servletHost and servletPort connection service properties.

You can also reconfigure the pullPeriod property to improve performance. The httpjms connection service configuration properties are detailed in Table C-1.

Table C-1 httpjms Connection Service Properties
Property Name	Description
imq.httpjms.http. servletHost	Change this value, if necessary, to specify the name of the host (hostname or IP address) on which the HTTP tunnel servlet is running. (This can be a remote host or a specific hostname on a local host.) Default: localhost
imq.httpjms.http. servletPort	Change this value to specify the port number that the broker uses to access the HTTP tunnel servlet. (If the default port is changed on the Web server, you must change this property accordingly.) Default: 7675
imq.httpjms.http. pullPeriod	Specifies the interval, in seconds, between HTTP requests made by a client runtime to pull messages from the broker. (Note that this property is set on the broker and propagates to the client runtime.) If the value is zero or negative, the client keeps one HTTP request pending at all times, ready to pull messages as fast as possible. With a large number of clients, this can be a heavy drain on web server resources and the server may become unresponsive. In such cases, you should set the pullPeriod property to a positive number of seconds. This sets the time the client’s HTTP transport driver waits before making subsequent pull requests. Setting the value to a positive number conserves web server resources at the expense of the response times observed by clients. Default: -1
imq.httpjms.http. connectionTimeout	Specifies the time, in seconds, that the client runtime waits for a response from the HTTP tunnel servlet before throwing an exception. (Note that this property is set on the broker and propagates to the client runtime.) This property also specifies the time the broker waits after communicating with the HTTP tunnel servlet before freeing up a connection. A timeout is necessary in this case because the broker and the tunnel servlet have no way of knowing if a client that is accessing the HTTP servlet has terminated abnormally. Default: 60

Step 3. Configuring an HTTP Connection

A client application must use an appropriately configured connection factory administered object to make an HTTP connection to a broker. This section discusses HTTP connection configuration issues.

Configuring the Connection Factory

To enable HTTP support, you need to set the connection factory’s imqAddressList attribute to the HTTP tunnel servlet URL. The general syntax of the HTTP tunnel servlet URL is the following:

where hostName:port is the name and port of the web server hosting the HTTP tunnel servlet and contextRoot is a path set when deploying the tunnel servlet on the web server.

For more information on connection factory attributes in general, and the imqAddressList attribute in particular, see the Message Queue Developer’s Guide for Java Clients.

Using the -o option to the imqobjmgr command that creates the connection factory administered object (see Adding a Connection Factory), or set the attribute when creating the connection factory administered object using the Administration Console (imqadmin).

Using the -D option to the command that launches the client (see the Message Queue Developer’s Guide for Java Clients).

Using a an API call to set the attributes of a connection factory after you create it programmatically in client code (see the Message Queue Developer’s Guide for Java Clients).

Using a Single Servlet to Access Multiple Brokers

You do not need to configure multiple web servers and servlet instances if you are running multiple brokers. You can share a single web server and HTTP tunnel servlet instance among concurrently running brokers. If multiple broker instances are sharing a single tunnel servlet, you must configure the imqAddressList connection factory attribute as shown below:

http://hostName:port/contextRoot/tunnel?ServerName=bkrHostName:instanceName

Where bkrHostName is the broker instance host name and instanceName is the name of the specific broker instance you want your client to access.

To check that you have entered the correct strings for bkrHostName and instanceName, generate a status report for the HTTP tunnel servlet by accessing the servlet URL from a browser. The report lists all brokers being accessed by the servlet:

HTTP tunnel servlet ready.

Servlet Start Time : Thu May 30 01:08:18 PDT 2002

Accepting TCP connections from brokers on port : 7675

Total available brokers = 2

Broker List :

jpgserv:broker2

cochin:broker1

Using an HTTP Proxy

Set http.proxyHost system property to the proxy server host name.

Set http.proxyPort system property to the proxy server port number.

You can set these properties using the -D option to the command that launches the client application.

Example 1: Deploying the HTTP Tunnel Servlet on Sun Java System Web Server

This section describes how you deploy the HTTP tunnel servlet both as a jar file and as a WAR file on the Sun Java System Web Server. The approach you use depends on the version of Sun Java System Web Server: If it does not support Servlet 2.2 or later, it will not be able to handle WAR file deployment.

Deploying as a Jar File

The instructions below refer to deployment on Sun Java System Web Server 6.1 using the browser-based administration GUI. This procedure consists of the following general steps:

add a servlet

configure the servlet virtual path

load the servlet

disable the servlet access log

These steps are described in the following subsections. You can verify successful HTTP tunnel servlet deployment by accessing the servlet URL using a web browser. It should display status information.

Adding a Servlet

To Add a Tunnel Servlet

Select the Servlets tab.

Choose Configure Servlet Attributes.

Specify a name for the tunnel servlet in the Servlet Name field.

Set the Servlet Code (class name) field to the following value:

com.sun.messaging.jmq.transport.httptunnel.servlet.HttpTunnelServlet

Enter the complete path to the imqservlet.jar in the Servlet Classpath field. For example:

/usr/share/lib/imq/imqservlet.jar (Solaris)
/opt/sun/mq/share/lib/imqservlet.jar (Linux)
IMQ_HOME/lib/imqservlet.jar (Windows)

In the Servlet args field, enter any optional arguments, as shown in Table C-2:

Table C-2 Servlet Arguments for Deploying HTTP Tunnel Servlet Jar File
Argument	Default Value	Reference
servletHost	all hosts	See Table C-1
servletPort	7675	See Table C-1

If using both arguments, separate them with a comma:

servletPort=portNumber, servletHost=…

The servletHost and servletPort argument apply only to communication between the Web Server and broker, and are set only if the default values are problematic. However, in that case, you also must set the broker configuration properties accordingly (see Table C-1), for example:

imq.httpjms.http.servletPort

Configuring a Servlet Virtual Path (Servlet URL)

To Configure a Virtual Path (Servlet URL) for a Tunnel Servlet

Select the Servlets tab.

Choose Configure Servlet Virtual Path Translation.

Set the Virtual Path field.

The Virtual Path is the /contextRoot/tunnel portion of the tunnel servlet URL:

http://hostName:port/contextRoot/tunnel

For example, if you set the contextRoot to imq, the Virtual Path field would be:

/imq/tunnel

Set the Servlet Name field to the same value as in Step 3 in Adding a Servlet.

Loading a Servlet

To Load the Tunnel Servlet at Web Server Startup

Select the Servlets tab.

Choose Configure Global Attributes.

In the Startup Servlets field, enter the same servlet name value as in Step 3 in Adding a Servlet.

Disabling a Server Access Log

You do not have to disable the server access log, but you will obtain better performance if you do.

To Disable the Server Access Log

Select the Status tab.

Choose the Log Preferences Page.

Use the Log client accesses control to disable logging

Deploying as a WAR File

The instructions below refer to deployment on Sun Java System Web Server 6.0 Service Pack 2. You can verify successful HTTP tunnel servlet deployment by accessing the servlet URL using a web browser. It should display status information.

To Deploy the http Tunnel Servlet as a WAR File

In the browser-based administration GUI, select the Virtual Server Class tab and select Manage Classes.

Select the appropriate virtual server class name (for example, defaultClass) and click the Manage button.

Select Manage Virtual Servers.

Select an appropriate virtual server name and click the Manage button.

Select the Web Applications tab.

Click on Deploy Web Application.

Select the appropriate values for the WAR File On and WAR File Path fields so as to point to the imqhttp.war file, which can be found in a directory that depends on your operating system (see Appendix A, "Operating System-Specific Locations of Message Queue Data").

Enter a path in the Application URI field.

The Application URI field value is the /contextRoot portion of the tunnel servlet URL:

http://hostName:port/contextRoot/tunnel

For example, if you set the contextRoot to imq, the Application URI field would be:

/imq

Enter the installation directory path (typically somewhere under the Sun Java System Web Server installation root) where the servlet should be deployed.

Click OK.

Restart the web server instance.

Clients can now use this URL to connect to the message service using an HTTP connection.

Example 2: Deploying the HTTP Tunnel Servlet on Sun Java System Application Server 7.0

This section describes how you deploy the HTTP tunnel servlet as a WAR file on the Sun Java System Application Server 7.0.

deploy the HTTP tunnel servlet using the Application Server 7.0 deployment tool

modify the application server instance’s server.policy file

Using the Deployment Tool

To Deploy the HTTP Tunnel Servlet in an Application Server 7.0 Environment

In the web-based administration GUI, choose

App Server > Instances > server1 > Applications > Web Applications.

Click the Deploy button.

In the File Path: text field, enter the location of the HTTP tunnel servlet WAR file (imqhttp.war).

The location of the imqhttp.war file depends on your operating system (see Appendix A, "Operating System-Specific Locations of Message Queue Data")

Click OK.

On the next screen, set the value for the Context Root text field.

The Context Root field value is the /contextRoot portion of the tunnel servlet URL:

http://hostName:port/contextRoot/tunnel

For example, you could set the Context Root field to /imq.

Click OK.

The next screen shows that the tunnel servlet has been successfully deployed, is enabled by default, and—in this case—is located at:

/var/opt/SUNWappserver7/domains/domain1/server1/applications/
j2ee-modules/imqhttp_1

Clients can now use this URL to connect to the message service using an HTTP connection.

Modifying the server.policy File

The Application Server 7.0 enforces a set of default security policies that unless modified would prevent the HTTP tunnel servlet from accepting connections from the Message Queue broker.

Each application server instance has a file that contains its security policies or rules. For example, the location of this file for the server1 instance on Solaris is:

To make the tunnel servlet accept connections from the Message Queue broker, an additional entry is required in this file.

To Modify the Application Server’s server.policy File

Open the server.policy file.

Add the following entry:


grant codeBase
"file:/var/opt/SUNWappserver7/domains/domain1/server1/ applications/j2ee-modules/imqhttp_1/-”
{
permission java.net.SocketPermission "*", “connect,accept,resolve";
};

Enabling HTTPS Support

The following sections describe the steps you need to take to enable HTTPS support. They are similar to those in Enabling HTTP Support with the addition of steps needed to generate and access SSL certificates.

To Enable HTTPS Support

Generate a self-signed certificate for the HTTPS tunnel servlet.

Deploy the HTTPS tunnel servlet on a web server.

Configure the broker’s httpsjms connection service and start the broker.

Configure an HTTPS connection.

Step 1. Generating a Self-signed Certificate for the HTTPS Tunnel Servlet

Message Queue’s SSL support is oriented toward securing on-the-wire data with the assumption that the client is communicating with a known and trusted server. Therefore, SSL is implemented using only self-signed server certificates. In the httpsjms connection service architecture, the HTTPS tunnel servlet plays the role of server to both broker and application client.

Run the imqkeytool utility to generate a self-signed certificate for the tunnel servlet. Enter the following at the command prompt:

The utility will prompt you for the information it needs. (On Unix systems you may need to run imqkeytool as the superuser (root) in order to have permission to create the keystore.)

First, imqkeytool prompts you for a keystore password, and then it prompts you for some organizational information, and then it prompts you for confirmation. After it receives the confirmation, it pauses while it generates a key pair. It then asks you for a password to lock the particular key pair (key password); you should enter Return in response to this prompt: this makes the key password the same as the keystore password.


Note	Remember the password you provide—you must provide this password later to the tunnel servlet so it can open the keystore.

Running imqkeytool runs the JDK keytool utility to generate a self-signed certificate and to place it in Message Queue’s keystore file located as specified in the keystore_location argument. (The keystore is in the same keystore format as that supported by the JDK1.2 keytool.)

Step 2. Deploying the HTTPS Tunnel Servlet on a Web Server

There are two general ways you can deploy the HTTPS tunnel servlet on a web server:


Note	The HTTPS tunnel servlet must be able to see the keystore. Make sure you move/copy the generated keystore located in keystore_location to a location accessible by the HTTPS tunnel servlet (see Step 2. Deploying the HTTPS Tunnel Servlet on a Web Server).

deploying it as a jar file—for web servers that support Servlet 2.1 or earlier

deploying it as a web archive (WAR) file—for web servers that support Servlet 2.2 or later

In either case, you should make sure that encryption is activated for the web server, enabling end to end secure communication between the client and broker.

Deploying as a Jar File

Any web server with servlet 2.x support can be used to load this servlet. The servlet class name is:

Make sure that the JSSE jar files are in the classpath for running servlets in the web server. Check the web server’s documentation for how to do this.

An important aspect of configuring the web server is specifying the location and password of the self-signed certificate to be used by the HTTPS tunnel servlet to establish a secure connection with a broker. You must place the keystore created in Step 1. Generating a Self-signed Certificate for the HTTPS Tunnel Servlet in a location accessible by the HTTPS tunnel servlet.

It is also recommended that you disable your web server’s access logging feature in order to improve performance.

Deploying as a Web Archive File

Deploying the HTTPS tunnel servlet as a WAR file consists of using the deployment mechanism provided by the web server. The HTTPS tunnel servlet WAR file (imqhttps.war) is located in a directory that depends on your operating system (see Appendix A, "Operating System-Specific Locations of Message Queue Data").

The WAR file includes a deployment descriptor that contains the basic configuration information needed by the web server to load and run the servlet. Depending on the web server, you might also need to specify the context root portion of the servlet’s URL (see Example 4: Deploying the HTTPS Tunnel Servlet on Sun Java System Application Server 7.0).

However, the deployment descriptor of the imqhttps.war file cannot know where you have placed the keystore file needed by the tunnel servlet (see Step 1. Generating a Self-signed Certificate for the HTTPS Tunnel Servlet). This requires you to edit the tunnel servlet’s deployment descriptor (an XML file) to specify the keystore location before deploying the imqhttps.war file.

Step 3. Configuring the httpsjms Connection Service

HTTPS support is not activated for a broker by default, so you need to reconfigure the broker to activate the httpsjms connection service. Once reconfigured, the broker can be started as outlined in Starting Brokers Interactively.

To Activate the httpsjms Connection Service

Open the broker’s instance configuration file.

…/instances/instanceName/props/config.properties

Add the httpsjms value to the imq.service.activelist property:

imq.service.activelist=jms,admin,httpsjms

At startup, the broker looks for a web server and HTTPS tunnel servlet running on its host machine. To access a remote tunnel servlet, however, you can reconfigure the servletHost and servletPort connection service properties.

You can also reconfigure the pullPeriod property to improve performance. The httpsjms connection service configuration properties are detailed in Table C-3.

Table C-3 httpsjms Connection Service Properties
Property Name	Description
imq.httpsjms.https. servletHost	Change this value, if necessary, to specify the name of the host (hostname or IP address) on which the HTTPS tunnel servlet is running. (This can be a remote host or a specific hostname on a local host.) Default: localhost
imq.httpsjms.https. servletPort	Change this value to specify the port number that the broker uses to access the HTTPS tunnel servlet. (If the default port is changed on the Web server, you must change this property accordingly.) Default: 7674
imq.httpsjms.https. pullPeriod	Specifies the interval, in seconds, between HTTP requests made by each client to pull messages from the broker. (Note that this property is set on the broker and propagates to the client runtime.) If the value is zero or negative, the client keeps one HTTP request pending at all times, ready to pull messages as fast as possible. With a large number of clients, this can be a heavy drain on web server resources and the server may become unresponsive. In such cases, you should set the pullPeriod property to a positive number of seconds. This sets the time the client’s HTTP transport driver waits before making subsequent pull requests. Setting the value to a positive number conserves web server resources at the expense of the response times observed by clients. Default: -1
imq.httpsjms.https. connectionTimeout	Specifies the time, in seconds, that the client runtime waits for a response from the HTTPS tunnel servlet before throwing an exception. (Note that this property is set on the broker and propagates to the client runtime.) This property also specifies the time the broker waits after communicating with the HTTPS tunnel servlet before freeing up a connection. A timeout is necessary in this case because the broker and the tunnel servlet have no way of knowing if a client that is accessing the HTTPS servlet has terminated abnormally. Default: 60

Step 4. Configuring an HTTPS Connection

A client application must use an appropriately configured connection factory administered object to make an HTTPS connection to a broker.

However, the client must also have access to SSL libraries provided by the Java Secure Socket Extension (JSSE) and must also have a root certificate. The SSL libraries are bundled with JDK 1.4. If you have an earlier JDK version, see Configuring JSSE, otherwise proceed to Importing a Root Certificate.

Once these issues are resolved, you can proceed to configuring the HTTPS connection.

Configuring JSSE

To Configure JSSE

Copy the JSSE jar files to the JRE_HOME/lib/ext directory.

jsse.jar, jnet.jar, jcert.jar

Statically add the JSSE security provider by adding

security.provider.n=com.sun.net.ssl.internal.ssl.Provider

to the JRE_HOME/lib/security/java.security file (where n is the next available priority number for security provider package).

If not using JDK1.4, you need to set the following JSSE property using the -D option to the command that launches the client application:

java.protocol.handler.pkgs=com.sun.net.ssl.internal.www.protocol

Importing a Root Certificate

If the root certificate of the CA who signed your web server's certificate is not in the trust database by default or if you are using a proprietary web server certificate, you must add that certificate to the trust database. If this is the case, follow the instruction below, otherwise go to Configuring the Connection Factory.

Assuming that the certificate is saved in cert_file and that trust_store_file is your keystore, run the following command:

JRE_HOME/bin/keytool -import -trustcacerts
-alias alias_for_certificate -file cert_file
-keystore trust_store_file

You also need to specify the following JSSE properties using the -D option to the command that launches the client application:

Configuring the Connection Factory

To enable HTTPS support, you need to set the connection factory’s imqAddressList attribute to the HTTPS tunnel servlet URL. The general syntax of the HTTPS tunnel servlet URL is the following:

where hostName:port is the name and port of the web server hosting the HTTPS tunnel servlet and contextRoot is a path set when deploying the tunnel servlet on the web server.

For more information on connection factory attributes in general, and the imqAddressList attribute in particular, see the Message Queue Developer’s Guide for Java Clients.

Using the -D option to the command that launches the client application (see the Message Queue Developer’s Guide for Java Clients).

Using an API call to set the attributes of a connection factory after you create it programmatically in client application code (see the Message Queue Developer’s Guide for Java Clients).

Using a Single Servlet to Access Multiple Brokers

You do not need to configure multiple web servers and servlet instances if you are running multiple brokers. You can share a single web server and HTTPS tunnel servlet instance among concurrently running brokers. If multiple broker instances are sharing a single tunnel servlet, you must configure the imqAddressList connection factory attribute as shown below:

https://hostName:port/contextRoot/tunnel?ServerName=bkrHostName:instanceName

Where bkrHostName is the broker instance host name and instanceName is the name of the specific broker instance you want your client to access.

To check that you have entered the correct strings for bkrhostName and instanceName, generate a status report for the HTTPS tunnel servlet by accessing the servlet URL from a browser. The report lists all brokers being accessed by the servlet:

HTTPS tunnel servlet ready.

Servlet Start Time : Thu May 30 01:08:18 PDT 2002

Accepting secured connections from brokers on port : 7674

Total available brokers = 2

Broker List :

jpgserv:broker2

cochin:broker1

Using an HTTP Proxy

Set http.proxyHost system property to the proxy server host name.

Set http.proxyPort system property to the proxy server port number.

You can set these properties using the -D option to the command that launches the client application.

Example 3: Deploying the HTTPS Tunnel Servlet on Sun Java System Web Server

This section describes how you deploy the HTTPS tunnel servlet both as a jar file and as a WAR file on the Sun Java System Web Server. The approach you use depends on the version of Sun Java System Web Server: If it does not support Servlet 2.2 or later, it will not be able to handle WAR file deployment.

Deploying as a Jar File

The instructions below refer to deployment on Sun Java System Web Server 6.1 using the browser-based administration GUI. This procedure consists of the following general steps:

add a servlet

configure the servlet virtual path

load the servlet

disable the servlet access log

These steps are described in the following subsections. You can verify successful HTTPS tunnel servlet deployment by accessing the servlet URL using a web browser. It should display status information.

Adding a Servlet

To Add a Tunnel Servlet

Select the Servlets tab.

Choose Configure Servlet Attributes.

Specify a name for the tunnel servlet in the Servlet Name field.

Set the Servlet Code (class name) field to the following value:

com.sun.messaging.jmq.transport.
httptunnel.servlet.HttpsTunnelServlet

Enter the complete path to the imqservlet.jar in the Servlet Classpath field. For example:

/usr/share/lib/imq/imqservlet.jar (Solaris)

/opt/sun/mq/share/lib/imqservlet.jar (Linux)

IMQ_HOME/lib/imqservlet.jar (Windows)

In the Servlet args field, enter required and optional arguments, as shown in Table C-4.

Table C-4 Servlet Arguments for Deploying HTTPS Tunnel Servlet Jar File
Argument	Default Value	Required?
keystoreLocation	none	Yes
keystorePassword	none	Yes
servletHost	all hosts	No
servletPort	7674	No

Separate the arguments with commas. For example:

keystoreLocation=keystore_location,keystorePassword=keystore_password, servletPort=portnumber

imq.httpsjms.https.servletPort

Configuring a Servlet Virtual Path (Servlet URL)

To Configure a Virtual Path (servlet URL) for a Tunnel Servlet

Select the Servlets tab.

Choose Configure Servlet Virtual Path Translation.

Set the Virtual Path field.

The Virtual Path is the /contextRoot/tunnel portion of the tunnel servlet URL:

https://hostName:port/contextRoot/tunnel

For example, if you set the contextRoot to imq, the Virtual Path field would be:

/imq/tunnel

Set the Servlet Name field to the same value as in Step 3 in Adding a Servlet.

Loading a Servlet

To Load the Tunnel Servlet at Web Server Startup

Select the Servlets tab.

Choose Configure Global Attributes.

In the Startup Servlets field, enter the same servlet name value as in Step 3 in Adding a Servlet.

Disabling a Server Access Log

You do not have to disable the server access log, but you will obtain better performance if you do.

To Disable the Server Access Log

Select the Status tab.

Choose the Log Preferences Page.

Use the Log client accesses control to disable logging

Deploying as a WAR File

The instructions below refer to deployment on Sun Java System Web Server 6.0 Service Pack 2. You can verify successful HTTPS tunnel servlet deployment by accessing the servlet URL using a web browser. It should display status information.

Before deploying the HTTPS tunnel servlet, make sure that JSSE jar files are included in the web server’s classpath. The simplest way to do this is to copy the jsse.jar, jnet.jar, and jcert.jar to IWS60_TOPDIR/bin/https/jre/lib/ext.

Also, before deploying the HTTPS tunnel servlet, you must modify its deployment descriptor to point to the location where you have placed the keystore file and to specify the keystore password.

To Modify the HTTPS Tunnel Servlet WAR File

Copy the WAR file to a temporary directory.

cp /usr/share/lib/imq/imqhttps.war /tmp (Solaris)

cp /opt/sun/mq/share/lib/imqhttps.war /tmp (Linux)

cp IMQ_HOME/lib/imqhttps.war /tmp (Windows)

Make the temporary directory your current directory.

$ cd /tmp

Extract the contents of the WAR file.

$ jar xvf imqhttps.war

List the WAR file’s deployment descriptor.

$ ls -l WEB-INF/web.xml

Edit the web.xml file to provide correct values for the keystoreLocation and keystorePassword arguments (as well as servletPort and servletHost arguments, if necessary).

Re-assemble the contents of the WAR file.

$ jar uvf imqhttps.war WEB-INF/web.xml

You are now ready to use the modified imqhttps.war file to deploy the HTTPS tunnel servlet. (If you are concerned about exposure of the keystore password, you can use file system permissions to restrict access to the imqhttps.war file.)

To Deploy the https Tunnel Servlet as a WAR File

In the browser-based administration GUI, select the Virtual Server Class tab. Click Manage Classes.

Select the appropriate virtual server class name (for example, defaultClass) and click the Manage button.

Select Manage Virtual Servers.

Select an appropriate virtual server name and click the Manage button.

Select the Web Applications tab.

Click on Deploy Web Application.

Select the appropriate values for the WAR File On and WAR File Path fields so as to point to the modified imqhttps.war file (see To Modify the HTTPS Tunnel Servlet WAR File.)

Enter a path in the Application URI field.

The Application URI field value is the /contextRoot portion of the tunnel servlet URL:

https://hostName:port/contextRoot/tunnel

For example, if you set the contextRoot to imq, the Application URI field would be:

/imq

Enter the installation directory path (typically somewhere under the Sun Java System Web Server installation root) where the servlet should be deployed.

Click OK.

Restart the web server instance.

Clients can now use this URL to connect to the message service using a secure HTTPS connection.

Example 4: Deploying the HTTPS Tunnel Servlet on Sun Java System Application Server 7.0

This section describes how you deploy the HTTPS tunnel servlet as a WAR file on the Sun Java System Application Server 7.0.

deploy the HTTPS tunnel servlet using the Application Server 7.0 deployment tool

modify the application server instance’s server.policy file

Using the Deployment Tool

To Deploy the HTTPS Tunnel Servlet in an Application Server 7.0 Environment

In the web-based administration GUI, choose

App Server > Instances > server1 > Applications > Web Applications.

Click the Deploy button.

In the File Path: text field, enter the location of the HTTPS tunnel servlet WAR file (imqhttps.war).

The location of the imqhttps.war file depends on your operating system (see Appendix A, "Operating System-Specific Locations of Message Queue Data")

Click OK.

On the next screen, set the value for the Context Root text field.

The Context Root field value is the /contextRoot portion of the tunnel servlet URL:

https://hostName:port/contextRoot/tunnel

For example, you could set the Context Root field to:

/imq

Click OK.

The next screen shows that the tunnel servlet has been successfully deployed, is enabled by default, and—in this case—is located at:

/var/opt/SUNWappserver7/domains/domain1/server1/applications/
j2ee-modules/imqhttps_1

Clients can now use this URL to connect to the message service using an HTTPS connection.

Modifying the server.policy file

The Application Server 7.0 enforces a set of default security policies that unless modified would prevent the HTTPS tunnel servlet from accepting connections from the Message Queue broker.

Each application server instance has a file that contains its security policies or rules. For example, the location of this file for the server1 instance on Solaris is:

To make the tunnel servlet accept connections from the Message Queue broker, an additional entry is required in this file.

To Modify the Application Server’s server.policy File

Open the server.policy file.

Add the following entry:


grant codeBase
"file:/var/opt/SUNWappserver7/domains/domain1/server1/ applications/j2ee-modules/imqhttps_1/-”
{
permission java.net.SocketPermission "*", “connect,accept,resolve";
};

Troubleshooting

This section describes possible problems with an HTTP or HTTPS connection and provides guidance on how to handle them.

Server or Broker Failure

If the web server fails and is restarted, all connections are restored and there is no effect on clients. However, if the broker fails and is restarted, an exception is thrown and clients must re-establish their connections.

If both the web server and the broker fail, and the broker is not restarted, the web server restores client connections and continues waiting for a broker connection without notifying clients. To avoid this situation, always make sure the broker is restarted.

Client Failure to Connect Through the Tunnel Servlet

If an HTTPS client cannot connect to the broker through the tunnel servlet, do the following:

Start the servlet and the broker.

Use a browser to manually access the servlet through the HTTPS tunnel servlet URL.

Use the following administrative commands to pause and resume the connection:

imqcmd pause svc -n httpsjms -u admin
imqcmd resume svc -n httpsjms -u admin

When the service resumes, an HTTPS client should be able to connect to the broker through the tunnel servlet.

Previous Contents Index Next
Sun Java System Message Queue 3 2005Q1 Administration Guide