Secrets of the Configuration Manager in WebSphere Message Broker V6

Matt Lucas (lucas@uk.ibm.com), Software Developer, WebSphere Message Broker, IBM

Matt Lucas is a Software Developer on the WebSphere Message Broker Development team at the IBM Hursley Software Lab in the UK. He joined IBM in 1997, and since the release of WebSphere MQ V2.1 in 2001, he has been Development Team Leader for WebSphere Message Broker. He was responsible for the development of the WebSphere Message Broker Configuration Manager Proxy API and is now responsible for the administration architecture. In his spare time he enjoys the theatre, playing the piano, and playing far too many video games. You can contact Matt at lucas@uk.ibm.com.

Summary: The Configuration Manager has been an integral component of WebSphere Message Broker since the first release of MQSeries Integrator. Sitting squarely between the Message Broker Toolkit and the domain of brokers, the Configuration Manager drives deployment, polices access to brokers, and provides key status information to the administrator. Understanding the Configuration Manager and knowing how to manage it can therefore be vital to the survival of your domain, particularly if things go wrong. This article describes the benefits of the WebSphere Message Broker V6 Configuration Manager and its subcomponents, and show you some secret tips and tools to help you stay in control of your domain.

Tag this!

Date: 20 Jun 2007
Level: Intermediate
Activity: 1322 views
Comments:

What does the Configuration Manager do?

Of the three main components of IBM® WebSphere® Message Broker, the Configuration Manager’s benefits are perhaps the most difficult to define. The Message Broker Toolkit provides the application development and administration front-end, and the broker executes the message processing logic that you have defined. The Configuration Manager sits between the two: a service that passes message flows and their dependencies to the broker, and shuffles status information back to the toolkit; an electronic errand boy.

But the Configuration Manager’s benefits are understated. Firstly, its positioning means that not only is it best placed to provide a centralised security model to all brokers in the domain (thus ensuring that only authorised users can control your deployed resources), it also reduces the load on the brokers by directly dealing with status requests from the Message Broker Toolkit and other Configuration Manager Proxy applications.

How many Configuration Managers do you need?

Each Configuration Manager is responsible for a single domain of brokers, but the word domain is not always clearly defined; for example, how many brokers constitute a domain? In a publish/subscribe (pub/sub) environment, the definition is straightforward: the Configuration Manager provides coordinated deployment capabilities of the pub/sub topology and topic hierarchy, which means that a domain equates to the set of brokers that share a common topic hierarchy and/or have the potential to share publications and subscriptions.

But when not using the Message Broker as a pub/sub provider, the role of the domain, and therefore the decision of where to place your Configuration Manager and how many brokers to assign to it is a more complicated architectural and manageability one.

For many administrators, a domain corresponds to a single environment that defines the lifecycle of developed assets through an organization, such as a development domain, a test/QA domain, and a production domain. But this arrangement is not mandatory, and with the introduction of WebSphere Message Broker V6 and the capability to install Configuration Managers on all platforms supported by the broker, it is a lot easier to place and organize Configuration Managers (and therefore domains) so that they can manage your brokers in a way that’s most convenient for the administrator. At one extreme, you could define one Configuration Manager to manage your entire organisation; at the other extreme you could define one Configuration Manager per broker. Both are valid topologies.

Usually, the best balance of brokers-per-domain depends on the size of your Message Broker infrastructure and the importance you give to a centrally managed environment. Having one or a few Configuration Managers simplifies administration: controlling access to each broker from within the Configuration Manager means that access information is controlled from a single place, and your domain administrators can access a large number of resources from a single entry point. On the other hand, associating one broker with each Configuration Manager, perhaps so that they share the same queue manager, provides more isolation, and the tighter component coupling lets you manage the two components as one and perhaps save on administration costs.

Of course, advice on Configuration Manager placement is all very well if you are planning a new domain, but more difficult if you have an existing environment that you wish to tweak. Thankfully, you can move Configuration Managers between machines, and WebSphere Message Broker V6 Configuration Manager provides commands for doing so -- -- mqsibackupconfigmgr and mqsirestoreconfigmgr -- which are desribed below.

Configuration Manager resources

In order to understand how to maintain the Configuration Manager after it has been created, you need to be aware of the different resources that it requires. There are stateless MQ resources that are used by the Configuration Manager to communicate with the other Message Broker components, and data structures that define the Configuration Manager’s state. For the Configuration Manager’s MQ configuration, three standard queues are required:

SYSTEM.BROKER.CONFIG.QUEUE: Configuration Manager Proxy applications put requests on this queue that are read by the Configuration Manager.
SYSTEM.BROKER.CONFIG.REPLY: Configuration Manager Proxy applications read messages from this queue that are posted by the Configuration Manager.
SYSTEM.BROKER.ADMIN.REPLY: The broker puts its status messages on this queue, which are read by the Configuration Manager.

Additionally, each broker has a SYSTEM.BROKER.ADMIN.QUEUE, which the Configuration Manager uses to put deployment messages to the broker. The queue configuration is shown below:

Figure 1. Queue configuration

Configuration Manager Proxy applications communicate with the Configuration Manager’s queue manager using the WebSphere MQ Classes for Java. The Configuration Manager Proxy puts messages to the Configuration Manager input queue and listens for messages on the reply queue that are addressed to that Configuration Manager Proxy session using a unique correlation ID.

This MQ configuration is used solely for message passing; no state is permanently held in the queues, and it is assumed that any work conveyed through the queues is completed (and therefore the queues are empty) before maintenance takes place on the Configuration Manager. Therefore it is reasonable to exclude the MQ configuration from the discussion of persistent state. With this in mind, there are two data structures that define the Configuration Manager’s state: the registry and the repository:

Registry: Names all components that exist on a machine, and is used by commands such as mqsilist. On Microsoft® Windows® it lives in the Windows registry branch HKEY_LOCAL_MACHINE\SOFTWARE\IBM\WebSphereMQIntegrator. On UNIX and Linux it lives in /var/mqsi/registry. On z/OS it is the component directory. But other than defining the fact that the component exists, the Configuration Manager does not store much information in this registry; in fact, all of the information is derived from the parameters supplied to the mqsicreateconfigmgr command.
Repository: Contains the rest of the Configuration Manager state, as a set of files in an internal format in the directory specified by the environment variable MQSI_WORKPATH (which defaults to C:\Documents and Settings\All Users\Application Data\IBM\MQSI\ on Windows). There you will see the a directory called components, which contains a directory named after the Configuration Manager, and inside that is a directory with the constant name BERNARD, which is the repository (named after the Configuration Manager development team’s pet gargoyle).

With all of the Configuration Manager’s state in the repository and registry structures, moving a Configuration Manager means transferring both of these items. However, as discussed earlier, you can easily regenerate the registry data using the mqsicreateconfigmgr command (which also happens to create the stateless MQ resources). Therefore, you can safely ignore those parts of the Configuration Manager for backup purposes. And for the repository, WebSphere Message Broker V6 provides the command mqsibackupconfigmgr, which simply creates a zipped copy of the BERNARD directory, and mqsirestoreconfigmgr, which copies it back.

Therefore, to back up a Configuration Manager:

Stop the Configuration Manager, in order to prevent changes to the repository from occurring while the backup is taking place.
Issue the mqsibackupconfigmgr command to copy the repository to a safe place.

And to restore it (on the same or a different machine):

Use mqsicreateconfigmgr to create the registry and MQ resources.
Use mqsirestoreconfigmgr to copy the stored repository into the active Configuration Manager's repository.

Typically that is all you need to do, although there is one additional step if you have moved the Configuration Manager onto a different queue manager. Each broker in the domain must know the name of the queue manager on which its Configuration Manager resides, so that it can publish status messages to it. A single complete deploy of the topology will cause this reconfiguration to occur for all brokers in the domain.

Manipulating the Configuration Manager repository

If you encounter problems in your domain, it is useful to know the contents of the repository. The best visualisation of this information is through an application that uses the Configuration Manager Proxy (such as the Broker Administration perspective of the Message Broker Toolkit). This API, as the name suggests, is a remote proxy (or window) to the Configuration Manager repository. Not only does it provide easy-to-use methods that describe the properties of the objects in the domain (guess what getExecutionGroups() does?), it also provides additional capabilities that can help you diagnose and fix problems. You can invoke these methods from either your own Java™ programs, or from the Configuration Manager Proxy API Exerciser Sample, available from the Windows Start Menu.

Three particularly useful methods are:

TopologyProxy.removeDeletedBroker(String): Causes the Configuration Manager to go through its repository and completely clean any references to the broker with the name or UUID that is supplied as a parameter. Useful if a previous broker deletion failed and left partially deleted brokers in the repository.
BrokerProxy.forceSubscribe(): Asks the Configuration Manager to register or re-register for status messages on a broker, which are used to communicate (among other things) when message flows start and stop. This internal registration usually occurs automatically after the first successful deployment to a broker, but if this fails and you receive the error BIP1536 (Unable to register for internal subscriptions), you can use the forceSubscribe() method to attempt the registration again. It is important to solve this probleme, because without these internal subscriptions in place, the message flow status reported by the Configuration Manager may be incorrect.
BrokerProxy.setUUID(String): If you try to force a Configuration Manager to take ownership of a broker created under a different Configuration Manager, you are likely to receive the BIP2045 error message, which means that the unique identifier (UUID) of the broker is not the same as the one the new Configuration Manager attempted to assign. This method attempts to fix the problem by modifying the UUID that the Configuration Manager holds for that broker. There are several caveats associated with this method, which are ably explained in the BIP2045 error message documentation – issue the command mqsiservice –m 2045. Alternatively, you can read the Java documentation for the setUUID() method.

The Configuration Manager Proxy has many more capabilities, such as precisely controlling deployment, and configuring access control lists remotely. For more information on them, play with the Configuration Manager Proxy API Exerciser, or read the Java API documentation.

Figure 2. Demonstrating the removeDeletedBroker() method in the Configuration Manager Proxy API Exerciser

More about the repository

The Configuration Manager Proxy is the most convenient way of visualising the contents of the repository. However, for more experienced users it is occasionally useful to view the raw data that is held by the Configuration Manager, without the data conversion and type-checking that the remote API provides.

The Windows command mqsicmrv (Configuration Manager Repository Viewer) followed by the name of the Configuration Manager can be used to precisely see the tables that comprise the repository, as shown in the diagram below:

Figure 3. Configuration Manager Repository Viewer

The rows define the different tables in the repository. For problem diagnosis, the most interesting ones are:

CBROKER: Contains records of the brokers that have been defined in the Configuration Manager; their names, descriptions, queue manager names and links to any execution group documents that have been defined.
CEG: Contains records of the execution groups that have been defined in the Configuration Manager, including links to any objects that have been successfully deployed to them.
CMSGFLOW: Contains records of the message flows that have been successfully deployed in the domain.
CTOPOLOGY: Contains links to the set of brokers that have been defined in the domain and any publish/subscribe topology that exists.
CSUBSCRIBE: Contains list of all pub/sub subscriptions active in the domain, including any internal status message subscriptions between the brokers and the Configuration Manager.
CLOG: Contains all the log messages from the broker that were issued in the last 72 hours.
CPROXY: Contains details of all the connected Configuration Manager Proxy applications; the Configuration Manager uses this information to inform the relevant Configuration Manager Proxy applications when the status or properties of any domain object used by each application changes.
CPROXYCRESOURCE: Describes which domain objects each Configuration Manager Proxy application described in the CPROXY table is interested in, for the communication of status changes.
CACLGROUPS: Contains the Configuration Manager’s access control entries list.

If you browse through the list of domain objects you'll see that many have two entries – shared and deployed. Shared entries describe the object as currently defined in the Configuration Manager; in other words, properties that may have been changed by a Configuration Manager Proxy application but have not yet been deployed to a broker. Deployed entries describe the status of the object as confirmed by the broker. After making changes in the domain, but before a successful deployment is completed, the two entries may not be the same.

You may occasionally see entries in a graveyard section, which means that the Configuration Manager has been told by a Configuration Manager Proxy application to delete the object in question, but the Configuration Manager has not received a confirmation from the broker that the object has gone away (the removeDeletedBroker() method described earlier will remove all occurrences of deleted brokers, even ones in the graveyard.)

Figure 4 shows a domain with one broker defined. It has been successfully deployed, as it is showing both shared and deployed entries, and the selected entry describes the XML that defines the deployed characteristics of the broker.

Figure 4. Viewing broker information in the Configuration Manager Repository Viewer

There is a second command called mqsicmdt (Configuration Manager Display Table), which takes the Configuration Manager’s name and a table name that gives a textual view of the repository. Running this command against the Configuration Manager described above reveals:

WMB 6.0>mqsicmdt WBRK6_DEFAULT_CONFIGURATION_MANAGER CBROKER

Row 1
CUUID - 4fe43705-0b01-0000-0080-87d8950e7d9d
CSECTION - SHARED
CNAME - WBRK6_DEFAULT_BROKER
CQMANAGER - WBRK6_DEFAULT_QUEUE_MANAGER
CSTATUS - 10000000
CSUBSCRIBED - N
CXMLDATA - <?xml version="1.0" encoding="UTF-8"?><Broker
    configMgrQMgr="WBRK6_DEFAULT_QUEUE_MANAGER" longDescription=""
     shortDescription="" xmi.id="4fe43705-0b01-0000-0080-87d8950e7d9d"
     xmi.label="WBRK6_DEFAULT_BROKER"
     xmi.uuid="4fe43705-0b01-0000-0080-87d8950e7d9d">
     <Broker_queueManager value="WBRK6_DEFAULT_QUEUE_MANAGER"
     xmi.label="queueManager"/><ExecutionGroupRef
     href="ExecutionGroup/48c21a4a-0c01-0000-0080-f544e2d04c87"
     title="default"/></Broker>
CLASTUPDATE - 2006-07-07 18:48:23.484

Row 2
CUUID - 4fe43705-0b01-0000-0080-87d8950e7d9d
CSECTION - DEPLED
CNAME - WBRK6_DEFAULT_BROKER
CQMANAGER - WBRK6_DEFAULT_QUEUE_MANAGER
CSTATUS - 10000100
CSUBSCRIBED - Y
CXMLDATA - <?xml version="1.0" encoding="UTF-8"?><Broker
     configMgrQMgr="WBRK6_DEFAULT_QUEUE_MANAGER" longDescription=""
     shortDescription="" status="started"
     xmi.id="4fe43705-0b01-0000-0080-87d8950e7d9d"
     xmi.label="WBRK6_DEFAULT_BROKER"
     xmi.uuid="4fe43705-0b01-0000-0080-87d8950e7d9d">
     <Broker_queueManager value="WBRK6_DEFAULT_QUEUE_MANAGER"
     xmi.label="queueManager"/><ExecutionGroupRef
     href="ExecutionGroup/48c21a4a-0c01-0000-0080-f544e2d04c87"
     icon="" refType="ExecutionGroup" title="default"
     type="ExecutionGroup" xmi.label="ExecutionGroup"
     xml:link="simple"/></Broker>
CLASTUPDATE - 2006-07-07 18:48:23.484
			
Exit
			
WMB 6.0>

This example shows two rows in the repository – note the differing values of CSECTION, which determines whether the row contains shared or deployed information.

A final word of caution about mqsicmdt and mqsicmrv: do not rely on the information provided by these commands to remain constant from release to release, or even from fixpack to fixpack. The commands are only for diagnosing problems.

Tracing the Configuration Manager

One benefit of running the Configuration Manager on z/OS is that by default, it reveals (via the job log) information on all messages that pass through the Configuration Manager, which makes it easy to see what the component is doing. You can also enable this behavior on Windows, by running the component in the foreground instead of as a service:

mqsistop [CMNAME]
set MQSI_CONSOLEMODE=1
bipconfigmgr [CMNAME]

On UNIX and Linux, the commands are:

mqsistop [CMNAME]
export MQSI_CONSOLEMODE=1
export MQSIJVERBOSE=-DMQSI_CONSOLEMODE=1
bipconfigmgr [CMNAME]

Not only does running the Configuration Manager in the foreground describe the messages that pass through it, it also reveals detailed technical information about the environment in which the component is being asked to run: the CLASSPATH, version, OS, JRE and the place where various internal files are loaded, all invaluable if you experience errors on start-up.

The disadvantage of running in this mode is that the Configuration Manager is no longer started as a Windows service; it instead runs in a console window that will cause the Configuration Manager to stop if this window closes or the user logs out, and it will not automatically restart.

If this information does not help you to diagnose a problem you encounter, more detailed trace is available through the mqsichangetrace, mqsireadlog and mqsiformatlog commands, which are documented in the product information center. However, it is also possible to enable this trace through the Message Broker registry, which is useful if you need to gather service trace when running mqsichangetrace is not an option; for example, if you have problems starting the Configuration Manager. The two keys are in the Configuration Manager registry folder (along with the QueueManagerName and FADLevel keys):

Trace: Denotes the level of service tracing to enable: none, normal, or debug
TraceSize: Denotes the maximum size in KB of the service trace file. This key is particularly useful because you cannot configure the size using the mqsichangetrace command.

For more information see Figure 5:

Figure 5. Configuring trace settings in the Windows registry

If you set these registry keys, be careful to enter the information correctly and remember to set the Trace key back to none when you're done. Also, remember that service trace is typically useful only to IBM support personnel, so if you need to enable service trace in order to fix a problem, or even if you have to start looking at the contents of the repository, then consider giving IBM a call.

Conclusion

This article has described in some depth the WebSphere Message Broker V6 Configuration Manager, including its capabilities and how it communicates with the other Message Broker components. The article also showed you how to diagnose and fix problems using the Configuration Manager Proxy and other tools that are part of WebSphere Message Broker V6.

Resources

WebSphere Message Broker developer resources page
Technical resources to help you use WebSphere Message Broker for connectivity, universal data transformation, and enterprise-level integration of disparate services, applications, and platforms to power your SOA.
WebSphere Message Broker product page
Product descriptions, product news, training information, support information, and more.
WebSphere Message Broker information center
A single Eclipse-based Web portal to all WebSphere Message Broker V6 documentation, with conceptual, task, and reference information on installing, configuring, and using your WebSphere Message Broker environment.
WebSphere Message Broker documentation library
WebSphere Message Broker specifications and manuals.
WebSphere Message Broker forum
Get answers to your technical questions and share your expertise with other WebSphere Message Broker users.
WebSphere Message Broker support page
A searchable database of support problems and their solutions, plus downloads, fixes, problem tracking, and more.
developerWorks WebSphere Business Integration zone
For developers, access to WebSphere Business Integration how-to articles, downloads, tutorials, education, product info, and more.
WebSphere Business Integration products page
For both business and technical users, a handy overview of all WebSphere Business Integration products
WebSphere forums
Product-specific forums where you can get answers to your technical questions and share your expertise with other WebSphere users.
Most popular WebSphere trial downloads
No-charge trial downloads for key WebSphere products.
Trial downloads for IBM software products
No-charge trial downloads for selected IBM® DB2®, Lotus®, Rational®, Tivoli®, and WebSphere® products.
Technical books from IBM Press
Convenient online ordering through Barnes & Noble.
developerWorks technical events and Webcasts
Free technical sessions by IBM experts that can accelerate your learning curve and help you succeed in your most difficult software projects. Sessions range from one-hour Webcasts to half-day and full-day live sessions in cities worldwide.

About the author

Comments

Trademarks | My developerWorks terms and conditions

Close [x]

Help: Update or add to My dW interests

What's this?

This little timesaver lets you update your My developerWorks profile with just one click! The general subject of this content (AIX and UNIX, Information Management, Lotus, Rational, Tivoli, WebSphere, Java, Linux, Open source, SOA and Web services, Web development, or XML) will be added to the interests section of your profile, if it's not there already. You only need to be logged in to My developerWorks.

And what's the point of adding your interests to your profile? That's how you find other users with the same interests as yours, and see what they're reading and contributing to the community. Your interests also help us recommend relevant developerWorks content to you.

View your My developerWorks profile

Return from help

Close [x]

Help: Remove from My dW interests

What's this?

Removing this interest does not alter your profile, but rather removes this piece of content from a list of all content for which you've indicated interest. In a future enhancement to My developerWorks, you'll be able to see a record of that content.

View your My developerWorks profile

Return from help

static.content.url=http://www.ibm.com/developerworks/js/artrating/

SITE_ID=1

Zone=WebSphere

ArticleID=232262

ArticleTitle=Secrets of the Configuration Manager in WebSphere Message Broker V6

publish-date=06202007

author1-email=lucas@uk.ibm.com

author1-email-cc=