Sun Java System Message Queue 4.3 Administration Guide

JMX Configuration

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:

RMI Registry Configuration

You can configure the broker to do any of the following:

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).

Static JMX Service URL: Using an RMI Registry

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:


Example D–1 JMX Service URL When Using an RMI Registry

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.

Dynamic JMX Service URL: Not Using an RMI Registry

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)


Example D–2 JMX Service URL When Not Using an RMI Registry

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.

SSL-Based JMX Connections

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.

Broker Side SSL Configuration

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.

ProcedureTo Activate the SSL-Based JMX connector

  1. 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.

  2. Install the root certification authority certificate in the trust store if necessary.

  3. Add the ssljmxrmi connector to the list of JMX connectors to be activated at broker startup:

       imq.jmx.connector.activelist=jmxrmi,ssljmxrmi
    
  4. 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.

  5. 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.

JMX Client Side SSL Configuration

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

JMX Connections Through a Firewall

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:

Once these ports are specified, configure the firewall to allow traffic on these ports.


Example D–3 JMX Configuration for Firewall When Not Using a RMI Registry

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.



Example D–4 JMX Configuration for Firewall When Using an RMI Registry

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.