What's New in The 4.1 Release (Sun Java System Message Queue 4.1 Release Notes)

Sun Java System Message Queue 4.1 Release Notes

What's New in The 4.1 Release

Message Queue 4.1 introduces high availability (data and service availability) broker clusters, JAAS support, and various other minor features. This section describes these features and provides further references for your use.

High Availability

Message Queue 4.1 introduces high availability clusters, which provide data availability as well as service availability. If a client loses its connection to a high availability broker, it is automatically reconnected to another broker in a cluster. The broker that provides the new connection takes over the failed broker's persistent data and state, and continues to provide uninterrupted service to the failed broker's clients. You can run high availability brokers over a secure connection.

High availability brokers require the use of a highly available database (HADB). If you do not have such a database or if data availability is not important to you, you can continue to use conventional clusters, which offer automatic reconnection and service availability.

Configuring high availability brokers is simple: you specify the following kinds of broker properties for each broker in the cluster.

Cluster membership properties, which specify that the broker is part of a high availability cluster, the id of the cluster, and the id of the broker.
Highly available database (HADB) properties, which specify the model for persistent messages (JDBC), the name of the HADB vendor, and vendor-specific configuration properties for the database.
Failure detection and takeover properties, which specify how broker failure should be detected and handled.

To use this feature, you must do the following:

Install a highly available database.
Install the JDBC driver's .jar file.
Create the database schema for the highly available persistent store.
Set those properties that are related to high availability for each broker in the cluster.
Start each broker in the cluster.

For a conceptual discussion of high availability and how it compares to conventional clusters, see Chapter 4, Broker Clusters, in Sun Java System Message Queue 4.1 Technical Overview. For procedural and reference information about high availability, see Chapter 8, Broker Clusters, in Sun Java System Message Queue 4.1 Administration Guide and Cluster Configuration Properties in Sun Java System Message Queue 4.1 Administration Guide.

If you were using an HADB database with Message Queue version 4.0 and want to use a high availability cluster, you can use the dbmgr utility to upgrade to a shared HADB store. See Broker Clusters for more information.

JAAS Support

In addition to the file-based and LDAP-based built-in authentication mechanisms, Message Queue also supports the Java Authentication and Authorization Service (JAAS), which allows you to plug a variety of services into the broker to authenticate Message Queue clients. This section describes the information that the broker makes available to a JAAS-compliant authentication service, and it explains how you configure the broker to use such a service.

It is beyond the scope of this document to describe the JAAS API. Please consult the following sources if you need to know more.

For complete information about the JAAS API, please see the Java Authentication and Authorization Service (JAAS) Reference Guide.

http://java.sun.com/j2se/1.5.0/docs/guide/security/jaas/JAASRefGuide.html
For information about writing a LoginModule, please see the Java Authentication and Authorization Service (JAAS) LoginModule Developer's Guide.

http://java.sun.com/j2se/1.5.0/docs/guide/security/jaas/JAASLMDevGuide.html

The JAAS API is a core API in J2SE and therefore it is an integral part of Message Queue's runtime environment. JAAS defines an abstraction layer between an application and an authentication mechanism, allowing the desired mechanism to be plugged in with no change to application code. In the case of the Message Queue service, the abstraction layer lies between the broker (application) and an authentication provider. By setting a few broker properties, it is possible to plug in any JAAS-compliant authentication service and to upgrade this service with no disruption or change to broker code.

You can use JMX clients to manage the broker if you are using JAAS-based authentication, but you must manually set up JAAS support (by setting JAAS-related broker properties) before you start the broker. You cannot use the JMX API to change those properties.

Elements of JAAS

Figure 1–1 shows the basic elements of JAAS: a JAAS client, a JAAS-compliant authentication service, and a JAAS configuration file.

The JAAS client is an application that wants to perform authentication using a JAAS-compliant authentication service. It communicates with this service using a LoginModule and it is responsible for providing a callback handler that the LoginModule can call to obtain the user name, password, and other relevant information.
The JAAS-compliant Authentication Service consists of one or more LoginModule and of logic that performs the needed authentication. The LoginModule may include the authentication logic, or it may use a private protocol or API to communicate with a module that provides that logic.
The JAAS configuration file is a text file that the JAAS client uses to locate the LoginModule(s) needed to communicate with the JAAS-compliant service.

Figure 1–1 JAAS Elements

This figure shows the elements required for JAAS-compliant
authentication. The text that introduces the figure explains its content.

The next section explains how the Message Queue service uses these elements to provide JAAS-compliant authentication.

JAAS and Message Queue

The next figure shows how JAAS is used by the Message Queue broker. It shows a more complex implementation of the JAAS model shown in the previous figure.

Figure 1–2 How Message Queue Uses JAAS

The figure shows how JAAS-compliant authentication is
used with Message Queue. The text that follows the figure explains its contents.

As was shown in the simpler case, the authentication service layer is separate from the broker. The authentication service consists of one or more login modules (LoginModule) and of additional authentication modules if needed. The login modules run in the same Java virtual machine as the broker. The Message Queue broker is represented to the login module as a LogInContext and it communicates with the login module by means of a CallBackHandler that is part of the broker runtime code.

The authentication service also supplies a JAAS configuration file that contains entries to the login modules. The configuration file specifies the order in which the modules are to be used and some conditions for their use. When the broker starts up, JAAS locates the configuration file by the Java system property java.security.auth.login.config or the Java security properties file. It then selects an entry in the JAAS configuration file, according to the value of the broker property imq.user_repository.jaas.name. That entry specifies which login modules will be used for authentication. As the figure shows, it is possible for the broker to use more than one login module. (The relation between the configuration file, the login module, and the broker is shown in Figure 1–3.)

The fact that the broker uses a JAAS plug-in authentication service remains completely transparent to the Message Queue client. The client continues to connect to the broker as it did before, passing a user name and password. In turn, the broker uses a callback handler to pass this information to the authentication service, and the service uses that information to authenticate the user and return the results. If authentication succeeds, the broker grants the connection; if it fails, the client runtime returns a JMS security exception that the client must handle.

After the Message Queue client is authenticated, if there is further authorization to be done, the broker proceeds as it would normally; it consults the access control file to determine whether the authenticated client is authorized to perform the actions it undertakes: accessing a destination, consuming a message, browsing a queue, and so on.

Setting up JAAS-Compliant Authentication

Setting up JAAS-compliant authentication involves setting broker and system properties to select this type of authentication, to specify the location of the configuration file, and to specify the entries to the login modules that are going to be used.

This section illustrates how the JAAS client, the login modules, and the JAAS configuration file are related and then describes the process required to set up JAAS-compliant authentication. The next figure shows the relation between the configuration file, the login module, and the broker.

Figure 1–3 Setting Up JAAS Support

This figure shows the relationship between JAAS-related
files. The text following the figure explains its content.

As shown in the figure, the JAAS configuration file, MyJAASCFile.config contains references to several login modules, grouped in an entry point. The broker locates the configuration file by consulting the Java system property java.security.auth.login.config or by consulting the Java Security properties file. The login modules to be used are determined by consulting the broker property imq.user_repository.jaas.name, which specifies the desired entry in the configuration file. The classes for those modules are found in the lib/ext directory.

To set up JAAS support for Message Queue, you must complete the following steps. (In a development environment all these steps might be done by the developer. In a production environment, the administrator would take over some of these tasks.)

Create one or more login module classes that implement the authentication service. The JAAS callback types that the broker supports are listed below.

javax.security.auth.callback.LanguageCallback

The broker uses this callback to pass the authentication service the locale in which the broker is running This value can be used for localization.

javax.security.auth.callback.NameCallback

The broker uses this callback to pass to the authentication service the user name specified by the Message Queue client when the connection was requested.

javax.security.auth.callback.TextInputCallback

The broker uses this callback to specify the value of imq.authentication.type to the authentication service when the TextInputCallback.getPrompt() is imq.authentication.type. Right now, the only possible value for this field is basic. This indicates Base-64 password encoding.

javax.security.auth.callback.PasswordCallback

The broker uses this callback to pass to the authentication service the password specified by the Message Queue client when the connection was requested.

javax.security.auth.callback.TextOutputCallback

The broker uses this callback to provide logging services to the authentication service by logging the text output to the broker's log file. The callback's MessageType ERROR, INFORMATION, WARNING are mapped to the broker log levels ERROR, INFO, and WARNING respectively.
Create a JAAS configuration file with entries that reference the login module classes and specify the location of this file to the Message Queue administrator. (The file can be located remotely, and its location can be specified with a url.)
Note the name of the entry (that references the login implementation classes) in the JAAS configuration file.
Archive the classes that implement the login modules to a jar file, and place the jar file in the Message Queue lib/ext directory.
Configure the broker properties that relate to JAAS support. These are described in Table 1–2.
Set the following system property to specify the location of the JAAS configuration file.

java.security.auth.login.config=JAAS_Config_File_Location

For example, you can specify the configuration file when you start the broker.

imqbrokerd -Djava.security.auth.login.config=JAAS_Config_File_Location

There are other ways to specify the location of the JAAS configuration file. For additional information, please see

http://java.sun.com/j2se/1.5.0/docs/guide/security/jaas/tutorials/LoginConfigFile.html

The following table lists the broker properties needed to set up JAAS support.

Table 1–2 Broker Properties for JAAS Support


Property	Description
`imq.authentication.type`	Set to `basic` to indicate Base-64 password encoding. This is the only permissible value for JAAS authentication.
`imq.authentication.basic.user_repository`	Set to `jaas` to specify JAAS authentication.
`imq.accesscontrol.type`	Set to `file.`
`imq.user_repository.jaas.name`	Set to the name of the desired entry (in the JAAS configuration file) that references the login modules you want to use as the authentication mechanism. This is the name you noted in Step 3.
`imq.user_repository.jaas.userPrincipalClass`	This property, used by Message Queue access control, specifies the `java.security.Principal` implementation class in the login module(s) that the broker uses to extract the Principal name to represent the user entity in the Message Queue access control file. If, it is not specified, the user name passed from the Message Queue client when a connection was requested is used instead.
`imq.user_repository.jaas.groupPrincipalClass`	This property, used by Message Queue access control, specifies the `java.security.Principal` implementation class in the login module(s) that the broker uses to extract the Principal name to represent the group entity in the Message Queue access control file. If, it is not specified, the group rules, if any, in the Message Queue access control file are ignored.

Persistent Store Format Change

Version 4.1 of Message Queue changes the JDBC store to support high availability. For this reason the JDBC store version is increased to 410. JDBC store versions 350, 370, and 400 are automatically migrated to the 410 version format.

Please note that the file-based persistent store version remains 370 because no changes were made to it.

Broker Configuration

The property IMQ_DEFAULT_EXT_JARS has been added to the imqenv.conf file. You can set this property to specify the path names of external .jar files to be included in CLASSPATH when the broker starts up. If you use this property to specify the location of external .jar files, you will no longer need to copy these files to the lib/ext directory. External jars can refer to JDBC drivers or to JAAS login modules. The following sample command, specifies the location of jdbc drivers.

IMQ_DEFAULT_EXT_JARS=/opt/SUNWhadb4/lib/hadbjdbc4.jar:/opt/SUNWjavadb/derby.jar

JES Monitoring Framework Support

Message Queue supports the Sun Java Enterprise System (JES) Monitoring Framework, which allows Java Enterprise System components to be monitored using a common graphical interface. This interface is implemented by a web-based console called the Sun Java System Monitoring Console. If you are running Message Queue along with other JES components, you might find it more convenient to use a single interface to manage all these components.

The JES monitoring framework defines a common data model (CMM) to be used by all JES component products. This model enables a centralized and uniform view of all JES components. Message Queue exposes the following objects to the JES monitoring framework:

the installed product
the broker instance name
the broker port mapper
each connection service
each physical destination
the persistent store
the user repository

Each one of these objects is mapped to a CMM object whose attributes can be monitored using the JES monitoring console. At runtime, administrators can use the console to view performance statistics, create rules to monitor automatically, and acknowledge alarms. For detailed information about the mapping of Message Queue objects to CMM objects, see the Sun Java Enterprise System Monitoring Guide.

To enable JES monitoring, you must do the following

Install and configure all the components in your deployment (Message Queue and other components) according to instructions given in the Sun Java Enterprise System Installation Guide.
Enable and configure the Monitoring Framework for all of your monitored components, as described in the Sun Java Enterprise System Monitoring Guide.
Install the Monitoring Console on a separate host, start the master agent, and then start the web server, as described in the Sun Java Enterprise System Monitoring Guide.

Using the JES Monitoring Framework will not impact broker performance because all the work of gathering metrics is done by the monitoring framework, which pulls data from the broker's existing monitoring data infrastructure.

Transaction Management

Previously, only transactions in a PREPARED state were allowed to be rolled back administratively. That is, if a session that was part of a distributed transaction did not terminate gracefully, the transaction remained in a state that could not be cleaned up by the broker administrator. In Message Queue 4.1, you can use the imqcmd utility to clean up (roll back) transactions that are in the following states: STARTED, FAILED, INCOMPLETE, COMPLETE, PREPARED.

To help you determine whether a particular transaction can be rolled back (especially when it is not in a PREPARED state), the imqcmd utility provides additional data as part of theimqcmd query txn output: it provides the connection id for the connection that started the transaction and specifies the time when the transaction was created. Using this information, the administrator can decide whether the transaction needs to be rolled back. In general, the administrator should avoid rolling back a transaction prematurely.

Fixed Ports for C Client Connections

C clients can use the MQ_SERVICE_PORT_PROPERTY connection property to specify a fixed port to connect to. This can be useful if you're trying to get through a firewall or if you need to bypass the broker's port mapper service (which assigns ports dynamically).

Remember that you need to configure the JMS service port on the broker side as well. For example, if you want to connect your client via ssljms to port 1756, you would do the following.

On the client side: Set the MQ_SERVICE_PORT_PROPERTY to 1756 and set the MQ_CONNECTION_TYPE_PROPERTY to SSL.
On the broker side: Set the imq.serviceNameType.protocol.port property to 1756 as follows.
```
imq.ssljms.ssl.port=1756
```

Note –

The MQ_SERVICE_PORT_PROPERTY connection property was introduced with version 3.7 Update 2 of Message Queue.