Sun JavaTM System Message Queue data is stored in different locations on different operating system platforms. The tables that follow show the location of various types of Message Queue data on the following platforms:
In the tables, instanceName denotes the name of the broker instance with which the data is associated.
Table A–1 shows the location of Message Queue data on the Solaris operating system. If you are using Message Queue on Solaris with the standalone version of Sun Java System Application Server, the directory structure is like that described under Windows.
Table A–1 Message Queue Data Locations on Solaris Platform
Table A–2 shows the location of Message Queue data on the Linux operating system.
Table A–2 Message Queue Data Locations on Linux Platform
Table A–3 shows the location of Message Queue data on the Windows operating system. The table also applies to the Solaris platform when Message Queue is bundled with the standalone version of Sun Java System Application Server. That version of Application Server is bundled with neither Solaris nor Sun Java Enterprise System. Use the pathnames in Table A–3, but change the direction of the slash characters from the Windows backslash (\) to the Solaris forward slash (/). SeeDirectory Variable Conventions for definitions of the IMQ_HOME and IMQ_VARHOME directory variables.
Table A–3 Message Queue Data Locations on Windows Platform
Sun JavaTM System Message Queue uses many interfaces that can help administrators automate tasks. This appendix classifies the interfaces according to their stability. The more stable an interface is, the less likely it is to change in subsequent versions of the product.
Any interface that is not listed in this appendix is private and not for customer use.
Appendix B, Stability of Message Queue Interfaces describes the stability classification scheme.
Table B–1 Interface Stability Classification Scheme
Classification |
Description |
---|---|
Private |
Not for direct use by customers. May change or be removed in any release. |
Evolving |
For use by customers. Subject to incompatible change at a major (e.g. 3.0, 4.0) or minor (e.g. 3.1, 3.2) release. The changes will be made carefully and slowly. Reasonable efforts will be made to ensure that all changes are compatible but that is not guaranteed. |
Stable |
For use by customers. Subject to incompatible change at a major (for example, 3.0 or 4.0) release only. |
Standard |
For use by customers. These interfaces are defined by a formal standard, and controlled by a standards organization. Incompatible changes to these interfaces are rare. |
Unstable |
For use by customers. Subject to incompatible change at a major (e.g. 3.0, 4.0) or minor (e.g. 3.1, 3.2) release. Customers are advised that these interfaces may be removed or changed substantially and in an incompatible way in a future release. It is recommended that customers not create explicit dependencies on unstable interfaces. |
Appendix B, Stability of Message Queue Interfaces lists the interfaces and their classifications.
Table B–2 Stability of Message Queue Interfaces
Interface |
Classification |
---|---|
Command Line Interfaces | |
imqbrokerd command line interface |
Evolving |
imqadmin command line interface |
Unstable |
imqcmd command line interface |
Evolving |
imqdbmgr command line interface |
Unstable |
imqkeytool command line interface |
Evolving |
imqobjmgr command line interface |
Evolving |
imqusermgr command line interface |
Unstable |
Output from imqbrokerd, imqadmin, imqcmd, imqdbmgr, imqkeytool, imqobjmgr, imqusermgr |
Unstable |
Commands | |
imqobjmgr command file |
Evolving |
imqbrokerd command |
Stable |
imqadmin command |
Unstable |
imqcmd command |
Stable |
imqdbmgr command |
Unstable |
imqkeytool command |
Stable |
imqobjmgr command |
Stable |
imqusermgr command |
Unstable |
APIs | |
JMS API (javax.jms) |
Standard |
JAXM API (javax.xml) |
Standard |
C-API |
Evolving |
C-API environment variables |
Unstable |
Message-based monitoring API |
Evolving |
Administered Object API (com.sun.messaging) |
Evolving |
.jar and .war Files |
|
imq.jar location and name |
Stable |
jms.jar location and name |
Evolving |
imqbroker.jar location and name |
Private |
imqutil.jar location and name |
Private |
imqadmin.jar location and name |
Private |
imqservlet.jar location and name |
Evolving |
imqhttp.war location and name |
Evolving |
imqhttps.war location and name |
Evolving |
imqjmsra.rar location and name |
Evolving |
imqxm.jar location and name |
Evolving |
jaxm-api.jar location and name |
Evolving |
saaj-api.jar location and name |
Evolving |
saaj-impl.jar location and name |
Evolving |
activation.jar location and name |
Evolving |
mail.jar location and name |
Evolving |
dom4j.jar location and name |
Private |
fscontext.jar location and name |
Unstable |
Files | |
Broker log file location and content format |
Unstable |
password file |
Unstable |
accesscontrol.properties file |
Unstable |
System Destinations | |
mq.sys.dmq destination |
Stable |
mq.metrics.* destinations |
Evolving |
Configuration Properties | |
Message Queue JMS Resource Adapter configuration properties |
Evolving |
Message Queue JMS Resource Adapter JavaBean and ActivationSpec configuration properties |
Evolving |
Message Properties and Formats | |
Dead message queue message property, JMSXDeliveryCount |
Standard |
Dead message queue message properties, JMS_SUN_* |
Evolving |
Message Queue client message properties: JMS_SUN_* |
Evolving |
JMS message format for metrics or monitoring messages |
Evolving |
Miscellaneous | |
Message Queue JMS Resource Adapter package, com.sun.messaging.jms.ra |
Evolving |
JDBC schema for storage of persistent messages |
Evolving |
Message Queue includes support for Java clients to communicate with a message broker by means of the HTTP or secure HTTP (HTTPS) transport protocols, rather than through a direct TCP connection. (HTTP/HTTPS support is not available for C clients.) Because HTTP/HTTPS connections are normally allowed through firewalls, this allows client applications to be separated from the broker by a firewall.
This appendix describes the architecture used to enable HTTP/HTTPS support and explains the setup work needed to allow Message Queue clients to use such connections. It has the following sections:
Message Queue’s support architecture is very similar for both HTTP and HTTPS support, as shown in Figure C–1:
On the client side, an HTTP or HTTPS transport driver (part of the Message Queue client runtime) encapsulates each message into an HTTP request and makes sure that these requests are transmitted in the correct sequence.
If necessary, the client can use an HTTP proxy server to communicate with the broker. The proxy’s address is specified using command line options when starting the client; seeUsing an HTTP Proxy for more information.
An HTTP or HTTPS tunnel servlet (both bundled with Message Queue) is loaded into an application server or Web server on the broker side and used to pull payload messages from client HTTP requests before forwarding them to the broker. The tunnel servlet also sends broker messages back to the client in response to the client’s HTTP requests. A single tunnel servlet can be used to access multiple brokers.
On the broker side, the httpjms or httpsjms connection service unwraps and demultiplexes incoming messages from the corresponding tunnel servlet.
The main difference between HTTP and HTTPS connections is that in the HTTPS case (httpsjms connection service), the tunnel servlet has a secure connection to both the client application and the broker. The secure connection to the broker is established by means of the Secure Socket Layer (SSL) protocol. Message Queue’s SSL-enabled HTTPS tunnel servlet passes a self-signed certificate to any broker requesting a connection. The broker uses the certificate to establish an encrypted connection to the tunnel servlet. Once this connection is established, a secure connection between the client application and the tunnel servlet can be negotiated by the client application and the application server or Web server.
The procedures for enabling HTTP and HTTPS support are essentially the same for both protocols, although a few extra steps are required in the HTTPS case to generate and access the needed encryption keys and certificates. The steps are as follows. (For HTTPS, start with step 1; for non-secure HTTP, start with step 4.)
(HTTPS only) Generate a self-signed certificate for the HTTPS tunnel servlet.
(HTTPS only) Modify the deployment descriptor in the tunnel servlet’s .war file to specify the location and password of the certificate key store.
(HTTPS only) Validate the Web or application server’s self-signed certificate and install it in the client application’s trust store.
(HTTP and HTTPS) Deploy the HTTP or HTTPS tunnel servlet.
(HTTP and HTTPS) Configure the broker’s httpjms or httpsjms connection service and start the broker.
(HTTP and HTTPS) Configure an HTTP or HTTPS connection.
The following subsections describe each of these steps in greater detail, using Sun JavaTM System Application Server as an example for purposes of illustration. If you are using a different application server or Web server (such as Sun Java System Web Server), the procedures will be substantially similar but may differ in detail; see your server product’s own documentation for specifics.
Message Queue’s SSL support is oriented toward securing on-the-wire data, on the assumption that the client is communicating with a known and trusted server. Therefore, SSL is implemented using only self-signed server certificates. Before establishing an HTTPS connection, you must obtain such a certificate. (This step is not needed for ordinary, non-secure HTTP connections.)
Run the Message Queue Key Tool utility (imqkeytool) to generate a self-signed certificate for the tunnel servlet. (On UNIX systems, you may need to run the utility as the root user in order to have permission to create the key store.) Enter the following at the command prompt:
imqkeytool -servlet keyStoreLocation
where keyStoreLocation is the location of Message Queue’s key store file.
The Key Tool utility prompts you for a key store password:
Enter keystore password:
After you have entered a valid password, the utility prompts you for identifying information from which to construct an X.500 distinguished name. Table C–1 shows the prompts and the values to be provided for each prompt. Values are case-insensitive and can include spaces.
Table C–1 Distinguished Name Information Required for a Self-Signed Certificate
Prompt |
X.500 Attribute |
Description |
Example |
---|---|---|---|
What is your first and last name? |
commonName (CN) |
Fully qualified name of server running the broker |
mqserver.sun.com |
What is the name of your organizational unit? |
organizationalUnit (OU) |
Name of department or division |
purchasing |
What is the name of your organization? |
organizationName (ON) |
Name of larger organization, such as a company or government entity |
Acme Widgets, Inc. |
What is the name of your city or locality? |
localityName (L) |
Name of city or locality |
San Francisco |
What is the name of your state or province? |
stateName (ST) |
Full (unabbreviated) name of state or province |
California |
What is the two-letter country code for this unit? |
country (C) |
Standard two-letter country code |
US |
When you have entered the information, the Key Tool utility displays it for confirmation: for example,
Is CN=mqserver.sun.com, OU=purchasing, ON=Acme Widgets, Inc., L=San Francisco, ST=California, C=US correct?
To accept the current values and proceed, enter yes; to reenter values, accept the default or enter no. After you confirm, the utility pauses while it generates a key pair.
Next, the utility asks for a password to lock the key pair (key password). Press Return in response to this prompt to use the same password for both the key password and the key store password.
Be sure to remember the password you specify. You must provide this password later to the tunnel servlet so it can open the key store.
The Key Tool utility generates a self-signed certificate and places it in Message Queue’s key store file at the location you specified for the keyStoreLocation argument.
The HTTPS tunnel servlet must be able to see the key store. Be sure to move or copy the generated key store from the location specified by keyStoreLocation to one accessible to the tunnel servlet (see Step 4 (HTTP and HTTPS): Deploying the Tunnel Servlet).
The tunnel servlet’s Web archive (.war) file includes a deployment descriptor, an XML file containing the basic configuration information needed by the application server or Web server to load and run the servlet. Before deploying the .war file for the HTTPS tunnel servlet, you must edit the deployment descriptor to specify the location and password of the certificate key store. (This step is not needed for ordinary, non-secure HTTP connections.)
Copy the .war file to a temporary directory:
The location of the HTTPS tunnel servlet’s .war file varies, depending on your platform (see Appendix A, Platform-Specific Locations of Message Queue Data):
Solaris: cp /usr/share/lib/imq/imqhttps.war /tmp
Linux: cp /opt/sun/mq/share/lib/imqhttps.war /tmp
Windows: cp IMQ_HOME\lib\imqhttps.war \tmp
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.
Enter the command
ls -l WEB-INF/web.xml
to confirm that the deployment descriptor file (WEB-INF/web.xml) was successfully extracted.
Edit the deployment descriptor to specify the key store location and password.
Edit the web.xml file to provide appropriate values for the keystoreLocation and keystorePassword elements (as well as servletPort and servletHost, if necessary): for example,
<init-param> <param-name>keystoreLocation</param-name> <param-value>/local/tmp/imqhttps/keystore</param-value> </init-param> <init-param> <param-name>keystorePassword</param-name> <param-value>shazam</param-value> </init-param> <init-param> <param-name>servletHost</param-name> <param-value>localhost</param-value> </init-param> <init-param> <param-name>servletPort</param-name> <param-value>7674</param-value> </init-param>
If you are concerned about exposure of the key store password, you can use file-system permissions to restrict access to the imqhttps.war file.)
Reassemble the contents of the .war file.
jar uvf imqhttps.war WEB-INF/web.xml
In order for a client application to communicate with the Web or application server, you must validate the server’s self-signed certificate and install it in the application’s trust store. The following procedure shows how:
Validate the server’s certificate.
By default, the Sun Java System Application Server generates a self-signed certificate and stores it in a key store file at the location
appServerRoot/glassfish/domains/domain1/config/keystore.jks
where appServerRoot is the root directory in which the Application Server is installed.
If necessary, you can use the JDK Key Tool utility to generate a key store of your own and use it in place of the default key store. For more information, see the section “Establishing a Secure Connection Using SSL” in Chapter 28, “Introduction to Security in Java EE,” of the Java EE 5 Tutorial at
http://java.sun.com/javaee/5/docs/tutorial/doc/Security-Intro7.html
Make the directory containing the key store file your current directory.
For example, to use the Application Server’s default key store file (as shown above), navigate to its directory with the command
cd appServerRoot/glassfish/domains/domain1/config
where appServerRoot is, again, the root directory in which the Application Server is installed.
List the contents of the key store file.
The Key Tool utility’s -list option lists the contents of a specified key store file. For example, the following command lists the Application Server’s default key store file (keystore.jks):
keytool -list -keystore keystore.jks -v
The -v option tells the Key Tool utility to display certificate fingerprints in human-readable form.
Enter the key store password.
The Key Tool utility prompts you for the key store file’s password:
Enter keystore password:
By default, the key store password is set to changeit; you can use the Key Tool utility’s -storepasswd option to change it to something more secure. After you have entered a valid password, the Key Tool utility will respond with output like the following:
|
Verify the certificate’s fingerprints.
Obtain the correct fingerprints for the Application Server’s self-signed certificate by independent means (such as by telephone) and compare them with the fingerprints displayed by the keytool -list command. Do not accept the certificate and install it in your application’s trust store unless the fingerprints match.
Export the Application Server’s certificate to a certificate file.
Use the Key Tool utility’s -export option to export the certificate from the Application Server’s key store to a separate certificate file, from which you can then import it into your application’s trust store. For example, the following command exports the certificate shown above, whose alias is slas, from the Application Server’s default key store (keystore.jks) to a certificate file named slas.cer:
keytool -export -keystore keystore.jks -storepass changeit -alias slas -file slas.cer
The Key Tool utility responds with the output
Certificate stored in file <slas.cer>
Verify the contents of the certificate file.
If you wish, you can double-check the contents of the certificate file to make sure it contains the correct certificate:
List the contents of the certificate file.
The Key Tool utility’s -printcert option lists the contents of a specified certificate file. For example, the following command lists the certificate file slas.cer that was created in the preceding step:
keytool -printcert -file slas.cer -v
Once again, the -v option tells the Key Tool utility to display the certificate’s fingerprints in human-readable form. The resulting output looks like the following:
|
Confirm the certificate’s contents.
Examine the output from the keytool -printcert command to make sure that the certificate is correct.
Import the certificate into your application’s trust store.
The Key Tool utility’s -import option installs a certificate from a certificate file in a specified trust store. For example, if your client application’s trust store is kept in the file /local/tmp/imqhttps/appKeyStore, the following command will install the certificate from the file slas.cer created above:
keytool -import -file slas.cer -keystore "/local/tmp/imqhttps/appKeyStore"
You can deploy the HTTP or HTTPS tunnel servlet on Sun Java System Application Server either from the command line or by using the Application Server’s Web-based administration GUI. In either case, you must then modify the Application Server’s security policy file to grant permissions for the tunnel servlet.
To deploy the tunnel servlet from the command line, use the deploy subcommand of the Application Server administration utility (asadmin): for example,
asadmin deploy --user admin --passwordfile pfile.txt --force=true /local/tmp/imqhttps/imqhttps.war
The procedure below shows how to use the Web-based GUI to deploy the servlet.
After deploying the tunnel servlet (whether from the command line or with the Web-based GUI), proceed to Modifying the Application Server’s Security Policy File for instructions on how to grant it the appropriate permissions.
Deploy the tunnel servlet:
Specify the .war file location:
Enter the location of the tunnel servlet’s Web archive file (imqhttp.war or imqhttps.war) in the File Path text field.
The file is located in the Message Queue installation directory containing .jar, .war, and .rar files, depending on your operating system platform (see Appendix A, Platform-Specific Locations of Message Queue Data).
Click the OK button.
Specify the context root directory:
Enter the /contextRoot portion of the tunnel servlet’s URL.
The URL has the form
http://hostName:portNumber/contextRoot/tunnel
or
https://hostName:portNumber/contextRoot/tunnel
For example, if the URL for the tunnel servlet is
http://hostName:portNumber/imq/tunnel
the value you enter would be
/imq
Click the OK button.
A confirmation screen appears, showing that the tunnel servlet has been successfully deployed and is enabled by default. The servlet is now available at the URL
http://hostName:portNumber/contextRoot/tunnel
or
https://hostName:portNumber/contextRoot/tunnel
where contextRoot is the context root directory you specified in step a above. Clients can now use this URL to connect to the message service using an HTTP or HTTPS connection.
Modify the server’s security policy file
Once you have deployed the HTTP or HTTPS tunnel servlet, you must grant it the appropriate permissions by modifying the Application Server’s security policy file, as described in the next procedure.
Each Application Server instance has a security policy file specifying its security policies or rules. Unless modified, the default security policies would prevent the HTTP or HTTPS tunnel servlet from accepting connections from the Message Queue message broker. In order for the broker to connect to the tunnel servlet, you must add an additional entry to this policy file:
Open the security policy file.
The file is named server.policy and resides at a location that varies depending on your operating system platform. On the Solaris platform, for example, the policy file for server jeeves would be located at
appServerRoot/glassfish/domains/domain1/jeeves/config/server.policy
where appServerRoot is the root directory in which Sun Java System Application Server is installed.
Add the following entry to the file:
grant codeBase "file:appServerRoot/glassfish/domains/domain1/jeeves /applications/j2ee-modules/imqhttps/- { permission java.net.SocketPermission "*","connect,accept,resolve"; };
Save and close the security policy file.
HTTP/HTTPS support is not activated for a broker by default, so before connecting using these protocols, you need to reconfigure the broker to activate the httpjms or httpsjms connection service. Table C–2 shows broker configuration properties pertaining specifically to these two connection services. Once reconfigured, the broker can be started normally, as described under Starting Brokers.
Table C–2 Broker Configuration Properties for the httpjms and httpsjms Connection Services
Open the broker’s instance configuration file.
The instance configuration file is named config.properties and is located in a directory identified by the name of the broker instance to which it belongs:
…/instances/instanceName/props/config.properties
(See Appendix A, Platform-Specific Locations of Message Queue Data for the location of the instances directory.)
Add httpjms or httpsjms to the list of active connection services.
Add the value httpjms or httpsjms to the imq.service.activelist property: for example,
imq.service.activelist=jms,admin,httpjms
or
imq.service.activelist=jms,admin,httpsjms
Set any other HTTP/HTTPS-related configuration properties as needed.
At startup, the broker looks for an application server or Web server and an HTTP or HTTPS tunnel servlet running on its local host machine. If necessary, you can reconfigure the broker to access a remote tunnel servlet instead, by setting the servletHost and servletPort properties appropriately (see Table C–2): for example,
imq.httpjms.http.servletHost=helios imq.httpjms.http.servletPort=7675
You can also improve performance by reconfiguring the connection service’s pullPeriod property. This specifies the interval, in seconds, at which each client issues HTTP/HTTPS requests to pull messages from the broker. With the default value of -1, the client will keep one such request pending at all times, ready to pull messages as fast as possible. With a large number of clients, this can cause a heavy drain on server resources, causing the server to become unresponsive. Setting the pullPeriod property to a positive value configures the client’s HTTP/HTTPS transport driver to wait that many seconds between pull requests, conserving server resources at the expense of increased response times to clients.
The connectionTimeout property specifies the interval, in seconds, that the client runtime waits for a response from the HTTP/HTTPS tunnel servlet before throwing an exception, as well as the time the broker waits after communicating with the tunnel servlet before freeing 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 tunnel servlet has terminated abnormally.)
To make HTTP/HTTPS connections to a broker, a client application needs an appropriately configured connection factory administered object. Before configuring the connection factory, clients wishing to use secure HTTPS connections must also have access to SSL libraries provided by the Java Secure Socket Extension (JSSE) and must obtain a trusted root certificate.
If the root certificate of the certification authority (CA) that signed your application server’s (or Web server’s) certificate is not in the trust store by default, or if you are using a proprietary application server or Web server certificate, you must install the root certificate in the trust store. (This step is not needed for ordinary, non-secure HTTP connections, or if the CA’s root certificate is already in the trust store by default.)
Import the root certificate.
Execute the command
JRE_HOME/bin/keytool -import -trustcacerts -alias certAlias -file certFile -keystore trustStoreFile
where certFile is the file containing the root certificate, certAlias is the alias representing the certificate, and trustStoreFile is the file containing your trust store.
Confirm that you trust the certificate.
Answer YES to the question Trust this certificate?
Identify the trust store to the client application.
In the command that launches the client application, use the -D option to specify the following properties:
javax.net.ssl.trustStore=trustStoreFile javax.net.ssl.trustStorePassword=trustStorePassword
To enable HTTP/HTTPS support, you need to set the connection factory’s imqAddressList attribute to the URL of the HTTP/HTTPS tunnel servlet. The URL has the form
http://hostName:portNumber/contextRoot/tunnel
or
https://hostName:portNumber/contextRoot/tunnel
where hostName:portNumber is the host name and port number of the application server or Web server hosting the tunnel servlet and contextRoot is the context root directory you specified when deploying the tunnel servlet on the server, as described above under Step 4 (HTTP and HTTPS): Deploying the Tunnel Servlet.
You can set the imqAddressList attribute in any of the following ways:
Use the -o option to the imqobjmgr command that creates the connection factory administered object (see Adding a Connection Factory).
Set the attribute when creating the connection factory administered object using the Administration Console (imqadmin).
Use the -D option to the command that launches the client application.
Use an API call to set the attributes of the connection factory after you create it programmatically in client application code (see the Message Queue Developer’s Guide for Java Clients).
It is not necessary to configure multiple application or Web servers and tunnel servlets in order to access multiple brokers; you can share a single server instance and tunnel servlet among them. To do this, you must configure the imqAddressList connection factory attribute as follows:
http://hostName:portNumber/contextRoot/tunnel?ServerName=brokerHostName:instanceName
or
https://hostName:portNumber/contextRoot/tunnel?ServerName=brokerHostName:instanceName
where brokerHostName 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 values for brokerHostName and instanceName, generate a status report for the HTTP/HTTPS tunnel servlet by accessing the servlet URL from a browser:
http://localhost:8080/imqhttp/tunnel
The report lists all brokers being accessed by the servlet, as shown in Example C–1.
|
To use an HTTP proxy to access the HTTPS tunnel servlet, set the system properties http.proxyHost and http.proxyPort to the proxy server’s host name and port number. You can set these properties using the -D option to the command that launches the client application.
This section describes possible problems with an HTTP or HTTPS connection and provides guidance on how to handle them.
The consequences of a server or broker failure in an (HTTP or HTTPS) connection vary depending on the specific component that has failed:
If the application server or Web server fails and is restarted, all existing connections are restored with no effect on clients.
If the broker fails and is restarted, an exception is thrown and clients must reestablish their connections.
In the unlikely event that both the broker and the application server or Web server fail and the broker is not restarted, the application server or Web server will restore client connections and continue waiting for a broker connection without notifying clients. To avoid this situation, always restart the broker after a failure.
If an HTTPS client cannot connect to the broker through the tunnel servlet, do the following:
Start the tunnel servlet and the broker.
Use a browser to access the servlet manually through the 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.
Message Queue includes support for Java-based client programs to programmatically configure and monitor Message Queue resources by means of the Java Management Extensions (JMX) application programming interface. These resources include brokers, connection services, connections, destinations, durable subscribers, and transactions, Use of the JMX API from the client side is fully described in the Message Queue Developer’s Guide for JMX Clients. This appendix describes the JMX support infrastructure on the broker side, including the following topics:
The JMX API allows Java client applications to monitor and manage broker resources by programmatically accessing JMX MBeans (managed beans) that represent broker resources. As explained in the JMX-Based Administration in Sun Java System Message Queue 4.2 Technical Overview, the broker implements MBeans associated with individual broker resources, such as connection services, connections, destinations, and so forth, as well as with whole categories of resources, such as the set of all destinations on a broker. There are separate configuration MBeans and monitor MBeans for setting a resource’s configuration properties and monitoring its runtime state.
In the JMX implementation used by Message Queue, JMX client applications access MBeans using remote method invocation (RMI) protocols provided by JDK 1.5 (and later).
When a broker is started, it automatically creates MBeans that correspond to broker resources and places them in an MBean server (a container for MBeans). JMX client applications access the MBean server by means of an JMX RMI connector (heretofore called a JMX connector), which is used to obtain an MBean server connection, which, in turn, provides access to individual MBeans.
The broker also creates and configures two default JMX connectors, jmxrmi and ssljmxrmi. These connectors are similar to the broker connection services used to provide connections to the broker from JMS clients. By default, only the jmxrmi connector is activated at broker startup. The ssljmxrmi connector, which is configured to use SSL encryption, can be activated using the imq.jmx.connector.activelist broker property (see To Activate the SSL-Based JMX connector ).
JMX client applications programmatically access JMX MBeans by first obtaining an MBean server connection from the jmxrmi or ssljmxrmi connector. The connector itself is accessed by using a proxy object (or stub) that is obtained from the broker by the JMX client runtime, as shown in the following figure. Encapsulated in the connector stub is the port at which the connector resides, which is dynamically assigned each time a broker is started, and other connection properties.
JMX client applications obtain a JMX connector stub using an address called the JMX service URL. The value and format of the JMX service URL depends on how the broker's JMX support is configured:
Static JMX service URL. The JMX service URL specifies the location of the JMX connector stub in an RMI registry. When the broker is started, it creates the JMX connector stub and places it in the specified location in the RMI registry. This location is fixed across broker startups.
Dynamic JMX service URL.The JMX service URL contains the JMX connector stub as a serialized object. This URL is dynamically created each time the broker is started.
A JMX service URL has the following form:
service:jmx:rmi://brokerHost[:connectorPort]urlpath
where rmi://brokerHost[:connectorPort] specifies the host (and optionally a port) used by the JMX connector. By default the port is assigned dynamically on broker startup, but can be set to a fixed value for JMX connections through a firewall.
The urlpath portion of the JMX service URL depends on whether the JMX service URL is static (see Static JMX Service URL: Using an RMI Registry) or dynamic (see Dynamic JMX Service URL: Not Using an RMI Registry). In either case, you can determine the value of the JMX service URL by using the imqcmd list jmx subcommand (see the examples in RMI Registry Configuration).
By default, the broker does not use an RMI registry, and the JMX runtime obtains a JMX connector stub by extracting it from a dynamic JMX service URL. However, if the broker is configured to use an RMI registry, then JMX runtime uses a static JMX service URL to perform a JNDI lookup of the JMX connector stub in the RMI registry. This approach, illustrated in the following figure, has the advantage of providing a fixed location at which the connector stub resides, one that does not change across broker startups.
Message Queue also provides, as a convenience, an AdminConnectionFactory class that hides the details of the JMX Service URL and JMX connector stub. The Admin Connection Factory uses the Message Queue Port Mapper service to get the relevant JMX Service URL (regardless of the form being used) and thereby obtain a JMX connector stub. JMX applications that use the Admin Connection Factory only need to know the broker's host and Port Mapper port. The scheme is shown in the following figure.
For programmatic details, see Obtaining a JMX Connector from an Admin Connection Factory in Sun Java System Message Queue 4.2 Developer’s Guide for JMX Clients
Broker configuration properties that support JMX are listed in Table 16–12. These properties can be set in the broker's instance configuration file (config.properties) or at broker startup with the -D option of the Broker utility (imqbrokerd). None of these properties can be set dynamically with the Command utility (imqcmd). In addition, as described below, some of these properties can be set with corresponding imqbrokerd options.
This section discusses several JMX configuration topics:
You can configure the broker to do any of the following:
Start an RMI registry (imq.jmx.rmiregistry.start=true)
If the broker is configured to start an RMI registry, then the broker will do the following:
Start an RMI registry in the broker process. The RMI registry will remain operational during the lifetime of the broker.
Store the JMX connector stub for it's connectors in this RMI registry.
Advertise a static JMX Service URL that points to the relevant JMX connector stub in this registry.
Shut down the RMI registry as part of the broker shutdown process.
Use an existing RMI registry (imq.jmx.rmiregistry.use=true)
If the broker is configured to use an existing RMI registry on the local host, then the broker will do the following:
Expect an RMI registry to be running on the same host (at a port which can also be specified)
Store the JMX connector stub for it's connectors in this externally managed RMI registry.
Advertise a static JMX Service URL that points to the relevant JMX connector stub in this registry. This means the registry must remain operational during the lifetime of the broker.
Not shut down the RMI registry as part of the broker shutdown process.
Not use a registry at all (both imq.jmx.rmiregistry.start and imq.jmx.rmiregistry.use are set to false).
If the broker is configured to not use a registry, then the broker will advertise a dynamic JMX Service URL that contains the JMX connector stub as a serialized object.
The choice of using or not using an RMI registry depends upon whether you want a static or dynamic JMX Service URL, respectively. The advantages and disadvantages of using an RMI registry are shown in the following table.
Table D–1 Advantages and Disadvantages of Using an RMI Registry
Scenario |
Broker Configuration |
Advantages |
Disadvantages |
---|---|---|---|
Using a Registry (Static JMX Service URL) |
Configuration Properties: imq.jmx.rmigegistry.start imq.jmx.rmigegistry.use imq.jmx.rmigegistry.port |
The value of the JMX Service URL is constant across broker restarts. |
Broker depends on an RMI registry, either one it starts or one that is externally available. There is therefore one more port to worry about with regard to port conflicts or firewall configurations. |
Not Using a Registry (Dynamic JMX Service URL) |
Default |
Broker does not start up an RMI registry. There is therefore one less port to worry about with regard to port conflicts or firewall configurations. |
The value of the JMX Service URL changes at every broker startup. JMX applications need to be provided a new URL every time the broker restarts. (This is not an issue with JMX client applications that use the AdminConnectionFactory class.) |
If a registry is being used, the imq.jmx.rmiregistry.port property specifies the port number for the RMI registry. For convenience, you can also specify these RMI registry related properties by using equivalent Broker utility (imqbrokerd) options at broker startup: -startRmiRegistry, -useRmiRegistry, and -rmiRegistryPort, respectively (see Table 15–1).
When using an RMI Registry to store a JMX connector stub, the urlpath portion of the JMX service URL (see The JMX Service URL) does not change across broker startups and has the following form:
/jndi/rmi://brokerHost[:rmiPort]/brokerHost/portMapperPort/connectorName
This path consists of two segments:
/jndi/rmi://brokerHost[:rmiPort]
Specifies the RMI registry host and port at which the JMX contector stub is obtained by performing a JNDI lookup. The default port is 1099.
/brokerHost/portMapperPort/connectorName
Specifies the location within the RMI registry where the JMX connector stub is stored.
The following example shows the JMX service URL for the default jmxrmi connector in the case where an RMI registry is started on port 1098 on a host called yourhost:
# imqbrokerd -startRmiRegistry -rmiRegistryPort 1098
% imqcmd list jmx -u admin -passfile /myDir/psswds Listing JMX Connectors on the broker specified by: ------------------------- Host Primary Port ------------------------- localhost 7676 Name Active URL jmxrmi true service:jmx:rmi://yourhost/jndi/rmi://yourhost:1098 /yourhost/7676/jmxrmi ssljmxrmi false Successfully listed JMX Connectors. |
The JMX service URL could potentially contain a hostname and port three separate times, indicating the location of the JMX connector, the RMI registry, and the broker, respectively.
When not using an RMI Registry to store a JMX connector stub, the urlpath portion of the JMX service URL is dynamically generated at broker startup and has the following form:
/stub/rO0ABdmVyLlJlpIDJyGvQkwAAAARod97VdgAEAeA==
where the string following /stub/ is the is the serialized JMX connector stub encoded in BASE64 (shortened above for legibility)
The following example shows the JMX service URL for the default jmxrmi connector when no RMI registry is started by the broker and no existing registry is used.
# imqbrokerd
% imqcmd list jmx -u admin -passfile /myDir/psswds Listing JMX Connectors on the broker specified by: ------------------------- Host Primary Port ------------------------- localhost 7676 Name Active URL jmxrmi true service:jmx:rmi://yourhost/stub/rO0ABdmVyLlJlpIDJy== ssljmxrmi false Successfully listed JMX Connectors. |
If you need to have secure, encrypted connections between a JMX client and the broker's MBean server, then you need to configure both sides of the connection accordingly.
As mentioned in JMX Connection Infrastructure, a broker is configured by default for non-secure communication using the preconfigured jmxrmi connector. Applications wishing to use the Secure Socket Layer (SSL) for secure communication must activate the alternate ssljmxrmi connector. The ssljmxrmi connector is preconfigured with imq.jmx.connector.RMIconnectorName.useSSL=true.
Obtain and install a signed certificate.
The procedure is the same as for the ssljms, ssladmin, or cluster connection service, as described under Using Signed Certificates.
Install the root certification authority certificate in the trust store if necessary.
Add the ssljmxrmi connector to the list of JMX connectors to be activated at broker startup:
imq.jmx.connector.activelist=jmxrmi,ssljmxrmi
Start the broker.
Use the Broker utility (imqbrokerd), either passing it the keystore password in a passfile or typing it from at the command line when prompted.
Disable validation of certificates if desired.
By default, the ssljmxrmi connector (or any other SSL-based connector) is configured to validate all broker SSL certificates presented to it. Validation will fail if the signer of the certificate is not in the client's trust store. To avoid this validation (for instance, when using self-signed certificates during software testing), set the broker property imq.jmx.connector.ssljmxrmi.brokerHostTrusted to true.
On the client side, if the AdminConnectionFactory class is being used to obtain a JMX connector, the AdminConnectionFactory object must be configured with a URL specifying the ssljmxrmi connector:
AdminConnectionFactory acf = new AdminConnectionFactory(); acf.setProperty(AdminConnectionConfiguration.imqAddress, "mq://myhost:7676/ssljmxrmi");
In addition, if the JMX client needs to access the trust store, use the system properties javax.net.ssl.trustStore and javax.net.ssl.trustStorePassword to point the JMX client to the trust store. For example:
java -Djavax.net.ssl.trustStore=/tmp/myStrustsore -Djavax.net.ssl.trustStorePassword=myTurstword MyApp
If a JMX client application needs to connect to a broker that is located behind a firewall, the broker must be configured to use fixed JMX ports so the firewall can, in turn, be configured to allow traffic on these ports. The relevant ports are the following:
The port used by the JMX connector. The property used to configure this port is imq.jmx.connector.connectorName.port, where connectorName can be jmxrmi or ssljmxrmi.
The port used by the RMI registry, if any. The property used to configure this port is imq.jmx.rmiregistry.port. The equivalent command line option for imqbrokerd is -rmiRegistryPort.
Once these ports are specified, configure the firewall to allow traffic on these ports.
The following example starts a broker with no RMI registry and a jmxrmi connector on port 5656 on a host called yourhost, as follows:
# imqbrokerd -Dimq.jmx.connector.jmxrmi.port=5656
The resulting JMX service URL is:
service:jmx:rmi://yourhost:5656/stub/rO0ABdmVyLlJlpIDJy== |
The JMX service URL shows the connector port. In this case, you need to configure the firewall to allow traffic only on port 5656.
The following example starts a broker with an RMI registry on port 1098 and a jmxrmi connector on port 5656 on a host called yourhost, as follows:
# imqbrokerd -startRmiRegistry -rmiRegistryPort 1098 -Dimq.jmx.connector.jmxrmi.port=5656
The resulting JMX service URL is:
service:jmx:rmi://yourhost:5656/jndi/rmi://yourhost:1098 /yourhost/7676/jmxrmi |
The JMX service URL shows both these ports. You need to configure the firewall to allow traffic on ports 1098 and 5656.
This appendix lists some frequently used Message Queue Command utility ( imqcmd) commands. For a comprehensive list of command options and attributes available to you from the command line, refer to Command Utility in Command Utility
imqcmd subcommand argument [ options] imqcmd -h|H imqcmd -v
-H or -h provides comprehensive help. The -v subcommand provides version information.
When you use imqcmd, the Command utility prompts you for a password. To avoid the prompt (and to increase security), you can use the -passfile pathToPassfile option to point the utility to a password file that contains the administrator user name and password.
Example: imqcmd query bkr -u adminUserName -passfile pathToPassfile -b myServer:7676
imqcmd query bkr imqcmd pause bkr imqcmd restart bkr imqcmd resume bkr imqcmd shutdown bkr -b myBroker:7676 imqcmd update bkr -o "imq.system.max_count=1000" imqcmd reload cls
Broker Configuration Properties (-o option) lists frequently used broker configuration properties. For a full list of broker configuration properties and their descriptions, see Chapter 16, Broker Properties Reference
Table E–1 Broker Configuration Properties ( -o option)
Property |
Notes |
---|---|
imq.autocreate.queue | |
imq.autocreate.queue.maxNumActiveConsumers |
Specify -1 for unlimited |
imq.autocreate.queue.maxNumBackupConsumers |
Specify -1 for unlimited |
imq.autocreate.topic | |
imq.cluster.url | |
imq.destination.DMQ.truncateBody | |
imq.destination.logDeadMessages | |
imq.log.file.rolloverbytes |
Specify -1 for unlimited |
imq.log.file.rolloversecs |
Specify -1 for unlimited |
imq.log.level |
NONEERRORWARNINGINFO |
imq.message.max_size |
Specify -1 for unlimited |
imq.portmapper.port | |
imq.system.max_count |
Specify -1 for unlimited |
imq.system.max_size |
Specify -1 for unlimited |
imqcmd list svc imqcmd query svc imqcmd update svc -n jms -o "minThreads=200" -o "maxThreads=400" -o "port=8995" imqcmd pause svc -n jms imqcmd resume svc -n jms imqcmd list cxn -svn jms imqcmd query cxn -n 1234567890
imqcmd list dur -d MyTopic imqcmd destroy dur -n myDurSub -c "clientID-111.222.333.444" imqcmd purge dur -n myDurSub -c "clientID-111.222.333.444"
imqcmd list txn imqcmd commit txn -n 1234567890 imqcmd query txn -n 1234567890 imqcmd rollback txn -n 1234567890
imqcmd create dst -n MyQueue -t q -o "maxNumMsgs=1000" -o "maxNumProducers=5" imqcmd update dst -n MyTopic -t t -o "limitBehavior=FLOW_CONTROL| REMOVE_OLDEST|REJECT_NEWEST|REMOVE_LOW_PRIORITY" imqcmd compact dst -n MyQueue -t q imqcmd purge dst -n MyQueue -t q imqcmd pause dst -n MyQueue -t q -pst PRODUCERS|CONSUMERS|ALL imqcmd resume dst -n MyQueue -t q imqcmd destroy dst -n MyQueue -t q imqcmd query dst -n MyQueue -t q imqcmd list dst -tmp
Destination Configuration Properties (-o option) lists frequently used destination configuration properties. For a full list of destination configuration properties and their descriptions, see Chapter 17, Physical Destination Property Reference
Table E–2 Destination Configuration Properties (-o option)
Property |
Notes |
---|---|
consumerFlowLimit |
Specify -1 for unlimited |
isLocalOnly (create only) | |
limitBehavior |
FLOW_CONTROLREMOVE_OLDESTREJECT_NEWESTREMOVE_LOW_PRIORITY |
localDeliveryPreferred (queue only) | |
maxNumActiveConsumers (queue only) |
Specify -1 for unlimited |
maxNumBackupConsumers (queue only) |
Specify -1 for unlimited |
maxBytesPerMsg |
Specify -1 for unlimited |
maxNumMsgs |
Specify -1 for unlimited |
maxNumProducers |
Specify -1 for unlimited |
maxTotalMsgBytes |
Specify -1 for unlimited |
useDMQ |
imqcmd metrics bkr -m cxn|rts|ttl -int 5 -msp 20 imqcmd metrics svc -m cxn|rts|ttl imqcmd metrics dst -m con|dsk|rts|ttl