Sun GlassFish Message Queue 4.4 Administration Guide

Sun GlassFish Message Queue 4.
4 Administration Guide
Sun Microsystems, Inc. 4150 Network Circle Santa Clara, CA 95054 U.S.A.
Part No: 821002712 June 2010
Copyright 2009Sun Microsystems, Inc.
4150 Network Circle, Santa Clara, CA 95054 U.S.A.
This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited. The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing. If this is software or related software documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the following notice is applicable: U.S. GOVERNMENT RIGHTS Programs, software, databases, and related documentation and technical data delivered to U.S. Government customers are commercial computer software or commercial technical data pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, the use, duplication, disclosure, modification, and adaptation shall be subject to the restrictions and license terms set forth in the applicable Government contract, and, to the extent applicable by the terms of the Government contract, the additional rights set forth in FAR 52.227-19, Commercial Computer Software License (December 2007). Oracle America, Inc., 500 Oracle Parkway, Redwood City, CA 94065. This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications which may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications. Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. UNIX is a registered trademark licensed through X/Open Company, Ltd. This software or hardware and documentation may provide access to or information on content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services.
100621@24378
Contents
Preface ...................................................................................................................................................23
Part I
Introduction to Message Queue Administration ........................................................................... 33
Administrative Tasks and Tools ......................................................................................................... 35 Administrative Tasks .......................................................................................................................... 35 Administration in a Development Environment ..................................................................... 35 Administration in a Production Environment ......................................................................... 36 Administration Tools .......................................................................................................................... 38 Built-in Administration Tools .................................................................................................... 38 JMX-Based Administration ........................................................................................................ 40
Quick-Start Tutorial .............................................................................................................................41 Starting the Administration Console ................................................................................................ 42 Administration Console Online Help ............................................................................................... 44 Working With Brokers ....................................................................................................................... 45 Starting a Broker .......................................................................................................................... 45 Adding a Broker to the Administration Console ..................................................................... 45 Connecting to a Broker ............................................................................................................... 47 Viewing Connection Services ..................................................................................................... 48 Working With Physical Destinations ............................................................................................... 50 Creating a Physical Destination ................................................................................................. 50 Viewing Physical Destination Properties .................................................................................. 51 Purging Messages From a Physical Destination ....................................................................... 54 Deleting a Physical Destination ................................................................................................. 54 Working With Object Stores .............................................................................................................. 55 Adding an Object Store ............................................................................................................... 55
3
Contents
Connecting to an Object Store ................................................................................................... 58 Working With Administered Objects ............................................................................................... 58 Adding a Connection Factory .................................................................................................... 58 Adding a Destination ................................................................................................................... 60 Viewing Administered Object Properties ................................................................................. 62 Deleting an Administered Object .............................................................................................. 63 Running the Sample Application ...................................................................................................... 63 To Run the Sample Application ................................................................................................. 64
Part II
Administrative Tasks ........................................................................................................................... 67
Starting Brokers and Clients .............................................................................................................. 69 Preparing System Resources .............................................................................................................. 69 Synchronizing System Clocks .................................................................................................... 69 Setting the File Descriptor Limit ................................................................................................ 70 Starting Brokers ................................................................................................................................... 70 Starting Brokers Interactively ..................................................................................................... 70 Starting Brokers Automatically .................................................................................................. 71 Deleting a Broker Instance ................................................................................................................. 76 Starting Clients .................................................................................................................................... 77
Configuring a Broker ...........................................................................................................................79 Broker Services .................................................................................................................................... 79 Setting Broker Configuration Properties .......................................................................................... 80 Modifying Configuration Files ................................................................................................... 80 Setting Configuration Properties from the Command Line ................................................... 82
Managing a Broker ..............................................................................................................................85 Command Utility Preliminaries ........................................................................................................ 86 Using the Command Utility ............................................................................................................... 86 Specifying the User Name and Password .................................................................................. 86 Specifying the Broker Name and Port ....................................................................................... 87 Displaying the Product Version ................................................................................................. 87 Displaying Help ............................................................................................................................ 88
Sun GlassFish Message Queue 4.4 Administration Guide June 2010
Contents
Examples ....................................................................................................................................... 88 Managing Brokers ............................................................................................................................... 89 Shutting Down and Restarting a Broker ................................................................................... 89 Quiescing a Broker ....................................................................................................................... 90 Pausing and Resuming a Broker ................................................................................................. 91 Updating Broker Properties ........................................................................................................ 91 Viewing Broker Information ...................................................................................................... 92
Configuring and Managing Connection Services .......................................................................... 95 Configuring Connection Services ..................................................................................................... 95 Port Mapper .................................................................................................................................. 97 Thread Pool Management ........................................................................................................... 98 Managing Connection Services ......................................................................................................... 99 Pausing and Resuming a Connection Service .......................................................................... 99 Updating Connection Service Properties ............................................................................... 100 Viewing Connection Service Information .............................................................................. 101 Managing Connections .................................................................................................................... 103
Managing Message Delivery ...........................................................................................................107 Configuring and Managing Physical Destinations ....................................................................... 107 Command Utility Subcommands for Physical Destination Management ......................... 108 Creating and Destroying Physical Destinations .................................................................... 109 Pausing and Resuming a Physical Destination ....................................................................... 112 Purging a Physical Destination ................................................................................................ 113 Updating Physical Destination Properties .............................................................................. 114 Viewing Physical Destination Information ............................................................................ 114 Managing Physical Destination Disk Utilization ................................................................... 118 Using the Dead Message Queue ............................................................................................... 120 Managing Broker System-Wide Memory ...................................................................................... 121 Managing Durable Subscriptions .................................................................................................... 123 Managing Transactions .................................................................................................................... 124
Configuring Persistence Services ...................................................................................................127 Introduction to Persistence Services ............................................................................................... 127

5
Contents
File-Based Persistence ....................................................................................................................... 128 File-Based Persistence Properties ............................................................................................ 128 Configuring a File-Based Data Store ....................................................................................... 129 Securing a File-Based Data Store .............................................................................................. 130 Optimizing File-Based Transaction Persistence .................................................................... 130 JDBC-Based Persistence ................................................................................................................... 131 JDBC-Based Persistence Properties ......................................................................................... 131 Configuring a JDBC-Based Data Store .................................................................................... 133 Securing a JDBC-Based Data Store .......................................................................................... 135 Data Store Formats ............................................................................................................................ 135
Configuring and Managing Security Services .............................................................................. 137 Introduction to Security Services .................................................................................................... 137 Authentication ........................................................................................................................... 139 Authorization ............................................................................................................................. 140 Encryption .................................................................................................................................. 140 User Authentication .......................................................................................................................... 141 Using a Flat-File User Repository ............................................................................................ 141 Using an LDAP User Repository .............................................................................................. 147 Using JAAS-Based Authentication .......................................................................................... 150 User Authorization ............................................................................................................................ 155 Access Control File Syntax ........................................................................................................ 156 Application of Authorization Rules ......................................................................................... 158 Authorization Rules for Connection Services ........................................................................ 159 Authorization Rules for Physical Destinations ...................................................................... 160 Message Encryption .......................................................................................................................... 161 Using Self-Signed Certificates .................................................................................................. 161 Using Signed Certificates .......................................................................................................... 167 Password Files .................................................................................................................................... 170 Security Concerns ...................................................................................................................... 170 Password File Contents ............................................................................................................. 171 Connecting Through a Firewall ....................................................................................................... 171 To Enable Broker Connections Through a Firewall .............................................................. 172 Audit Logging with the Solaris BSM Audit Log ............................................................................. 172
Contents
10
Configuring and Managing Broker Clusters ................................................................................. 175 Configuring Broker Clusters ............................................................................................................ 175 The Cluster Configuration File ................................................................................................ 176 Cluster Configuration Properties ............................................................................................ 176 Displaying a Cluster Configuration ......................................................................................... 180 Managing Broker Clusters ................................................................................................................ 182 Managing Conventional Clusters ............................................................................................ 182 Managing Enhanced Clusters ................................................................................................... 187 Converting a Conventional Cluster to an Enhanced Cluster ............................................... 191
11
Managing Administered Objects ....................................................................................................195 Object Stores ...................................................................................................................................... 195 LDAP Server Object Stores ....................................................................................................... 195 File-System Object Stores ......................................................................................................... 197 Administered Object Attributes ...................................................................................................... 198 Connection Factory Attributes ................................................................................................. 198 Destination Attributes ............................................................................................................... 205 Using the Object Manager Utility .................................................................................................... 205 Adding Administered Objects .................................................................................................. 206 Deleting Administered Objects ................................................................................................ 208 Listing Administered Objects ................................................................................................... 209 Viewing Administered Object Information ........................................................................... 210 Modifying Administered Object Attributes ............................................................................ 210 Using Command Files ............................................................................................................... 211
12
Configuring and Managing Bridge Services ................................................................................. 215 The Bridge Service Manager ............................................................................................................ 215 Bridge-Related Broker Properties ............................................................................................ 216 Bridge Manager Utility .............................................................................................................. 216 Logging of Bridge Services ........................................................................................................ 217 Configuring and Managing JMS Bridge Services .......................................................................... 217 JMS Bridge Components .......................................................................................................... 218 JMS Bridge Features ................................................................................................................... 219 Message Processing Sequence Across a Link in a JMS Bridge .............................................. 224 Configuring a JMS Bridge ......................................................................................................... 225
7
Contents
Starting and Stopping JMS Bridges .......................................................................................... 233 Starting and Stopping Links in a JMS Bridge .......................................................................... 234 Configuring and Managing STOMP Bridge Services ................................................................... 235 Configuring the STOMP Bridge .............................................................................................. 236 Starting and Stopping the STOMP Bridge .............................................................................. 237 Message Processing Sequence Across the STOMP Bridge .................................................... 237 STOMP Protocol Features and the STOMP Bridge ............................................................... 239
13
Monitoring Broker Operations ........................................................................................................245 Monitoring Services .......................................................................................................................... 245 Introduction to Monitoring Tools .................................................................................................. 246 Configuring and Using Broker Logging ......................................................................................... 248 Logger Properties ....................................................................................................................... 249 Log Message Format .................................................................................................................. 249 Default Logging Configuration ................................................................................................ 250 Changing the Logging Configuration ..................................................................................... 251 Using the Command Utility to Display Metrics Interactively ..................................................... 254 imqcmd metrics ......................................................................................................................... 255 Metrics Outputs: imqcmd metrics ........................................................................................... 256 imqcmd query ............................................................................................................................ 258 Using the JMX Administration API ................................................................................................ 259 Using the Java ES Monitoring Console ........................................................................................... 259 Using the Message-Based Monitoring API .................................................................................... 260 Setting Up Message-Based Monitoring ................................................................................... 261 Security and Access Considerations ........................................................................................ 262 Metrics Outputs: Metrics Messages ......................................................................................... 263
14
Analyzing and Tuning a Message Service ..................................................................................... 265 About Performance ........................................................................................................................... 265 The Performance Tuning Process ............................................................................................ 265 Aspects of Performance ............................................................................................................. 266 Benchmarks ................................................................................................................................ 266 Baseline Use Patterns ................................................................................................................. 267 Factors Affecting Performance ........................................................................................................ 268 Message Delivery Steps .............................................................................................................. 269
Contents
Application Design Factors Affecting Performance .............................................................. 270 Message Service Factors Affecting Performance .................................................................... 274 Adjusting Configuration To Improve Performance ..................................................................... 278 System Adjustments .................................................................................................................. 278 Broker Memory Management Adjustments ........................................................................... 281 Client Runtime Message Flow Adjustments ........................................................................... 282 Adjusting Multiple-Consumer Queue Delivery ..................................................................... 284
15
Troubleshooting ............................................................................................................................... 287 A Client Cannot Establish a Connection ........................................................................................ 287 Connection Throughput Is Too Slow ............................................................................................. 292 A Client Cannot Create a Message Producer ................................................................................. 293 Message Production Is Delayed or Slowed ..................................................................................... 294 Messages Are Backlogged ................................................................................................................. 297 Broker Throughput Is Sporadic ....................................................................................................... 300 Messages Are Not Reaching Consumers ........................................................................................ 302 Dead Message Queue Contains Messages ...................................................................................... 303 To Inspect the Dead Message Queue ....................................................................................... 308
Part III
Reference ............................................................................................................................................311
16
Command Line Reference ................................................................................................................313 Command Line Syntax ..................................................................................................................... 313 Broker Utility ..................................................................................................................................... 314 Command Utility .............................................................................................................................. 318 General Command Utility Options ......................................................................................... 320 Broker Management .................................................................................................................. 321 Connection Service Management ............................................................................................ 323 Connection Management ......................................................................................................... 324 Physical Destination Management .......................................................................................... 324 Durable Subscription Management ......................................................................................... 326 Transaction Management ......................................................................................................... 327 JMX Management ...................................................................................................................... 327 Object Manager Utility ..................................................................................................................... 327
9
Contents
Database Manager Utility ................................................................................................................. 329 User Manager Utility ......................................................................................................................... 331 Bridge Manager Utility ..................................................................................................................... 332 Service Administrator Utility ........................................................................................................... 334 Key Tool Utility ................................................................................................................................. 336
17
Broker Properties Reference ...........................................................................................................337 Connection Properties ...................................................................................................................... 337 Routing and Delivery Properties ..................................................................................................... 340 Persistence Properties ....................................................................................................................... 346 File-Based Persistence Properties ............................................................................................ 346 File-Based Persistence Properties for Transaction Logging ................................................. 347 JDBC-Based Persistence Properties ......................................................................................... 349 Security Properties ............................................................................................................................ 351 Monitoring Properties ...................................................................................................................... 357 Cluster Configuration Properties .................................................................................................... 361 Bridge Properties ............................................................................................................................... 363 JMX Properties .................................................................................................................................. 366 Alphabetical List of Broker Properties ............................................................................................ 368
18
Physical Destination Property Reference ......................................................................................375 Physical Destination Properties ....................................................................................................... 375
19
Administered Object Attribute Reference ....................................................................................381 Connection Factory Attributes ........................................................................................................ 381 Connection Handling ................................................................................................................ 381 Client Identification ................................................................................................................... 385 Reliability and Flow Control ..................................................................................................... 385 Queue Browser and Server Sessions ........................................................................................ 387 Standard Message Properties .................................................................................................... 388 Message Header Overrides ....................................................................................................... 388 Destination Attributes ...................................................................................................................... 389
10
Contents
20
JMS Resource Adapter Property Reference .................................................................................. 391 About Shared Topic Subscriptions for Clustered Containers ...................................................... 392 ResourceAdapter JavaBean .............................................................................................................. 392 ManagedConnectionFactory JavaBean .......................................................................................... 394 ActivationSpec JavaBean .................................................................................................................. 397
21
Metrics Information Reference .......................................................................................................403 JVM Metrics ....................................................................................................................................... 404 Brokerwide Metrics ........................................................................................................................... 404 Connection Service Metrics ............................................................................................................. 406 Physical Destination Metrics ........................................................................................................... 407
22
JES Monitoring Framework Reference ...........................................................................................413 Common Attributes .......................................................................................................................... 413 Message Queue Product Information ............................................................................................. 414 Broker Information ........................................................................................................................... 414 Port Mapper Information ................................................................................................................. 415 Connection Service Information ..................................................................................................... 415 Destination Information .................................................................................................................. 416 Persistent Store Information ............................................................................................................ 417 User Repository Information ........................................................................................................... 418
Part IV
Appendixes .........................................................................................................................................419
Distribution-Specific Locations of Message Queue Data ........................................................... 421 Installations from an IPS image ....................................................................................................... 421 Installations from Solaris SVR4 Packages ...................................................................................... 423 Installations from Linux RPMs ........................................................................................................ 424
Stability of Message Queue Interfaces .......................................................................................... 427 Classification Scheme ....................................................................................................................... 427 Interface Stability ............................................................................................................................... 428
11
Contents
HTTP/HTTPS Support ........................................................................................................................431 HTTP/HTTPS Support Architecture ............................................................................................. 431 Enabling HTTP/HTTPS Support .................................................................................................... 432 Step 1 (HTTPS Only): Generating a Self-Signed Certificate for the Tunnel Servlet .......... 433 Step 2 (HTTPS Only): Specifying the Key Store Location and Password ............................ 435 Step 3 (HTTPS Only): Validating and Installing the Servers Self-Signed Certificate ........ 436 Step 4 (HTTP and HTTPS): Deploying the Tunnel Servlet .................................................. 440 Step 5 (HTTP and HTTPS): Configuring the Connection Service ...................................... 442 Step 6 (HTTP and HTTPS): Configuring a Connection ....................................................... 443 Troubleshooting ................................................................................................................................ 446 Server or Broker Failure ............................................................................................................ 446 Client Failure to Connect Through the Tunnel Servlet ......................................................... 446
JMX Support .......................................................................................................................................447 JMX Connection Infrastructure ...................................................................................................... 447 MBean Access Mechanism ....................................................................................................... 447 The JMX Service URL ................................................................................................................ 448 The Admin Connection Factory .............................................................................................. 449 JMX Configuration ........................................................................................................................... 450 RMI Registry Configuration ..................................................................................................... 450 SSL-Based JMX Connections ................................................................................................... 454 JMX Connections Through a Firewall .................................................................................... 455
Frequently Used Command Utility Commands ............................................................................ 457 Syntax .................................................................................................................................................. 457 Broker and Cluster Management .................................................................................................... 457 Broker Configuration Properties (-o option) ......................................................................... 458 Service and Connection Management ............................................................................................ 458 Durable Subscriber Management .................................................................................................... 459 Transaction Management ................................................................................................................ 459 Destination Management ................................................................................................................. 459 Destination Configuration Properties (-o option) ................................................................ 459 Metrics ................................................................................................................................................ 460
12
Contents
Index ................................................................................................................................................... 461
13
14
Figures
FIGURE 11 FIGURE 21 FIGURE 22 FIGURE 23 FIGURE 24 FIGURE 25 FIGURE 26 FIGURE 27 FIGURE 28 FIGURE 29 FIGURE 210 FIGURE 211 FIGURE 212 FIGURE 213 FIGURE 214 FIGURE 215 FIGURE 41 FIGURE 61 FIGURE 81 FIGURE 91 FIGURE 92 FIGURE 93 FIGURE 94 FIGURE 131 FIGURE 141 FIGURE 142 FIGURE C1 FIGURE D1
Local and Remote Administration Utilities ........................................................... 39 Administration Console Window ........................................................................... 43 Administration Console Help Window ................................................................. 44 Add Broker Dialog Box ............................................................................................. 46 Broker Displayed in Administration Console Window ....................................... 47 Connect to Broker Dialog Box ................................................................................. 48 Viewing Connection Services .................................................................................. 49 Service Properties Dialog Box .................................................................................. 49 Add Broker Destination Dialog Box ....................................................................... 51 Broker Destination Properties Dialog Box ............................................................. 53 Durable Subscriptions Panel .................................................................................... 54 Add Object Store Dialog Box ................................................................................... 56 Object Store Displayed in Administration Console Window .............................. 57 Add Connection Factory Object Dialog Box ......................................................... 59 Add Destination Object Dialog Box ........................................................................ 61 Destination Object Displayed in Administration Console Window .................. 62 Broker Configuration Files ....................................................................................... 81 Message Queue Connection Services ...................................................................... 96 Persistent Data Stores .............................................................................................. 128 Security Support ...................................................................................................... 138 JAAS Elements ......................................................................................................... 151 How Message Queue Uses JAAS ............................................................................ 152 Setting Up JAAS Support ........................................................................................ 153 Monitoring Services Support ................................................................................. 246 Message Delivery Through a Message Queue Service ......................................... 269 Transport Protocol Speeds ..................................................................................... 276 HTTP/HTTPS Support Architecture ................................................................... 432 Basic JMX Infrastructure ........................................................................................ 448
15
Figures
FIGURE D2 FIGURE D3
Obtaining a Connector Stub from an RMI Registry ........................................... 449 Obtaining a Connector Stub from an Admin Connection Factory ................... 450
16
Tables
TABLE 61 TABLE 62 TABLE 71 TABLE 72 TABLE 91 TABLE 92 TABLE 93 TABLE 94 TABLE 95 TABLE 96 TABLE 97 TABLE 98 TABLE 101 TABLE 111 TABLE 112 TABLE 121 TABLE 122 TABLE 123 TABLE 124 TABLE 125 TABLE 126 TABLE 127 TABLE 128 TABLE 129 TABLE 1210 TABLE 1211 TABLE 131 TABLE 132
Message Queue Connection Service Characteristics ............................................ 96 Connection Service Properties Updated by Command Utility ......................... 100 Physical Destination Subcommands for the Command Utility ........................ 108 Dead Message Queue Treatment of Physical Destination Properties ............... 120 Initial Entries in Flat-File User Repository ........................................................... 143 User Manager Subcommands ................................................................................ 143 General User Manager Options ............................................................................. 144 Broker Properties for JAAS Support ..................................................................... 155 Authorization Rule Elements ................................................................................. 156 Commands That Use Passwords ........................................................................... 170 Passwords in a Password File ................................................................................. 171 Broker Configuration Properties for Static Port Addresses ............................... 171 Broker States ............................................................................................................ 180 LDAP Object Store Attributes ................................................................................ 196 File-system Object Store Attributes ....................................................................... 197 DMQ Message Propeties ........................................................................................ 223 Broker Properties for a JMS Bridge ....................................................................... 225 jmsbridge Attributes ............................................................................................... 227 link Attributes .......................................................................................................... 228 source Attributes ..................................................................................................... 228 target Attributes ....................................................................................................... 229 dmq Attributes ......................................................................................................... 230 connection-factory Attributes ............................................................................... 231 destination Attributes ............................................................................................. 233 Broker Properties for the STOMP Bridge Service ............................................... 236 STOMP Bridge Handling of Selected Command/Header Combinations ........ 239 Benefits and Limitations of Metrics Monitoring Tools ...................................... 247 Logging Levels ......................................................................................................... 250
17
Tables
TABLE 133 TABLE 134 TABLE 135 TABLE 136 TABLE 141 TABLE 161 TABLE 162 TABLE 163 TABLE 164 TABLE 165 TABLE 166 TABLE 167 TABLE 168 TABLE 169 TABLE 1610 TABLE 1611 TABLE 1612 TABLE 1613 TABLE 1614 TABLE 1615 TABLE 1616 TABLE 1617 TABLE 1618 TABLE 1619 TABLE 1620 TABLE 1621 TABLE 171 TABLE 172 TABLE 173 TABLE 174 TABLE 175 TABLE 176
TABLE 177 TABLE 178 TABLE 179
imqcmd metrics Subcommand Syntax ................................................................ 255 imqcmd metrics Subcommand Options .............................................................. 255 imqcmd query Subcommand Syntax .................................................................... 258 Metrics Topic Destinations .................................................................................... 261 Comparison of High-Reliability and High-Performance Scenarios ................. 270 Broker Utility Options ............................................................................................ 314 Command Utility Subcommands ......................................................................... 318 General Command Utility Options ...................................................................... 320 Command Utility Subcommands for Broker Management .............................. 321 Command Utility Subcommands for Connection Service Management ........ 323 Command Utility Subcommands for Connection Service Management ........ 324 Command Utility Subcommands for Physical Destination Management ....... 325 Command Utility Subcommands for Durable Subscription Management ..... 326 Command Utility Subcommands for Transaction Management ..................... 327 Command Utility Subcommand for JMX Management .................................... 327 Object Manager Subcommands ............................................................................ 327 Object Manager Options ........................................................................................ 328 Database Manager Subcommands ........................................................................ 329 Database Manager Options .................................................................................... 330 User Manager Subcommands ................................................................................ 331 General User Manager Options ............................................................................. 332 Bridge Manager Subcommands for Bridge Management .................................. 332 Bridge Manager Subcommands for Link Management ...................................... 333 Bridge Manager Options ........................................................................................ 334 Service Administrator Subcommands .................................................................. 334 Service Administrator Options .............................................................................. 335 Broker Connection Properties ............................................................................... 338 Broker Routing and Delivery Properties .............................................................. 340 Broker Properties for Auto-Created Destinations .............................................. 342 Global Broker Persistence Property ...................................................................... 346 Broker Properties for File-Based Persistence ....................................................... 346 Broker Properties for File-Based Persistence Using the Transaction Logging Mechanism ............................................................................................................... 348 Broker Properties for JDBC-Based Persistence ................................................... 350 Broker Security Properties ..................................................................................... 351 Broker Security Properties for LDAP Authentication ........................................ 354
18
Tables
TABLE 1710 TABLE 1711 TABLE 1712 TABLE 1713 TABLE 1714 TABLE 1715 TABLE 1716 TABLE 1717 TABLE 181 TABLE 191 TABLE 192 TABLE 193 TABLE 194 TABLE 195 TABLE 196 TABLE 197 TABLE 198 TABLE 199 TABLE 201 TABLE 202 TABLE 203 TABLE 211 TABLE 212 TABLE 213 TABLE 214 TABLE 221 TABLE 222 TABLE 223 TABLE 224 TABLE 225 TABLE 226 TABLE 227 TABLE 228 TABLE A1 TABLE A2
Broker Security Properties for JAAS Authentication .......................................... 356 Broker Monitoring Properties ............................................................................... 357 Broker Properties for Cluster Configuration ....................................................... 361 Broker Properties for the Bridge Service Manager .............................................. 364 Broker Properties for a JMS Bridge Service .......................................................... 364 Broker Properties for the STOMP Bridge Service ............................................... 365 Broker Properties for JMX Support ....................................................................... 366 Alphabetical List of Broker Properties .................................................................. 368 Physical Destination Properties ............................................................................. 375 Connection Factory Attributes for Connection Handling ................................. 382 Message Broker Addressing Schemes ................................................................... 384 Message Broker Address Examples ....................................................................... 385 Connection Factory Attributes for Client Identification .................................... 385 Connection Factory Attributes for Reliability and Flow Control ...................... 386 Connection Factory Attributes for Queue Browser and Server Sessions .......... 387 Connection Factory Attributes for Standard Message Properties ..................... 388 Connection Factory Attributes for Message Header Overrides ......................... 389 Destination Attributes ............................................................................................ 389 Resource Adapter Properties ................................................................................. 392 Managed Connection Factory Properties ............................................................. 395 ActivationSpec Properties ...................................................................................... 397 JVM Metrics ............................................................................................................. 404 Brokerwide Metrics ................................................................................................. 404 Connection Service Metrics ................................................................................... 406 Physical Destination Metrics ................................................................................. 407 JESMF Common Object Attributes ...................................................................... 413 JESMF-Accessible Message Queue Product Attributes ...................................... 414 JESMF-Accessible Message Queue Broker Attributes ........................................ 414 JESMF-Accessible Message Queue Port Mapper Attributes .............................. 415 JESMF-Accessible Message Queue Connection Service Attributes .................. 415 JESMF-Accessible Message Queue Destination Attributes ................................ 416 JESMF-Accessible Message Queue Persistent Store Attributes ......................... 417 JESMF-Accessible Message Queue User Repository Attributes ........................ 418 Message Queue Data Locations for Installations from an IPS Image ................ 421 Message Queue Data Locations for Installations from Solaris SVR4 Packages .................................................................................................................................... 423
19
Tables
TABLE A3 TABLE B1 TABLE B2 TABLE C1 TABLE C2
TABLE D1 TABLE E1 TABLE E2
Message Queue Data Locations for Installations from Linux RPMs ................ 424 Interface Stability Classification Scheme .............................................................. 427 Stability of Message Queue Interfaces ................................................................... 428 Distinguished Name Information Required for a Self-Signed Certificate ........ 434 Broker Configuration Properties for the httpjms and httpsjms Connection Services ..................................................................................................................... 442 Advantages and Disadvantages of Using an RMI Registry ................................. 451 Broker Configuration Properties ( -o option) ..................................................... 458 Destination Configuration Properties (-o option) ............................................. 459
20
Examples
EXAMPLE 21 EXAMPLE 31 EXAMPLE 51 EXAMPLE 52 EXAMPLE 61 EXAMPLE 62 EXAMPLE 63 EXAMPLE 64 EXAMPLE 65 EXAMPLE 71 EXAMPLE 72 EXAMPLE 73 EXAMPLE 74 EXAMPLE 75 EXAMPLE 76 EXAMPLE 77 EXAMPLE 78 EXAMPLE 81 EXAMPLE 82 EXAMPLE 91 EXAMPLE 92 EXAMPLE 93 EXAMPLE 94 EXAMPLE 95 EXAMPLE 96 EXAMPLE 101 EXAMPLE 102 EXAMPLE 111
Output from Sample Application ............................................................................ 65 Displaying Broker Service Startup Options ........................................................... 75 Broker Information Listing ...................................................................................... 93 Broker Metrics Listing .............................................................................................. 94 Connection Services Listing ................................................................................... 101 Connection Service Information Listing .............................................................. 102 Connection Service Metrics Listing ...................................................................... 103 Broker Connections Listing ................................................................................... 104 Connection Information Listing ........................................................................... 104 Wildcard Publisher ................................................................................................. 111 Wildcard Subscriber ............................................................................................... 111 Physical Destination Information Listing ............................................................ 116 Physical Destination Metrics Listing .................................................................... 118 Destination Disk Utilization Listing ..................................................................... 119 Durable Subscription Information Listing ........................................................... 124 Broker Transactions Listing ................................................................................... 125 Transaction Information Listing ........................................................................... 125 Broker Properties for MySQL Database ............................................................... 132 Broker Properties for HADB Database ................................................................. 132 Viewing Information for a Single User ................................................................. 147 Viewing Information for All Users ....................................................................... 147 Example 1 ................................................................................................................. 157 Example 2 ................................................................................................................. 157 Example 3 ................................................................................................................. 157 Connection Services Listing ................................................................................... 167 Configuration Listing for a Conventional Cluster .............................................. 181 Configuration Listing for an Enhanced Cluster .................................................. 181 Adding a Connection Factory ................................................................................ 207
21
Examples
EXAMPLE 112 EXAMPLE 113 EXAMPLE 114 EXAMPLE 115 EXAMPLE 116 EXAMPLE 117 EXAMPLE 118 EXAMPLE 119 EXAMPLE 1110 EXAMPLE 1111 EXAMPLE 1112 EXAMPLE C1 EXAMPLE D1 EXAMPLE D2 EXAMPLE D3 EXAMPLE D4
Adding a Destination to an LDAP Object Store .................................................. 208 Adding a Destination to a File-System Object Store ........................................... 208 Deleting an Administered Object .......................................................................... 208 Listing All Administered Objects .......................................................................... 209 Listing Administered Objects of a Specific Type ................................................. 210 Viewing Administered Object Information ......................................................... 210 Modifying an Administered Objects Attributes .................................................. 211 Object Manager Command File Syntax ................................................................ 212 Example Command File ......................................................................................... 213 Partial Command File ............................................................................................. 213 Using a Partial Command File ............................................................................... 213 Tunnel Servlet Status Report .................................................................................. 445 JMX Service URL When Using an RMI Registry ................................................. 452 JMX Service URL When Not Using an RMI Registry ......................................... 453 JMX Configuration for Firewall When Not Using a RMI Registry ................... 455 JMX Configuration for Firewall When Using an RMI Registry ........................ 455
22
Preface
This Sun GlassFish Message Queue 4.4 Administration Guide provides background and information needed by system administrators to set up and manage a Sun GlassFish Message Queue messaging system. This preface consists of the following sections:

Who Should Use This Book on page 23 Before You Read This Book on page 23 How This Book Is Organized on page 24 Documentation Conventions on page 26 Related Documentation on page 28 Third-Party Web Site References on page 31 Searching Sun Product Documentation on page 32 Documentation, Support, and Training on page 32 Sun Welcomes Your Comments on page 32
Who Should Use This Book

This guide is intended for administrators and application developers who need to perform Message Queue administrative tasks. A Message Queue administrator is responsible for setting up and managing a Message Queue messaging system, especially the message broker at the heart of the system.
Before You Read This Book

Before reading this guide, you should read the Sun GlassFish Message Queue 4.4 Technical Overview to become familiar with the Message Queue implementation of the Java Message Service specification, with the components of the Message Queue service, and with the basic process of developing, deploying, and administering a Message Queue application.
23
Preface
How This Book Is Organized

Table P1 describes the contents of this manual.
TABLE P1
Book Contents
Description
Chapter/Appendix
Part I, Introduction to Message Queue Administration Chapter 1, Administrative Tasks and Tools Chapter 2, Quick-Start Tutorial Part II, Administrative Tasks Chapter 3, Starting Brokers and Describes how to start the Message Queue broker and clients. Clients Chapter 4, Configuring a Broker Chapter 5, Managing a Broker Describes how configuration properties are set and read, and gives an introduction to the configurable aspects of the broker. Describes broker management tasks. Introduces Message Queue administrative tasks and tools. Provides a hands-on tutorial to acquaint you with the Message Queue Administration Console.
Chapter 6, Configuring and Describes configuration and management tasks relating to the broker's Managing Connection Services connection services. Chapter 7, Managing Message Delivery Chapter 8, Configuring Persistence Services Chapter 9, Configuring and Managing Security Services Chapter 10, Configuring and Managing Broker Clusters Chapter 11, Managing Administered Objects Describes how to create and manage physical destinations and manage other aspects of message delivery. Describes how to set up a file-based or JDBC-based data store to perform persistence services. Describes security-related tasks, such as managing password files, authentication, authorization, and encryption. Describes how to set up and manage a cluster of Message Queue brokers. Describes the object store and shows how to perform tasks related to administered objects (connection factories and destinations).
Chapter 13, Monitoring Broker Describes how to set up and use Message Queue monitoring facilities. Operations Chapter 14, Analyzing and Tuning a Message Service Chapter 15, Troubleshooting Describes techniques for analyzing and optimizing message service performance. Provides suggestions for determining the cause of common Message Queue problems and the actions you can take to resolve them.
24
Preface
TABLE P1
Book Contents
(Continued)
Description
Chapter/Appendix
Part III, Reference Chapter 16, Command Line Reference Chapter 17, Broker Properties Reference Chapter 18, Physical Destination Property Reference Chapter 19, Administered Object Attribute Reference Chapter 20, JMS Resource Adapter Property Reference Chapter 21, Metrics Information Reference Chapter 22, JES Monitoring Framework Reference Part IV, Appendixes Appendix A, Lists the locations of Message Queue files on each supported platform. Distribution-Specific Locations of Message Queue Data Appendix B, Stability of Message Queue Interfaces Appendix C, HTTP/HTTPS Support Appendix D, JMX Support Describes the stability of various Message Queue interfaces. Describes how to set up and use the Hypertext Transfer Protocol (HTTP) for Message Queue communication. Describes Message Queues administrative support for client programs using the Java Management Extensions (JMX) application programming interface Lists some frequently used Message Queue Command utility (imqcmd) commands. Provides syntax and descriptions for Message Queue command line utilities. Describes the configuration properties of Message Queue message brokers. Describes the configuration properties of physical destinations.
Describes the configuration properties of administered objects (connection factories and destinations). Describes the configuration properties of the Message Queue Resource Adapter for use with an application server. Describes the metric information that a Message Queue message broker can provide for monitoring, turning, and diagnostic purposes. . Lists Message Queue attributes that are accessible by means of the Java Enterprise System Monitoring Framework (JESMF).
Appendix E, Frequently Used Command Utility Commands
25
Preface
Documentation Conventions
This section describes the following conventions used in Message Queue documentation:

Typographic Conventions on page 26 Symbol Conventions on page 26 Shell Prompt Conventions on page 27 Directory Variable Conventions on page 27
Typographic Conventions
The following table describes the typographic conventions that are used in this book.
TABLE P2 Typeface
Typographic Conventions
Meaning Example
AaBbCc123
The names of commands, files, and directories, and onscreen computer output
Edit your .login file. Use ls -a to list all files. machine_name% you have mail.
AaBbCc123
What you type, contrasted with onscreen computer output Placeholder: replace with a real name or value Book titles, new terms, and terms to be emphasized
machine_name% su Password: The command to remove a file is rm filename. Read Chapter 6 in the User's Guide. A cache is a copy that is stored locally. Do not save the file. Note: Some emphasized items appear bold online.
aabbcc123 AaBbCc123
Symbol Conventions
The following table explains symbols that might be used in this book.
TABLE P3 Symbol
Symbol Conventions
Description Example Meaning
[]
Contains optional arguments ls [-l] and command options.
The -l option is not required.
26
Preface
TABLE P3 Symbol
Symbol Conventions
Description
(Continued)
Example Meaning
{|}
Contains a set of choices for a -d {y|n} required command option. Indicates a variable reference. Joins simultaneous multiple keystrokes. Joins consecutive multiple keystrokes. Indicates menu item selection in a graphical user interface. ${com.sun.javaRoot} Control-A Ctrl+A+N File New Templates
The -d option requires that you use either the y argument or the n argument. References the value of the com.sun.javaRoot variable. Press the Control key while you press the A key. Press the Control key, release it, and then press the subsequent keys. From the File menu, choose New. From the New submenu, choose Templates.
${ } +
Shell Prompt Conventions

The following table shows the conventions used in Message Queue documentation for the default UNIX system prompt and superuser prompt for the C shell, Bourne shell, Korn shell, and for the Windows operating system.
TABLE P4 Shell
Shell Prompt Conventions

Prompt
C shell on UNIX, Linux, or AIX C shell superuser on UNIX, Linux, or AIX Bourne shell and Korn shell on UNIX, Linux, or AIX Bourne shell and Korn shell superuser on UNIX, Linux, or AIX Windows command line
machine-name% machine-name# $ # C:\>
Directory Variable Conventions

Message Queue documentation makes use of three directory variables; two of which represent environment variables needed by Message Queue. (How you set the environment variables varies from platform to platform.) The following table describes the directory variables that might be found in this book and how they are used. When installed from the IPS (pkg(5)) image distribution, Message Queue is
27
Preface
installed in a directory referred to as mqInstallHome, and some of the directory variables in Table P5 reference this mqInstallHome directory.
Note In this book, directory variables are shown without platform-specific environment variable notation or syntax (such as $IMQ_HOME on UNIX). Non-platform-specific path names use UNIX directory separator (/) notation.
TABLE P5 Variable
Directory Variable Conventions

Description
IMQ_HOME
Message Queue home directory, if any: For installations from the IPS image distribution on any platform, IMQ_HOME denotes the directory mqInstallHome/mq, where mqInstallHome is specified when you install Message Queue. For installations from Solaris SVR4 packages, IMQ_HOME is unused. For installations from Linux RPM packages, IMQ_HOME is unused.
IMQ_VARHOME
Directory in which Message Queue temporary or dynamically created configuration and data files are stored; IMQ_VARHOME can be explicitly set as an environment variable to point to any directory or will default as described below: For installations from the IPS image distribution on any platform, IMQ_VARHOME defaults to mqInstallHome/var/mq.

For installations from Solaris SVR4 packages, IMQ_VARHOME defaults to /var/imq. For installations from Linux RPM packages, IMQ_VARHOME defaults to /var/opt/sun/mq.
IMQ_JAVAHOME
An environment variable that points to the location of the Java runtime environment (JRE) required by Message Queue executable files: On Solaris, Linux and Windows, Message Queue looks for the latest JDK, but you can optionally set the value of IMQ_JAVAHOME to wherever the preferred JRE resides.
On AIX, IMQ_JAVAHOME is set to point to an existing Java runtime when you perform Message Queue installation.
Related Documentation
The information resources listed in this section provide further information about Message Queue in addition to that contained in this manual. The section covers the following resources:

Message Queue Documentation Set on page 29 Java Message Service (JMS) Specification on page 29 JavaDoc on page 30 Example Client Applications on page 30 Online Help on page 31
28
Preface
Message Queue Documentation Set

The documents that comprise the Message Queue documentation set are listed in the following table in the order in which you might normally use them. These documents are available through the Sun documentation Web site at http://www.sun.com/documentation/ Click Software, followed by Application & Integration Services, and then Message Queue. For a content reference to topics with the Message Queue documentation set, see the Message Queue Documentation Center at the above location.
TABLE P6 Document
Message Queue Documentation Set

Audience Description
Sun GlassFish Message Queue 4.4 Technical Overview Sun GlassFish Message Queue 4.4 Release Notes Sun GlassFish Message Queue 4.4 Administration Guide Sun GlassFish Message Queue 4.4 Developers Guide for Java Clients
Developers and administrators Developers and administrators Administrators, also recommended for developers Developers
Describes Message Queue concepts, features, and components. Includes descriptions of new features, limitations, and known bugs, as well as technical notes. Provides background and information needed to perform administration tasks using Message Queue administration tools. Provides a quick-start tutorial and programming information for developers of Java client programs using the Message Queue implementation of the JMS or SOAP/JAXM APIs. Provides programming and reference documentation for developers of C client programs using the Message Queue C implementation of the JMS API (C-API). Provides programming and reference documentation for developers of JMX client programs using the Message Queue JMX API.
Sun GlassFish Message Queue 4.4 Developers Guide for C Clients
Developers
Sun GlassFish Message Queue 4.4 Developers Guide for JMX Clients
Administrators
Java Message Service (JMS) Specification

The Message Queue message service conforms to the Java Message Service (JMS) application programming interface, described in the Java Message Service Specification. This document can be found at the URL http://java.sun.com/products/jms/docs.html
29
Preface
JavaDoc
JMS and Message Queue API documentation in JavaDoc format is included in your Message Queue installation at the locations shown in Table P7, depending on your installation method. This documentation can be viewed in any HTML browser. It includes standard JMS API documentation as well as Message Queuespecific APIs.
TABLE P7
JavaDoc Locations
Location
Installation Method
IPS image Solaris SVR4 packages Linux RPM packages

1
IMQ_HOME/javadoc/index.html1 /usr/share/javadoc/imq/index.html /opt/sun/mq/javadoc/index.html
IMQ_HOME is the Message Queue home directory.
Example Client Applications

Message Queue provides a number of example client applications to assist developers.
Example Java Client Applications

Example Java client applications are located in the following directories, depending on installation method. See the README files located in these directories and their subdirectories for descriptive information about the example applications.
Installation Method Location

1
IMQ_HOME/examples1 /usr/demo/imq /opt/sun/mq/examples
Example C Client Programs

Example C client applications are located in the following directories, depending on installation method. See the README files located in these directories and their subdirectories for descriptive information about the example applications.
IPS image
IMQ_HOME/examples/C1
30
Preface
Installation Method
Location
Solaris SVR4 packages Linux RPM packages
/opt/SUNWimq/demo/C /opt/sun/mq/examples/C
Example JMX Client Programs

Example Java Management Extensions (JMX) client applications are located in the following directories, depending on installation method. See the README files located in these directories and their subdirectories for descriptive information about the example applications.

1
IMQ_HOME/examples/jmx1 /opt/SUNWimq/demo/imq/jmx /opt/sun/mq/examples/jmx
Online Help
Online help is available for the Message Queue command line utilities; for details, see Chapter 16, Command Line Reference, for details. The Message Queue graphical user interface (GUI) administration tool, the Administration Console, also includes a context-sensitive help facility; see the section Administration Console Online Help in Chapter 2, Quick-Start Tutorial.
Third-Party Web Site References

Where relevant, this manual refers to third-party URLs that provide additional, related information.
Note Sun is not responsible for the availability of third-party Web sites mentioned in this
manual. Sun does not endorse and is not responsible or liable for any content, advertising, products, or other materials available on or through such sites or resources. Sun will not be responsible or liable for any actual or alleged damage or loss caused or alleged to be caused by or in connection with the use of or reliance on any such content, goods, or services available on or through such sites or resources.
31
Preface
Searching Sun Product Documentation

Besides searching Sun product documentation from the docs.sun.com web site, you can use a search engine by typing the following syntax in the search field:
search-term site:docs.sun.com
For example, to search for broker, type the following:

broker site:docs.sun.com
To include other Sun web sites in your search (for example, java.sun.com, www.sun.com, and developers.sun.com), use sun.com in place of docs.sun.com in the search field.
Documentation, Support, and Training

The Sun web site provides information about the following additional resources:

Documentation (http://www.sun.com/documentation/) Support (http://www.sun.com/support/) Training (http://www.sun.com/training/)
Sun Welcomes Your Comments

Sun is interested in improving its documentation and welcomes your comments and suggestions. To share your comments, go to http://docs.sun.com and click Feedback.
32
P A R T
Introduction to Message Queue Administration

Chapter 1, Administrative Tasks and Tools Chapter 2, Quick-Start Tutorial
33
34
C H A P T E R
Administrative Tasks and Tools
This chapter provides an overview of Sun GlassFish Message Queue administrative tasks and the tools for performing them, focusing on common features of the command line administration utilities. It consists of the following sections: Administrative Tasks on page 35 Administration Tools on page 38
Administrative Tasks
The typical administrative tasks to be performed depend on the nature of the environment in which you are running Message Queue. The demands of a software development environment in which Message Queue applications are being developed and tested are different from those of a production environment in which such applications are deployed to accomplish useful work. The following sections summarize the typical administrative requirements of these two different types of environment.
Administration in a Development Environment

In a development environment, the emphasis is on flexibility. The Message Queue message service is needed principally for testing applications under development. Administration is generally minimal, with programmers often administering their own systems. Such environments are typically distinguished by the following characteristics:

Simple startup of brokers for use in testing Administered objects instantiated in client code rather than created administratively Auto-created destinations File-system object store File-based persistence
35
File-based user repository No master broker in multiple-broker clusters
Administration in a Production Environment

In a production environment in which applications must be reliably deployed and run, administration is more important. Administrative tasks to be performed depend on the complexity of the messaging system and of the applications it must support. Such tasks can be classified into two general categories: setup operations and maintenance operations.
Setup Operations
Administrative setup operations in a production environment typically include some or all of the following: Administrator security
Setting the password for the default administrative user (admin) (Changing a Users Password on page 145) Controlling individual or group access to the administrative connection service (Authorization Rules for Connection Services on page 159) and the dead message queue (Authorization Rules for Physical Destinations on page 160) Regulating administrative group access to a file-based or Lightweight Directory Access Protocol (LDAP) user repository (User Groups and Status on page 141, Using an LDAP User Repository on page 147)
General security
Managing the contents of a file-based user repository (Using the User Manager Utility on page 143) or configuring the broker to use an existing LDAP user repository (Using an LDAP User Repository on page 147) Controlling the operations that individual users or groups are authorized to perform (User Authorization on page 155) Setting up encryption services using the Secure Socket Layer (SSL) (Message Encryption on page 161)
Administered objects
Setting up and configuring an LDAP object store ( LDAP Server Object Stores on page 195) Creating connection factories and destinations ( Adding Administered Objects on page 206)
Broker clusters
36 Sun GlassFish Message Queue 4.4 Administration Guide June 2010
Creating a cluster configuration file (The Cluster Configuration File on page 176) Designating a master broker (Managing a Conventional Cluster's Configuration Change Record on page 186)
Persistence
Configuring a broker to use a persistent store (Chapter 8, Configuring Persistence Services).
Memory management
Setting a destinations configuration properties to optimize its memory usage (Updating Physical Destination Properties on page 114, Chapter 18, Physical Destination Property Reference)
Maintenance Operations
Because application performance, reliability, and security are at a premium in production environments, message service resources must be tightly monitored and controlled through ongoing administrative maintenance operations, including the following: Broker administration and tuning
Using broker metrics to tune and reconfigure a broker ( Chapter 14, Analyzing and Tuning a Message Service) Managing broker memory resources (Managing Broker System-Wide Memory on page 121) Creating and managing broker clusters to balance message load (Chapter 10, Configuring and Managing Broker Clusters) Recovering failed brokers (Starting Brokers on page 70).
Administered objects
Adjusting connection factory attributes to ensure the correct behavior of client applications (Connection Factory Attributes on page 198) Monitoring and managing physical destinations ( Configuring and Managing Physical Destinations on page 107) Controlling user access to destinations ( Authorization Rules for Physical Destinations on page 160)
Client management
Monitoring and managing durable subscriptions (see Managing Durable Subscriptions on page 123). Monitoring and managing transactions (see Managing Transactions on page 124).
37
Chapter 1 Administrative Tasks and Tools
Administration Tools
This section describes the tools you use to configure and manageMessage Queue broker services. The tools fall into two categories:

Built-in Administration Tools on page 38 JMX-Based Administration on page 40
Built-in Administration Tools

Message Queue's built-in administration tools include both command line and GUI tools:

Command Line Utilities on page 38 Administration Console on page 39
Command Line Utilities

All Message Queue utilities are accessible via a command line interface. Utility commands share common formats, syntax conventions, and options. These utilities allow you to perform various administrative tasks, as noted below, and therefore can require different administrative permissions:
The Broker utility (imqbrokerd) starts up brokers and specifies their configuration properties, including connecting them together into a cluster. Permissions: User account that initially started the broker. The Command utility (imqcmd) controls brokers and their resources and manages physical destinations. Permissions: Message Queue admin user account. The Object Manager utility (imqobjmgr) manages provider-independent administered objects in an object store accessible via the Java Naming and Directory Interface (JNDI). Permissions: Object store (flat-file or LDAP server) access account. The Database Manager utility (imqdbmgr) creates and manages databases for persistent storage that conform to the Java Database Connectivity (JDBC) standard. Permissions: JDBC database manager account. The User Manager utility (imqusermgr) populates a file-based user repository for user authentication and authorization. Permissions: user account that initially started the broker. The Service Administrator utility ( imqsvcadmin) installs and manages a broker as a Windows service. Permissions: Administrator. The Key Tool utility (imqkeytool) generates self-signed certificates for Secure Socket Layer (SSL) authentication. Permissions: root user (Solaris and Linux platforms) or Administrator (Windows platform).
The executable files for the above command line utilities are in the /bin directory shown in Appendix A, Distribution-Specific Locations of Message Queue Data.
See Chapter 16, Command Line Reference, for detailed information on the use of these utilities.
Administration Console
The Message Queue Administration Console combines some of the capabilities of the Command and Object Manager utilities. You can use it to perform the following tasks:

Connect to and control a broker remotely Create and manage physical destinations Create and manage administered objects in a JNDI object store
However, you cannot use the Administration Console to perform such tasks as starting up a broker, creating broker clusters, managing a JDBC database or a user repository, installing a broker as a Windows service, or generating SSL certificates. For these, you need the other command line utilities (Broker, Database Manager, User Manager, Service Administrator, and Key Tool), which cannot operate remotely and must be run on the same host as the broker they manage (see Figure 11).
FIGURE 11
Local and Remote Administration Utilities
Remote Admin Host Broker Host Administration Console Broker imqcmd imqbrokerd imqobjmgr imqusermgr imqdbmgr imqkeytool
imqsvcadmin (Windows only)
See Chapter 2, Quick-Start Tutorial, for a brief, hands-on introduction to the Administration Console. More detailed information on its use is available through its own help facility.
Chapter 1 Administrative Tasks and Tools
39
JMX-Based Administration
To serve customers who need a standard programmatic means to monitor and access the broker, Message Queue also supports the Java Management Extensions (JMX) architecture, which allows a Java application to manage broker resources programmatically.
Resources include everything that you can manipulate using the Command utility (imqcmd) and the Message Queue Admin Console: the broker, connection services, connections, destinations, durable subscribers, transactions, and so on. Management includes the ability to dynamically configure and monitor resources, and the ability to obtain notifications about state changes and error conditions.
JMX is the Java standard for building management applications. Message Queue is based on the JMX 1.2 specification, which is part of JDK 1.5. For information on the broker's JMX infrastructure and how to configure the broker to support JMX client applications,, see Appendix D, JMX Support. To manage a Message Queue broker using the JMX architecture, see Sun GlassFish Message Queue 4.4 Developers Guide for JMX Clients.
40
C H A P T E R
Quick-Start Tutorial
This quick-start tutorial provides a brief introduction to Message Queue administration by guiding you through some basic administrative tasks using the Message Queue Administration Console, a graphical interface for administering a message broker and object store. The chapter consists of the following sections:

Starting the Administration Console on page 42 Administration Console Online Help on page 44 Working With Brokers on page 45 Working With Physical Destinations on page 50 Working With Object Stores on page 55 Working With Administered Objects on page 58 Running the Sample Application on page 63
The tutorial sets up the physical destinations and administered objects needed to run a simple JMS-compliant application, HelloWorldMessageJNDI. The application is available in the helloworld subdirectory of the example applications directory (demo on the Solaris and Windows platforms or examples on Linux; see Appendix A, Distribution-Specific Locations of Message Queue Data). In the last part of the tutorial, you will run this application.
Note You must have the Message Queue product installed in order to follow the tutorial. If necessary, see the Message Queue Installation Guide for instructions.
The tutorial is only a basic introduction; it is not a substitute for reading the documentation. By following the steps described in the tutorial, you will learn how to

Start a Message Queue broker Connect to a broker and use the Administration Console to manage it Create physical destinations on the broker Create an object store and use the Administration Console to connect to it Add administered objects to the object store and view their properties
41
Starting the Administration Console
Note The instructions given in this tutorial are specific to the Windows platform. Where necessary, supplemental notes are added for users of other platforms.
Some administrative tasks cannot be accomplished using the Administration Console. You must use command line utilities to perform such tasks as the following:

Start up a broker Create a broker cluster Configure certain physical destination properties Manage a JDBC database for persistent storage Manage a user repository Install a broker as a Windows service Generate SSL certificates
All of these tasks are covered in later chapters of this manual.

To start the Administration Console, use one of the following methods, depending on how Message Queue was installed:
On IPS package-based installations, enter the command IMQ_HOME/bin/imqadmin
On Solaris SVR4 package-based installations, enter the command /usr/bin/imqadmin
On Linux RPM package-based installations, enter the command /opt/sun/mq/bin/imqadmin
You may need to wait a few seconds before the Administration Console window is displayed (see Figure 21).
42
FIGURE 21
Administration Console Window
Take a few seconds to examine the Administration Console window. It has a menu bar at the top, a tool bar just below it, a navigation pane to the left, a result pane to the right (now displaying graphics identifying the Sun GlassFish Message Queue product), and a status pane at the bottom.
Note As you work with the Administration Console, you can use the Refresh command on the View menu to update the visual display of any element or group of elements, such as a list of brokers or object stores.
Chapter 2 Quick-Start Tutorial
43
Administration Console Online Help
Administration Console Online Help

The Administration Console provides a help facility containing complete information about how to use the Console to perform administrative tasks. To use the help facility, pull down the Help menu at the right end of the menu bar and choose Overview. The Administration Consoles Help window (Figure 22) will be displayed.
FIGURE 22
Administration Console Help Window
The Help windows navigation pane, on the left, organizes topics into three areas: Message Queue Administration Console, Message Queue Object Store Management, and Message Queue Broker Management. Within each area are files and folders. The folders provide help for dialog boxes containing multiple tabs, the files for simple dialog boxes or individual tabs. When you select an item in the navigation pane, the result pane to the right shows the contents of that item. With the Overview item chosen, the result pane displays a skeletal view of the Administration Console window identifying each of the windows panes, as shown in the figure. Your first task with the Administration Console will be to create a reference to a broker. Before you start, however, check the Help window for information. Click the Add Broker item in the Help windows navigation pane; the contents of the result pane will change to show text explaining what it means to add a broker and describing the use of each field in the Add Broker dialog box. Read through the help text, then close the Help window.
Working With Brokers

This section describes how to use the Administration Console to connect to and manage message brokers.
Starting a Broker
You cannot start a broker using the Administration Console. Instead, use one of the following methods, depending on how Message Queue was installed:
On IPS package-based installations, enter the command IMQ_HOME/bin/imqbrokerd
On Solaris SVR4 package-based installations, enter the command /usr/bin/imqbrokerd
On Linux RPM package-based installations, enter the command /opt/sun/mq/bin/imqbrokerd
If you used the Windows Start menu, the command window will appear, indicating that the broker is ready by displaying lines like the following: Loading persistent data... Broker imqbroker@stan:7676 ready. Reactivate the Administration Console window. You are now ready to add the broker to the Console and connect to it. You do not have to start the broker before adding a reference to it in the Administration Console, but you must start it before you can connect to it.
Adding a Broker to the Administration Console

Adding a broker creates a reference to that broker in the Administration Console. After adding the broker, you can connect to it.
To Add a Broker to the Administration Console

1
Click on the Brokers item in the Administration Console windows navigation pane and choose Add Broker from the Actions menu. Alternatively, you can right-click on Brokers and choose Add Broker from the pop-up context menu. In either case, the Add Broker dialog box (Figure 23) will appear.
45
FIGURE 23
Add Broker Dialog Box
Enter a name for the broker in the Broker Label field. This provides a label that identifies the broker in the Administration Console. Note the default host name (localhost) and primary port ( 7676) specified in the dialog box. These are the values you must specify later, when you configure the connection factory that the client will use to create connections to this broker. For this exercise, type the name MyBroker into the Broker Label field. Leave the Password field blank; your password will be more secure if you specify it at connection time.
Click OK to add the broker and dismiss the dialog box. The new broker will appear under Brokers in the navigation pane, as shown in Figure 24. The red X over the brokers icon indicates that it is not currently connected to the Administration Console.
46
FIGURE 24
Broker Displayed in Administration Console Window
Once you have added a broker, you can use the Properties command on the Actions menu (or the pop-up context menu) to display a Broker Properties dialog box, similar to the Add Broker dialog shown in Adding a Broker to the Administration Console on page 45, to view or modify any of its properties.
Connecting to a Broker
Now that you have added a broker to the Administration Console, you can proceed to connect to it.
To Connect to a Broker
1
Click on the brokers name in the Administration Console windows navigation pane and choose Connect to Broker from the Actions menu. Alternatively, you can right-click on the brokers name and choose Connect to Broker from the pop-up context menu. In either case, the Connect to Broker dialog box ( Figure 25) will appear.
47
FIGURE 25
Connect to Broker Dialog Box
Enter the user name and password with which to connect to the broker. The dialog box initially displays the default user name, admin . In a real-world environment, you should establish secure user names and passwords as soon as possible (see User Authentication on page 141); for this exercise, simply use the default value. The password associated with the default user name is also admin; type it into the Password field in the dialog box. This will connect you to the broker with administrative privileges.
Click OK to connect to the broker and dismiss the dialog box. Once you have connected to the broker, you can use the commands on the Actions menu (or the context menu) to perform the following operations on a selected broker:

Pause Broker temporarily suspends the operation of a running broker. Resume Broker resumes the operation of a paused broker. Restart Broker reinitializes and restarts a broker. Shut Down Broker terminates the operation of a broker. Query/Update Broker displays or modifies a brokers configuration properties. Disconnect from Broker terminates the connection between a broker and the Administration Console.
Viewing Connection Services

A broker is distinguished by the connection services it provides and the physical destinations it supports.
To View Available Connection Services

1
Select Services under the brokers name in the Administration Console windows navigation pane. A list of the available services will appear in the result pane (see Figure 26), showing the name, port number, and current state of each service.
48
FIGURE 26
Viewing Connection Services
Select a service by clicking on its name in the result pane. For this exercise, select the name jms.
Choose Properties from the Actions menu. The Service Properties dialog box (Figure 27) will appear. You can use this dialog box to assign the service a static port number and to change the minimum and maximum number of threads allocated for it.
Service Properties Dialog Box
FIGURE 27
For this exercise, do not change any of the connection services properties.
4
Click OK to accept the new property values and dismiss the dialog box. The Actions menu also contains commands for pausing and resuming a service. If you select the admin service and pull down the Actions menu, however, you will see that the Pause Service command is disabled. This is because the admin service is the Administration Consoles link to the broker: if you paused it, you would no longer be able to access the broker.
49
Working With Physical Destinations

A physical destination is a location on a message broker where messages received from a message producer are held for later delivery to one or more message consumers. Destinations are of two kinds, depending on the messaging domain in use: queues (point-to-point domain) and topics (publish/subscribe domain). See the Message Queue Technical Overview for further discussion of messaging domains and the destinations associated with them.
Creating a Physical Destination

By default, message brokers are configured to create new physical destinations automatically whenever a message producer or consumer attempts to access a nonexistent destination. Such auto-created destinations are convenient to use while testing client code in a software development environment. In a production setting, however, it is advisable to disable the automatic creation of destinations and instead require all destinations to be created explicitly by an administrator. The following procedure shows how to add such an admin-created destination to a broker.
To Add a Physical Destination to a Broker

1
Click on the Destinations item under the brokers name in the Administration Console windows navigation pane and choose Add Broker Destination from the Actions menu. Alternatively, you can right-click on Destinations and choose Add Broker Destination from the pop-up context menu. In either case, the Add Broker Destination dialog box (Figure 28) will appear.
50
FIGURE 28
Add Broker Destination Dialog Box
Enter a name for the physical destination in the Destination Name field. Note the name that you assign to the destination; you will need it later when you create an administered object corresponding to this physical destination. For this exercise, type in the name MyQueueDest.
Select the Queue or Topic radio button to specify the type of destination to create. For this exercise, select Queue if it is not already selected.
Click OK to add the physical destination and dismiss the dialog box. The new destination will appear in the result pane.
Viewing Physical Destination Properties

You can use the Properties command on the Administration Consoles Actions menu to view or modify the properties of a physical destination.
51
To View or Modify the Properties of a Physical Destination

1
Select Destinations under the brokers name in the Administration Console windows navigation pane. A list of the available physical destinations will appear in the result pane, showing the name, type, and current state of each destination.
2 3
Select a physical destination by clicking on its name in the result pane. Choose Properties from the Actions menu. The Broker Destination Properties dialog box (Figure 29) will appear, showing current status and configuration information about the selected physical destination. You can use this dialog box to change various configuration properties, such as the maximum number of messages, producers, and consumers that the destination can accommodate.
52
FIGURE 29
Broker Destination Properties Dialog Box
For this exercise, do not change any of the destinations properties. For topic destinations, the Broker Destination Properties dialog box contains an additional tab, Durable Subscriptions. Clicking on this tab displays the Durable Subscriptions panel (Figure 210), listing information about all durable subscriptions currently associated with the given topic.
53
FIGURE 210
Durable Subscriptions Panel
You can use the Durable Subscriptions panels Purge and Delete buttons to

Purge all pending messages associated with a durable subscription Remove a durable subscription from the topic
The Durable Subscriptions tab is disabled for queue destinations.

4
Click OK to accept the new property values and dismiss the dialog box.
Purging Messages From a Physical Destination

Purging messages from a physical destination removes all pending messages associated with the destination, leaving the destination empty.
To Purge Messages From a Physical Destination

1
Select Destinations under the brokers name in the Administration Console windows navigation pane. A list of the available physical destinations will appear in the result pane, showing the name, type, and current state of each destination. Select a destination by clicking on its name in the result pane. Choose Purge Messages from the Actions menu. A confirmation dialog box will appear, asking you to confirm that you wish to proceed with the operation. Click Yes to confirm the operation and dismiss the confirmation dialog.
2 3
Deleting a Physical Destination

Deleting a destination purges all of its messages and then destroys the destination itself, removing it permanently from the broker to which it belongs.
Working With Object Stores
To Delete a Physical Destination

1
Select Destinations under the brokers name in the Administration Console windows navigation pane. A list of the available destinations will appear in the result pane, showing the name, type, and current state of each destination.
2 3
Select a destination by clicking on its name in the result pane. Choose Delete from the Edit menu. A confirmation dialog box will appear, asking you to confirm that you wish to proceed with the operation.
Click Yes to confirm the operation and dismiss the confirmation dialog. For this exercise, do not delete the destination MyQueueDest that you created earlier; instead, click No to dismiss the confirmation dialog without performing the delete operation.

An object store is used to store Message Queue administered objects, which encapsulate implementation and configuration information specific to a particular Message Queue provider. An object store can be either a Lightweight Directory Access Protocol (LDAP) directory server or a directory in the local file system. Although it is possible to instantiate and configure administered objects directly from within a client applications code, it is generally preferable to have an administrator create and configure these objects and store them in an object store, where client applications can access them using the Java Naming and Directory Interface (JNDI). This allows the client code itself to remain provider-independent.
Adding an Object Store

Although the Administration Console allows you to manage an object store, you cannot use it to create one; the LDAP server or file-system directory that will serve as the object store must already exist ahead of time. You can then add this existing object store to the Administration Console, creating a reference to it that you can use to operate on it from within the Console.
55
Note The sample application used in this chapter assumes that the object store is held in a directory named Temp on the C drive. If you do not already have a folder named Temp on your C drive, create one before proceeding with the following exercise. (On non-Windows platforms, you can use the /tmp directory, which should already exist.)
To Add an Object Store to the Administration Console

1
Click on the Object Stores item in the Administration Console windows navigation pane and choose Add Object Store from the Actions menu. Alternatively, you can right-click on Object Stores and choose Add Object Store from the pop-up context menu. In either case, the Add Object Store dialog box (Figure 211) will appear.
Add Object Store Dialog Box
FIGURE 211
Enter a name for the object store in the Object Store Label field. This provides a label that identifies the object store in the Administration Console. For this exercise, type in the name MyObjectStore.
Enter the JNDI attribute values to be used for looking up administered objects: a. Select the name of the attribute you wish to specify from the Name pull-down menu. b. Type the value of the attribute into the Value field.
56
c. Click the Add button to add the specified attribute value. The property and its value will appear in the property summary pane. Repeat steps Adding an Object Store on page 55 to Adding an Object Store on page 55 for as many attributes as you need to set. For this exercise, set the java.naming.factory.initial attribute to com.sun.jndi.fscontext.RefFSContextFactory and the java.naming.provider.url attribute to file:///C:/Temp (or file:///tmp on the Solaris or Linux platforms). These are the only attributes you need to set for a file-system object store; see LDAP Server Object Stores on page 195 for information on the attribute values needed for an LDAP store.
4
Click OK to add the object store and dismiss the dialog box. The new object store will appear under Object Stores in the navigation pane, as shown in Figure 212. The red X over the object stores icon indicates that it is not currently connected to the Administration Console.
Object Store Displayed in Administration Console Window
FIGURE 212
When you click on the object store in the navigation pane, its contents are listed in the result pane. Since you have not yet added any administered objects to the object store, the Count column shows 0 for both destinations and connection factories. Once you have added an object store, you can use the Properties command on the Actions menu (or the pop-up context menu) to display an Object Store Properties dialog box, similar to the Add Object Store dialog shown in Figure 211, to view or modify any of its properties.
57
Working With Administered Objects
Connecting to an Object Store

Now that you have added an object store to the Administration Console, you must connect to it in order to add administered objects to it.
To Connect to an Object Store
Click on the object stores name in the Administration Console windows navigation pane and choose Connect to Object Store from the Actions menu. Alternatively, you can right-click on the object stores name and choose Connect to Object Store from the pop-up context menu. In either case, the red X will disappear from the object stores icon, indicating that it is now connected to the Administration Console.

Once you have connected an object store to the Administration Console, you can proceed to add administered objects (connection factories and destinations) to it. This section describes how.
Note The Administration Console displays only Message Queue administered objects. If an object store contains a nonMessage Queue object with the same lookup name as an administered object that you want to add, you will receive an error when you attempt the add operation.
Adding a Connection Factory

Connection factories are used by client applications to create connections to a broker. By configuring a connection factory, you can control the properties of the connections it creates.
To Add a Connection Factory to an Object Store

1
Make sure the object store is connected to the Administration Console (see Connecting to an Object Storeon page 58). Click on the Connection Factories item under the object stores name in the Administration Console windows navigation pane and choose Add Connection Factory Object from the Actions menu. Alternatively, you can right-click on Connection Factories and choose Add Connection Factory Object from the pop-up context menu. In either case, the Add Connection Factory Object dialog box ( Figure 213) will appear.
58
FIGURE 213
Add Connection Factory Object Dialog Box
Enter a name for the connection factory in the Lookup Name field. This is the name that client applications will use when looking up the connection factory with JNDI. For this exercise, type in the name MyQueueConnectionFactory .
Choose the type of connection factory you wish to create from the Factory Type pull-down menu. For this exercise, choose QueueConnectionFactory. Click the Connection Handling tab. The Connection Handling panel will appear, as shown in Figure 213. Fill in the Message Server Address List field with the address(es) of the broker(s) to which this connection factory will create connections. The address list may consist of a single broker or (in the case of a broker cluster) multiple brokers. For each broker, it specifies information such as the brokers connection service, host name, and port number. The exact nature and syntax of the information to be specified varies, depending on the connection service to be used; see Connection Handling on page 381 for specifics. For this exercise, there is no need to type anything into the Message Server Address List field, since the sample application HelloWorldMessageJNDI expects the connection factory to use the
Chapter 2 Quick-Start Tutorial 59
standard address list attributes to which it is automatically configured by default (connection service jms , host name localhost, and port number 7676 ).
7
Configure any other attributes of the connection factory as needed. The Add Connection Factory Object dialog box contains a number of other panels besides Connection Handling, which can be used to configure various attributes for a connection factory. For this exercise, do not change any of the other attribute settings. You may find it instructive, however, to click through the other tabs to get an idea of the kinds of configuration information that can be specified. Use the Help button to learn more about the contents of these other configuration panels.
If appropriate, click the Read-Only checkbox. This locks the connection factory objects configuration attributes to the values they were given at creation time. A read-only administered objects attributes cannot be overridden, whether programmatically from client code or administratively from the command line. For this exercise, do not check Read-Only.
Click OK to create the connection factory, add it to the object store, and dismiss the dialog box. The new connection factory will appear in the result pane.
Adding a Destination
A destination administered object represents a physical destination on a broker, enabling clients to send messages to that physical destination independently of provider-specific configurations and naming syntax. When a client sends a message addressed via the administered object, the broker will deliver the message to the corresponding physical destination, if it exists. If no such physical destination exists, the broker will create one automatically if auto-creation is enabled, as described under Creating a Physical Destination on page 50, and deliver the message to it; otherwise, it will generate an error signaling that the message cannot be delivered. The following procedure describes how to add a destination administered object to the object store corresponding to an existing physical destination.
To Add a Destination to an Object Store

1
Make sure the object store is connected to the Administration Console (see Connecting to an Object Storeon page 58).
60
Click on the Destinations item under the object stores name in the Administration Console windows navigation pane and choose Add Destination Object from the Actions menu. Alternatively, you can right-click on Destinations and choose Add Destination Object from the pop-up context menu. In either case, the Add Destination Object dialog box (Figure 214) will appear.
Add Destination Object Dialog Box
FIGURE 214
Enter a name for the destination administered object in the Lookup Name field. This is the name that client applications will use when looking up the destination with JNDI. For this exercise, type in the name MyQueue.
Select the Queue or Topic radio button to specify the type of destination object to create. For this exercise, select Queue if it is not already selected.
Enter the name of the corresponding physical destination in the Destination Name field. This is the name you specified when you added the physical destination to the broker (see Working With Physical Destinations on page 50). For this exercise, type in the name MyQueueDest.
Optionally, enter a brief description of the destination in the Destination Description field. The contents of this field are intended strictly for human consumption and have no effect on client operations. For this exercise, you can either delete the contents of the Destination Description field or type in some descriptive text such as Example destination for MQ Admin Guide tutorial
61
If appropriate, click the Read-Only checkbox. This locks the destination objects configuration attributes to the values they were given at creation time. A read-only administered objects attributes cannot be overridden, whether programmatically from client code or administratively from the command line. For this exercise, do not check Read-Only.
Click OK to create the destination object, add it to the object store, and dismiss the dialog box. The new destination object will appear in the result pane, as shown in Figure 215.
Destination Object Displayed in Administration Console Window
FIGURE 215
Viewing Administered Object Properties

You can use the Properties command on the Administration Consoles Actions menu to view or modify the properties of an administered object.
To View or Modify the Properties of an Administered Object

1
Select Connection Factories or Destinations under the object stores name in the Administration Console windows navigation pane. A list of the available connection factory or destination administered objects will appear in the result pane, showing the lookup name and type of each (as well as the destination name in the case of destination administered objects). Select an administered object by clicking on its name in the result pane. Choose Properties from the Actions menu. The Connection Factory Object Properties or Destination Object Properties dialog box will appear, similar to the Add Connection Factory Object (Figure 213) or Add Destination Object
2 3
62
Running the Sample Application
(Figure 214) dialog. You can use this dialog box to change the selected objects configuration attributes. Note, however, that you cannot change the objects lookup name; the only way to do this is the delete the object and then add a new administered object with the desired lookup name.
4
Click OK to accept the new attribute values and dismiss the dialog box.
Deleting an Administered Object

Deleting an administered object removes it permanently from the object store to which it belongs.
To Delete an Administered Object

1
Select Connection Factories or Destinations under the object stores name in the Administration Console windows navigation pane. A list of the available connection factory or destination administered objects will appear in the result pane, showing the lookup name and type of each (as well as the destination name in the case of destination administered objects).
2 3
Select an administered object by clicking on its name in the result pane. Choose Delete from the Edit menu. A confirmation dialog box will appear, asking you to confirm that you wish to proceed with the operation. Click Yes to confirm the operation and dismiss the confirmation dialog. For this exercise, do not delete the administered objects MyQueue or MyQueueConnectionFactory that you created earlier; instead, click No to dismiss the confirmation dialog without performing the delete operation.

The sample application HelloWorldMessageJNDI is provided for use with this tutorial. It uses the physical destination and administered objects that you created:

A queue physical destination named MyQueueDest A queue connection factory administered object with JNDI lookup name MyQueueConnectionFactory A queue administered object with JNDI lookup name MyQueue
63
The code creates a simple queue sender and receiver, and sends and receives a Hello World message. Before running the application, open the source file HelloWorldMessageJNDI.java and read through the code. The program is short and amply documented; you should have little trouble understanding how it works.
To Run the Sample Application

Make the directory containing the HelloWorldmessageJNDI application your current directory, using one of the following commands, depending on how Message Queue was installed:
On IPS package-based installations: cd IMQ_HOME/examples/helloworld/helloworldmessagejndi
On Solaris SVR4 package-based installations: cd /usr/demo/imq/helloworld/helloworldmessagejndi
On Linux RPM package-based installations: cd /opt/sun/mq/examples/helloworld/helloworldmessagejndi
You should find the file HelloWorldMessageJNDI.class present. (If you make changes to the application, you must recompile it using the procedure for compiling a client application given in the Message Queue Developers Guide for Java Clients.)
2
Set the CLASSPATH variable to include the current directory containing the file HelloWorldMessageJNDI.class, as well as the following .jar files that are included in the Message Queue product: jms.jar imq.jar jndi.jar fscontext.jar See the Message Queue Developers Guide for Java Clients for information on setting the CLASSPATH variable.
Note The file jndi.jar is bundled with JDK 1.4. You need not add this file to your CLASSPATH
unless you are using an earlier version of the JDK.

3
Run the HelloWorldMessageJNDI application by executing one of the following commands (depending on the platform youre using):
On Solaris or Linux:
64
% java HelloWorldMessageJNDI file:///tmp
On Windows: java HelloWorldMessageJNDI
If the application runs successfully, you should see the output shown in Example 21.
Example 21
Output from Sample Application

java HelloWorldMessageJNDI Using file:///C:/Temp for Context.PROVIDER_URL
Looking up Queue Connection Factory object with lookup name: MyQueueConnectionFactory Queue Connection Factory object found. Looking up Queue object with lookup name: MyQueue Queue object found.
Creating connection to broker. Connection to broker created. Publishing a message to Queue: MyQueueDest Received the following message: Hello World
65
66
P A R T
I I

Chapter 3, Starting Brokers and Clients Chapter 4, Configuring a Broker Chapter 5, Managing a Broker Chapter 6, Configuring and Managing Connection Services Chapter 7, Managing Message Delivery Chapter 8, Configuring Persistence Services Chapter 9, Configuring and Managing Security Services Chapter 10, Configuring and Managing Broker Clusters Chapter 11, Managing Administered Objects Chapter 12, Configuring and Managing Bridge Services Chapter 13, Monitoring Broker Operations Chapter 14, Analyzing and Tuning a Message Service Chapter 15, Troubleshooting
67
68
C H A P T E R
Starting Brokers and Clients
After installing Sun GlassFish Message Queue and performing some preparatory steps, you can begin starting brokers and clients. A brokers configuration is governed by a set of configuration files, which can be overridden by command line options passed to the Broker utility (imqbrokerd); see Chapter 4, Configuring a Broker, for more information. This chapter contains the following sections:

Preparing System Resources on page 69 Starting Brokers on page 70 Deleting a Broker Instance on page 76 Starting Clients on page 77
Preparing System Resources

Before starting a broker, there are two preliminary system-level tasks to perform: synchronizing system clocks and (on the Solaris or Linux platform) setting the file descriptor limit. The following sections describe these tasks.
Synchronizing System Clocks

Before starting any brokers or clients, it is important to synchronize the clocks on all hosts that will interact with the Message Queue system. Synchronization is particularly crucial if you are using message expiration (time-to-live). Time stamps from clocks that are not synchronized could prevent message expiration from working as expected and prevent the delivery of messages. Synchronization is also crucial for broker clusters. Configure your systems to run a time synchronization protocol, such as Simple Network Time Protocol (SNTP). Time synchronization is generally supported by the xntpd daemon on Solaris
69
Starting Brokers
and Linux, and by the W32Time service on Windows. (See your operating system documentation for information about configuring this service.) After the broker is running, avoid setting the system clock backward.
Setting the File Descriptor Limit

On the Solaris and Linux platforms, the shell in which a client or broker is running places a soft limit on the number of file descriptors that a process can use. In Message Queue, each connection a client makes, or a broker accepts, uses one of these file descriptors. Each physical destination that has persistent messages also uses a file descriptor. As a result, the file descriptor limit constrains the number of connections a broker or client can have. By default, the maximum is 256 connections on Solaris or 1024 on Linux. (In practice, the connection limit is actually lower than this because of the use of file descriptors for persistent data storage.) If you need more connections than this, you must raise the file descriptor limit in each shell in which a client or broker will be executing. For information on how to do this, see the man page for the ulimit command.
Starting Brokers
You can start a broker either interactively, using the Message Queue command line utilities or the Windows Start menu, or by arranging for it to start automatically at system startup. The following sections describe how.
Starting Brokers Interactively

You can start a broker interactively from the command line, using the Broker utility (imqbrokerd). (Alternatively, on Windows, you can start a broker from the Start menu.) You cannot use the Administration Console (imqadmin) or the Command utility (imqcmd) to start a broker; the broker must already be running before you can use these tools. On the Solaris and Linux platforms, a broker instance must always be started by the same user who initially started it. Each broker instance has its own set of configuration properties and file-based persistent data store. When the broker instance first starts, Message Queue uses the users file creation mode mask (umask) to set permissions on directories containing the configuration information and persistent data for that broker instance. A broker instance has the instance name imqbroker by default. To start a broker from the command line with this name and the default configuration, simply use the command imqbrokerd This starts a broker instance named imqbroker on the local machine, with the Port Mapper at the default port of 7676 (see Port Mapper on page 97).
Starting Brokers
To specify an instance name other than the default, use the-name option to the imqbrokerd command. The following command starts a broker with the instance name myBroker: imqbrokerd -name myBroker Other options are available on the imqbrokerd command line to control various aspects of the brokers operation. See Broker Utility on page 314 for complete information on the syntax, subcommands, and options of the imqbrokerd command. For a quick summary of this information, enter the following command: imqbrokerd -help For example, the following command uses the-tty option to send errors and warnings to the command window (standard output): imqbrokerd -name myBroker -tty You can also use the -D option on the command line to override the values of properties specified in the brokers instance configuration file (config.properties). The instance configuration file is described under Modifying Configuration Files on page 80. The following example sets a brokers imq.jms.max_threads property, raising the maximum number of threads available to the jms connection service to 2000: imqbrokerd -name myBroker -Dimq.jms.max_threads=2000
Starting Brokers Automatically

Instead of starting a broker explicitly from the command line, you can set it up to start automatically at system startup. How you do this depends on the platform (Solaris, Linux, or Windows) on which you are running the broker:

Automatic Broker Startup on the Solaris Platforms on page 71 Automatic Broker Startup on the Linux Platform on page 73 Automatic Broker Startup on Windows on page 73
Automatic Broker Startup on the Solaris Platforms

The method for enabling automatic startup on the Solaris 10 platforms is different from that for Solaris 9. Both are described below.
Automatic Broker Startup on the Solaris 9 Platform

On Solaris 9 operating system, scripts that enable automatic startup are placed in the /etc/rc* directory tree during Message Queue installation. To enable the use of these scripts, you must edit the configuration file imqbrokerd.conf (located in IMQ_HOME/etc/ for installations from IPS packages and in /etc/imq/ for installations from SVR4 packages) as follows:
Chapter 3 Starting Brokers and Clients 71
Starting Brokers
To start the broker automatically at system startup, set the AUTOSTART property to YES. To have the broker restart automatically after an abnormal exit, set the RESTART property to YES. To set startup command line arguments for the broker, specify one or more values for the ARGS property.
To disable automatic broker startup at system startup, edit the configuration file /etc/imq/imqbrokerd.conf and set the AUTOSTART property to NO.
Automatic Broker Startup on the Solaris 10 Platform

Rather than using an rc file to implement automatic broker startup when a computer reboots, the following procedure makes use of the Solaris 10 Service Management Facility (SMF). For more information on using the Service Management Facility, please refer to Solaris 10 documentation.
To Implement Automatic Broker Startup on Solaris 10 OS

1
Copy and change permissions on the mqbroker startup script. # cp /var/svc/manifest/application/sun/mq/mqbroker /lib/svc/method # chmod 555 /lib/svc/method/mqbroker
Import the mqbroker service into the SMF repository. # svccfg import /var/svc/manifest/application/sun/mq/mqbroker.xml
Verify that the import was successful by checking the state of the mqbroker service. # svcs mqbroker Output resembles the following:
STATE STIME FMRI disabled 16:22:50 svc:/application/sun/mq/mqbroker:default
The service is initially shown as disabled.

4
Eanable the mqbroker service. # svcadm enable svc:/application/sun/mq/mqbroker:default Enabling the mqbroker service will start the imqbrokerd process. A reboot will subsequently restart the broker.
72
Starting Brokers
Configure the mqbroker service to pass any desired arguments to the imqbrokerd command. The options/broker_args property is used to pass arguments toimqbrokerd. For example to add -loglevel DEBUGHIGH, do the following:
# svccfg svc:> select svc:/application/sun/mq/mqbroker svc:/application/sun/mq/mqbroker> setprop options/broker_args= "-loglevel DEBUGHIGH" svc:/application/sun/mq/mqbroker> exit
To Disable Automatic Broker Startup on Solaris 10 OS
Disable the mqbroker service. # svcadm disable svc:/application/sun/mq/mqbroker:default A subsequent reboot will not restart the broker.
Automatic Broker Startup on the Linux Platform

On Linux systems, scripts that enable automatic startup are placed in the /etc/rc* directory tree during Message Queue installation. To enable the use of these scripts, you must edit the configuration file imqbrokerd.conf (located in IMQ_HOME/etc/ for installations from IPS packages and in /etc/opt/sun/mq/ for installations from RPM packages) as follows:

To start the broker automatically at system startup, set the AUTOSTART property to YES. To have the broker restart automatically after an abnormal exit, set the RESTART property to YES. To set startup command line arguments for the broker, specify one or more values for the ARGS property.
To disable automatic broker startup at system startup, edit the configuration file /etc/opt/sun/mq/imqbrokerd.conf and set the AUTOSTART property to NO.
Automatic Broker Startup on Windows

To start a broker automatically at Windows system startup, you must define the broker as a Windows service. The broker will then start at system startup time and run in the background until system shutdown. Consequently, you will not need to use the Message Queue Broker utility (imqbrokerd) unless you want to start an additional broker. A system can have no more than one broker running as a Windows service. The Windows Task Manager lists such a broker as two executable processes:

The native Windows service wrapper, imqbrokersvc.exe The Java runtime that is running the broker
73
Chapter 3 Starting Brokers and Clients
Starting Brokers
You can install a broker as a service when you install Message Queue on a Windows system. After installation, you can use the Service Administrator utility (imqsvcadmin) to perform the following operations:

Add a broker as a Windows service Determine the startup options for the broker service Disable a broker from running as a Windows service
To pass startup options to the broker, use the -args option to the imqsvcadmin command. This works the same way as the imqbrokerd commands -D option, as described under Starting Brokers on page 70. Use the Command utility (imqcmd) to control broker operations as usual. See Service Administrator Utility on page 334 for complete information on the syntax, subcommands, and options of the imqsvcadmin command.
Reconfiguring the Broker Service

The procedure for reconfiguring a broker installed as a Windows service is as follows:
To Reconfigure a Broker Running as a Windows Service

1
Stop the service: a. From the Settings submenu of the Windows Start menu, choose Control Panel. b. Open the Administrative Tools control panel. c. Run the Services tool by selecting its icon and choosing Open from the File menu or the pop-up context menu, or simply by double-clicking the icon. d. Under Services (Local), select the Message Queue Broker service and choose Properties from the Action menu. Alternatively, you can right-click on Message Queue Broker and choose Properties from the pop-up context menu, or simply double-click on Message Queue Broker. In either case, the Message Queue Broker Properties dialog box will appear. e. Under the General tab in the Properties dialog, click Stop to stop the broker service.
Remove the service. On the command line, enter the command imqsvcadmin remove
74
Starting Brokers
Reinstall the service, specifying different broker startup options with the -args option or different Java version arguments with the -vmargs option. For example, to change the services host name and port number to broker1 and 7878, you could use the command imqsvcadmin install -args "-name broker1 -port 7878"
Using an Alternative Java Runtime

You can use either the imqsvcadmin commands -javahome or -jrehome option to specify the location of an alternative Java runtime. (You can also specify these options in the Start Parameters field under the General tab in the services Properties dialog window.)
Note The Start Parameters field treats the backslash character (\) as an escape character, so you
must type it twice when using it as a path delimiter: for example, -javahome c:\\j2sdk1.4.0
Displaying Broker Service Startup Options

To determine the startup options for the broker service, use the imqsvcadmin query command, as shown in Example 31.
EXAMPLE 31
Displaying Broker Service Startup Options
imqsvcadmin query Service Message Queue Broker is installed. Display Name: Message Queue Broker Start Type: Automatic Binary location: C:\Sun\MessageQueue\bin\imqbrokersvc.exe JavaHome: c:\j2sdk1.4.0 Broker Args: -name broker1 -port 7878
Disabling a Broker From Running as a Windows Service

To disable a broker from running as a Windows service, use the command imqcmd shutdown bkr to shut down the broker, followed by imqsvcadmin remove to remove the service.
Deleting a Broker Instance
Alternatively, you can use the Windows Services tool, reached via the Administrative Tools control panel, to stop and remove the broker service. Restart your computer after disabling the broker service.
Troubleshooting Service Startup Problems

If you get an error when you try to start a broker as a Windows service, you can view error events that were logged:
To See Logged Service Error Events

1 2 3 4
Open the Windows Administrative Tools control panel. Start the Event Viewer tool. Select the Application event log. Choose Refresh from the Action menu to display any error events.
Deleting a Broker Instance

To delete a broker instance, use the imqbrokerd command with the -remove option: imqbrokerd [options...] -remove instance For example, if the name of the broker is myBroker, the command would be imqbrokerd -name myBroker -remove instance The command deletes the entire instance directory for the specified broker. See Broker Utility on page 314 for complete information on the syntax, subcommands, and options of the imqbrokerd command. For a quick summary of this information, enter the command imqbrokerd -help
76
Starting Clients
Starting Clients
Before starting a client application, obtain information from the application developer about how to set up the system. If you are starting Java client applications, you must set the CLASSPATH variable appropriately and make sure you have the correct .jar files installed. The Message Queue Developers Guide for Java Clients contains information about generic steps for setting up the system, but your developer may have additional information to provide. To start a Java client application, use the following command line format: java clientAppName To start a C client application, use the format supplied by the application developer (see Building and Running C Clients in Sun GlassFish Message Queue 4.4 Developers Guide for C Clients). The applications documentation should provide information on attribute values that the application sets; you may want to override some of these from the command line. You may also want to specify attributes on the command line for any Java client that uses a Java Naming and Directory Interface (JNDI) lookup to find its connection factory. If the lookup returns a connection factory that is older than the application, the connection factory may lack support for more recent attributes. In such cases, Message Queue sets those attributes to default values; if necessary, you can use the command line to override these default values. To specify attribute values from the command line for a Java application, use the following syntax: java [ [-Dattribute=value] ... ] clientAppName The value for attribute must be a connection factory administered object attribute, as described in Chapter 19, Administered Object Attribute Reference. If there is a space in the value, put quotation marks around the attribute=value part of the command line. The following example starts a client application named MyMQClient, connecting to a broker on the host OtherHost at port 7677: java -DimqAddressList=mq://OtherHost:7677/jms MyMQClient The host name and port specified on the command line override any others set by the application itself. In some cases, you cannot use the command line to specify attribute values. An administrator can set an administered object to allow read access only, or an application developer can code the client application to do so. Communication with the application developer is necessary to understand the best way to start the client program.
78
C H A P T E R
Configuring a Broker
A brokers configuration is governed by a set of configuration files and by the options passed to the imqbrokerd command at startup. This chapter describes the available configuration properties and how to use them to configure a broker. The chapter contains the following sections:

Broker Services on page 79 Setting Broker Configuration Properties on page 80
For full reference information about broker configuration properties, see Chapter 17, Broker Properties Reference
Broker Services
Broker configuration properties are logically divided into categories that depend on the services or broker components they affect:
Connection services manage the physical connections between a broker and its clients that provide transport for incoming and outgoing messages. For a discussion of properties associated with connection services, see Configuring Connection Services on page 95 Message delivery services route and deliver JMS payload messages, as well as control messages used by the message service to support reliable delivery. For a discussion of properties associated with message delivery services, including physical destinations, see Chapter 7, Managing Message Delivery Persistence services manage the writing and retrieval of data, such as messages and state information, to and from persistent storage. For a discussion of properties associated with persistence services, see Chapter 8, Configuring Persistence Services Security services authenticate users connecting to the broker and authorize their actions. For a discussion of properties associated with authentication and authorization services, as well as encryption configuration, see Chapter 9, Configuring and Managing Security Services
79
Setting Broker Configuration Properties
Clustering services support the grouping of brokers into a cluster to achieve scalability and availability. For a discussion of properties associated with broker clusters, see Chapter 10, Configuring and Managing Broker Clusters Monitoring services generate metric and diagnostic information about the brokers performance. For a discussion of properties associated with monitoring and managing a broker, see Chapter 13, Monitoring Broker Operations

You can specify a brokers configuration properties in either of two ways:

Edit the brokers configuration file. Supply the property values directly from the command line.
The following sections describe these two methods of configuring a broker.
Modifying Configuration Files

Broker configuration files contain property settings for configuring a broker. They are kept in a directory whose location depends on the operating system platform you are using; see Appendix A, Distribution-Specific Locations of Message Queue Data, for details. Message Queue maintains the following broker configuration files:
A default configuration file (default.properties) that is loaded on startup. This file is not editable, but you can read it to determine default settings and find the exact names of properties you want to change. An installation configuration file (install.properties) containing any properties specified when Message Queue was installed. This file cannot be edited after installation. A separate instance configuration file (config.properties) for each individual broker instance.
In addition, if you connect broker instances in a cluster, you may need to use a cluster configuration file (cluster.properties) to specify configuration information for the cluster; see Cluster Configuration Properties on page 361 for more information. Also, Message Queue makes use of en environment configuration file, imqenv.conf, which is used to provide the locations of external files needed by Message Queue, such as the default Java SE location and the locations of database drivers, JAAS login modules, and so forth. At startup, the broker merges property values from the various configuration files. As shown in Figure 41, the files form a hierarchy in which values specified in the instance configuration file override those in the installation configuration file, which in turn override those in the default
configuration file. At the top of the hierarchy, you can manually override any property values specified in the configuration files by using command line options to the imqbrokerd command.
FIGURE 41
Broker Configuration Files
imqbrokerd -name MyBroker -metrics 5 Startup Command
Overrides
config.properties Overrides Instance Configuration File install.properties Overrides Install Configuration File default.properties
Default Configuration File
The first time you run a broker, an instance configuration file is created containing configuration properties for that particular broker instance. 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, Distribution-Specific Locations of Message Queue Data, for the location of the instances directory.) If the file does not yet exist, you must use the -name option when starting the broker (see Broker Utility on page 314) to specify an instance name that Message Queue can use to create the file.
Chapter 4 Configuring a Broker
81
Note The instances/instanceName directory and the instance configuration file are owned by the user who initially started the corresponding broker instance by using the imqbrokerd name brokerName option. The broker instance must always be restarted by that same user.
The instance configuration file is maintained by the broker instance and is modified when you make configuration changes using Message Queue administration utilities. You can also edit an instance configuration file by hand. To do so, you must be the owner of the instances/instanceName directory or log in as the root user to change the directorys access privileges. The broker reads its instance configuration file only at startup. To effect any changes to the brokers configuration, you must shut down the broker and then restart it. Property definitions in the config.properties file (or any configuration file) use the following syntax: propertyName=value [ [,value1] ... ] For example, the following entry specifies that the broker will hold up to 50,000 messages in memory and persistent storage before rejecting additional messages: imq.system.max_count=50000 The following entry specifies that a new log file will be created once a day (every 86,400 seconds): imq.log.file.rolloversecs=86400 See Broker Services on page 79 and Chapter 17, Broker Properties Reference, for information on the available broker configuration properties and their default values.
Setting Configuration Properties from the Command Line

You can enter broker configuration properties from the command line when you start a broker, or afterward. At startup time, you use the Broker utility (imqbrokerd) to start a broker instance. Using the commands -D option, you can specify any broker configuration property and its value; see Starting Brokers on page 70 and Broker Utility on page 314 for more information. If you start the broker as a Windows service, using the Service Administrator utility (imqsvcadmin), you use the -args option to specify startup configuration properties; see Service Administrator Utility on page 334.
You can also change certain broker configuration properties while a broker is running. To modify the configuration of a running broker, you use the Command utilitys imqcmd update bkr command; see Updating Broker Properties on page 91 and Broker Management on page 321.
Chapter 4 Configuring a Broker
83
84
C H A P T E R
Managing a Broker
This chapter explains how to use the Message Queue Command utility (imqcmd) to manage a broker. The chapter has the following sections:

Command Utility Preliminaries on page 86 Using the Command Utility on page 86 Managing Brokers on page 89
This chapter does not cover all topics related to managing a broker. Additional topics are covered in the following separate chapters:
For information on configuring and managing connection services, see Chapter 6, Configuring and Managing Connection Services. For information on managing message delivery services, including how to create, display, update, and destroy physical destinations, see Chapter 7, Managing Message Delivery. For information on configuring and managing persistence services, for both flat-file and JDBC-based data stores, see Chapter 8, Configuring Persistence Services. For information about setting up security for the broker, such as user authentication, access control, encryption, and password files, see Chapter 9, Configuring and Managing Security Services. For information on configuring and managing clustering services, for both conventional and enhanced broker clusters, see Chapter 10, Configuring and Managing Broker Clusters. For information about monitoring a broker, see Chapter 13, Monitoring Broker Operations.
85
Command Utility Preliminaries
Command Utility Preliminaries

Before using the Command utility to manage a broker, you must do the following:
Start the broker using the imqbrokerd command. You cannot use the Command utility subcommands l until a broker is running. Determine whether you want to set up a Message Queue administrative user or use the default account. You must specify a user name and password to use all Command utility subcommands (except to display command help and version information). When you install Message Queue, a default flat-file user repository is installed. The repository is shipped with two default entries: an administrative user and a guest user. If you are testing Message Queue, you can use the default user name and password (admin/admin) to run the Command utility. If you are setting up a production system, you must set up authentication and authorization for administrative users. See Chapter 9, Configuring and Managing Security Services, for information on setting up a file-based user repository or configuring the use of an LDAP directory server. In a production environment, it is a good security practice to use a nondefault user name and password.
If you want to use a secure connection to the broker, set up and enable the ssladmin service on the target broker instance, For more information, see Message Encryption on page 161.
Using the Command Utility

The Message Queue Command utility (imqcmd) enables you to manage the broker and its services interactively from the command line. See Command Utility on page 318 for general reference information about the syntax, subcommands, and options of the imqcmd command, and Chapter 17, Broker Properties Reference, for specific information on the configuration properties used to specify broker behavior.
Specifying the User Name and Password

Because each imqcmd subcommand is authenticated against the user repository, it requires a user name and password. The only exceptions are commands that use the -h or -H option to display help, and those that use the -v option to display the product version. Use the -u option to specify an administrative user name. For example, the following command displays information about the default broker: imqcmd query bkr -u admin If you omit the user name, the command will prompt you for it.
Note For simplicity, the examples in this chapter use the default user name admin as the argument to the -u option. In a real-life production environment, you would use a custom user name.
Specify the password using one of the following methods:
Create a password file and enter the password into that file as the value of the imq.imqcmd.password property. On the command line, use the -passfile option to provide the name of the password file. Let the imqcmd command prompt you for the password.
Note In previous versions of Message Queue, you could use the -p option to specify a password on the imqcmd command line. As of Message Queue 4.0, this option is deprecated and is no longer supported; you must instead use one of the methods listed above.
Specifying the Broker Name and Port

Most imqcmd subcommands use the -b option to specify the host name and port number of the broker to which the command applies: -b hostName:portNumber If no broker is specified, the command applies by default to a broker running on the local host (localhost) at port number 7676. To issue a command to a broker that is running on a remote host, listening on a nondefault port, or both, you must use the -b option to specify the host and port explicitly.
Displaying the Product Version

To display the Message Queue product version, use the -v option. For example: imqcmd -v If you enter an imqcmd command line containing the -v option in addition to a subcommand or other options, the Command utility processes only the -v option. All other items on the command line are ignored.
Chapter 5 Managing a Broker
87
Displaying Help
To display help on the imqcmd command, use the -h or -H option, and do not use a subcommand. You cannot get help about specific subcommands. For example, the following command displays help about imqcmd: imqcmd -H If you enter an imqcmd command line containing the -h or -H option in addition to a subcommand or other options, the Command utility processes only the -h or -H option. All other items on the command line are ignored.
Examples
The examples in this section illustrate how to use the imqcmd command. The following example lists the properties of the broker running on host localhost at port 7676, so the -b option is unnecessary: imqcmd query bkr -u admin The command uses the default administrative user name (admin) and omits the password, so that the command will prompt for it. The following example lists the properties of the broker running on the host myserver at port 1564. The user name is aladdin: imqcmd query bkr -b myserver:1564 -u aladdin (For this command to work, the user repository would need to be updated to add the user name aladdin to the admin group.) The following example lists the properties of the broker running on localhost at port 7676. The initial timeout for the command is set to 20 seconds and the number of retries after timeout is set to 7. The users password is in a password file called myPassfile, located in the current directory at the time the command is invoked. imqcmd query bkr -u admin -passfile myPassfile -rtm 20 -rtr 7 For a secure connection to the broker, these examples could include the -secure option. This option causes the Command utility to use the ssladmin service if that service has been configured and started.
Managing Brokers
Managing Brokers
This section describes how to use Command utility subcommands to perform the following broker management tasks:

Shutting Down and Restarting a Broker on page 89 Quiescing a Broker on page 90 Pausing and Resuming a Broker on page 91 Updating Broker Properties on page 91 Viewing Broker Information on page 92
In addition to using the subcommands described in the following sections, imqcmd allows you to set system properties using the D option. This is useful for setting or overriding connection factory properties or connection-related Java system properties. For example, the following command changes the default value of imqSSLIsHostTrusted:
imqcmd list svc -secure -DimqSSLIsHostTrusted=true
The following command specifies the password file and the password used for the SSL trust store that is used by the imqcmd command:
imqcmd list svc -secure -DJavax.net.ssl.trustStore=/tmp/MyTruststore -Djavax.net.ssl.trustStorePassword=MyTrustword
Shutting Down and Restarting a Broker

The subcommand imqcmd shutdown bkr shuts down a broker: imqcmd shutdown bkr [-b hostName:portNumber] [-time nSeconds] [-nofailover] The broker stops accepting new connections and messages, completes delivery of existing messages, and terminates the broker process. The -time option, if present, specifies the interval, in seconds, to wait before shutting down the broker. For example, the following command delays 90 seconds and then shuts down the broker running on host wolfgang at port 1756: imqcmd shutdown bkr -b wolfgang:1756 -time 90 -u admin The broker will not block, but will return immediately from the delayed shutdown request. During the shutdown interval, the broker will not accept any new jms connections; admin connections will be accepted, and existing jms connections will continue to operate. If the broker belongs to an enhanced broker cluster, it will not attempt to take over for any other broker during the shutdown interval.
Chapter 5 Managing a Broker 89
Managing Brokers
If the broker is part of an enhanced broker cluster (see Enhanced Clusters in Sun GlassFish Message Queue 4.4 Technical Overview), another broker in the cluster will ordinarily attempt to take over its persistent data on shutdown; the -nofailover option to the imqcmd shutdown bkr subcommand suppresses this behavior. Conversely, you can use the imqcmd takeover bkr subcommand to force such a takeover manually (for instance, if the takeover broker were to fail before completing the takeover process); see Preventing or Forcing Broker Failover on page 190 for more information.
Note The imqcmd takeover bkr subcommand is intended only for use in failed-takeover
situations. You should use it only as a last resort, and not as a general way of forcibly taking over a running broker. To shut down and restart a broker, use the subcommand imqcmd restart bkr: imqcmd restart bkr [-b hostName:portNumber] This shuts down the broker and then restarts it using the same options that were specified when it was first started. To choose different options, shut down the broker with imqcmd shutdown bkr and then start it again with the Broker utility (imqbrokerd), specifying the options you want.
Quiescing a Broker
The subcommand imqcmd quiesce bkr quiesces a broker, causing it to refuse any new client connections while continuing to service old ones: imqcmd quiesce bkr [-b hostName:portNumber] If the broker is part of an enhanced broker cluster, this allows its operations to wind down normally without triggering a takeover by another broker, for instance in preparation for shutting it down administratively for upgrade or similar purposes. For example, the following command quiesces the broker running on host hastings at port 1066: imqcmd quiesce bkr -b hastings:1066 -u admin To reverse the process and return the broker to normal operation, use the imqcmd unquiesce bkr subcommand: imqcmd unquiesce bkr [-b hostName:portNumber] For example, the following command unquiesces the broker that was quiesced in the preceding example: imqcmd unquiesce bkr -b hastings:1066 -u admin
Managing Brokers
Pausing and Resuming a Broker

The subcommand imqcmd pause bkr pauses a broker, suspending its connection service threads and causing it to stop listening on the connection ports: imqcmd pause bkr [-b hostName:portNumber] For example, the following command pauses the broker running on host myhost at port 1588: imqcmd pause bkr -b myhost:1588 -u admin Because its connection service threads are suspended, a paused broker is unable to accept new connections, receive messages, or dispatch messages. The admin connection service is not suspended, allowing you to continue performing administrative tasks needed to regulate the flow of messages to the broker. Pausing a broker also does not suspend the cluster connection service; however, since message delivery within a cluster depends on the delivery functions performed by the different brokers in the cluster, pausing a broker in a cluster may result in a slowing of some message traffic. You can also pause individual connection services and physical destinations. For more information, see Pausing and Resuming a Connection Service on page 99 and Pausing and Resuming a Physical Destination on page 112. The subcommand imqcmd resume bkr reactivates a brokers service threads, causing it to resume listening on the ports: imqcmd resume bkr [-b hostName:portNumber] For example, the following command resumes the default broker (host localhost at port 7676): imqcmd resume bkr -u admin
Updating Broker Properties

The subcommand imqcmd update bkr can be used to change the values of a subset of broker properties for the default broker (or for the broker at a specified host and port): imqcmd update bkr [-b hostName:portNumber] -o property1=value1 [ [-o property2=value2] ... ] For example, the following command turns off the auto-creation of queue destinations for the default broker: imqcmd update bkr -o imq.autocreate.queue=false -u admin You can use imqcmd update bkr to update any of the following broker properties:
Managing Brokers
imq.autocreate.queue imq.autocreate.topic imq.autocreate.queue.maxNumActiveConsumers imq.autocreate.queue.maxNumBackupConsumers imq.cluster.url imq.destination.DMQ.truncateBody imq.destination.logDeadMsgs imq.log.level imq.log.file.rolloversecs imq.log.file.rolloverbytes imq.system.max_count imq.system.max_size imq.message.max_size imq.portmapper.port See Chapter 17, Broker Properties Reference, for detailed information about these properties.
Viewing Broker Information

To display information about a single broker, use the imqcmd query bkr subcommand: imqcmd query bkr -b hostName:portNumber
92
Managing Brokers
This lists the current settings of the brokers properties, as shown in Example 51.
EXAMPLE 51
Broker Information Listing
Querying the broker specified by: ------------------------Host Primary Port ------------------------localHost 7676 Version Instance Name Broker ID Primary Port Broker is Embedded Instance Configuration/Data Root Directory Current Number of Messages in System Current Total Message Bytes in System Current Number of Messages in Dead Message Queue Current Total Message Bytes in Dead Message Queue Log Dead Messages Truncate Message Body in Dead Message Queue Max Number of Messages in System Max Total Message Bytes in System Max Message Size Auto Auto Auto Auto Create Queues Create Topics Created Queue Max Number of Active Consumers Created Queue Max Number of Backup Consumers ID Is Highly Available Broker List (active) Broker List (configured) Master Broker URL 4.4 imqbroker mybroker 7676 false /var/imq 0 0 0 0 true false unlimited (-1) unlimited (-1) 70m true true 1 0 myClusterID true
Cluster Cluster Cluster Cluster Cluster Cluster
Log Level Log Rollover Interval (seconds) Log Rollover Size (bytes)
INFO 604800 unlimited (-1)
The imqcmd metrics bkr subcommand displays detailed metric information about a brokers operation:
Managing Brokers
imqcmd metrics bkr [-b hostName:portNumber] [-m metricType] [-int interval] [-msp numSamples] The -m option specifies the type of metric information to display:

ttl (default): Messages and packets flowing into and out of the broker rts: Rate of flow of messages and packets into and out of the broker per second cxn: Connections, virtual memory heap, and threads
The -int and -msp options specify, respectively, the interval (in seconds) at which to display the metrics and the number of samples to display in the output. The default values are 5 seconds and an unlimited number of samples. For example, the following command displays the rate of message flow into and out of the default broker (host localhost at port 7676) at 10-second intervals: imqcmd metrics bkr -m rts -int 10 -u admin Example 52 shows an example of the resulting output.
EXAMPLE 52
Broker Metrics Listing
-------------------------------------------------------Msgs/sec Msg Bytes/sec Pkts/sec Pkt Bytes/sec In Out In Out In Out In Out -------------------------------------------------------0 0 27 56 0 0 38 66 10 0 7365 56 10 10 7457 1132 0 0 27 56 0 0 38 73 0 10 27 7402 10 20 1400 8459 0 0 27 56 0 0 38 73
For a more detailed description of the data gathered and reported by the broker, see Brokerwide Metrics on page 404. For brokers belonging to a broker cluster, the imqcmd list bkr subcommand displays information about the configuration of the cluster; see Displaying a Cluster Configuration on page 180 for more information.
94
C H A P T E R
Configuring and Managing Connection Services
Message Queue offers various connection services using a variety of transport protocols for connecting both application and administrative clients to a broker. This chapter describes how to configure and manage these services and the connections they support:

Configuring Connection Services on page 95 Managing Connection Services on page 99 Managing Connections on page 103
Configuring Connection Services

Broker configuration properties related to connection services are listed under Connection Properties on page 337. Figure 61 shows the connection services provided by the Message Queue broker.
95
FIGURE 61
Message Queue Connection Services
Persisted Messages and Broker State
Configuration Files and Logs
User Repository
Java Client
Java Client Runtime
httpjms HTTP/ (HTTP) Web HTTPS httpsjms Server Tunnel (HTTPS) Servlet jms (TCP) (TCP) ssljms (TLS) admin (TCP)
Firewall
Broker jms (TCP) ssljms (TLS)
Physical Destinations
C C Client Runtime Client
JNDI
(RMI)
ssladmin (TLS) MQ/JMX JMX Runtime Client
Administered Objects Legend Message Queue Message Service
Admin
These connection services are distinguished by two characteristics, as shown in Table 61:
The service type specifies whether the service provides JMS message delivery (NORMAL) or Message Queue administration services ( ADMIN). The protocol type specifies the underlying transport protocol.
Message Queue Connection Service Characteristics
Service Type Protocol Type
TABLE 61
Service Name
jms ssljms
NORMAL NORMAL
TCP TLS (SSL-based security)
96
TABLE 61
Message Queue Connection Service Characteristics

Service Type
(Continued)
Protocol Type
Service Name
httpjms httpsjms admin ssladmin
NORMAL NORMAL ADMIN ADMIN
HTTP HTTPS (SSL-based security) TCP TLS (SSL-based security)
By setting a brokers imq.service.activelist property, you can configure it to run any or all of these connection services. The value of this property is a list of connection services to be activated when the broker is started up; if the property is not specified explicitly, the jms and admin services will be activated by default. Each connection service also supports specific authentication and authorization features; see Introduction to Security Services on page 137 for more information.
Note There is also a special cluster connection service, used internally by the brokers within a broker cluster to exchange information about the clusters configuration and state. This service is not intended for use by clients communicating with a broker. See Chapter 10, Configuring and Managing Broker Clusters, for more information about broker clusters.
Also there are two JMX connectors, jmxrmi and ssljmxrmi, that support JMX-based administration. These JMX connectors are very similar to the connection services in Table 61, above, and are used by JMX clients to establish a connection to the broker's MBean server. For more information, see JMX Connection Infrastructure on page 447.
Port Mapper
Each connection service is available at a particular port, specified by host name (or IP address) and port number. You can explicitly specify a static port number for a service or have the brokers Port Mapper assign one dynamically. The Port Mapper itself resides at the brokers primary port, which is normally located at the standard port number 7676. (If necessary, you can use the broker configuration property imq.portmapper.port to override this with a different port number.) By default, each connection service registers itself with the Port Mapper when it starts up. When a client creates a connection to the broker, the Message Queue client runtime first contacts the Port Mapper, requesting a port number for the desired connection service. Alternatively, you can override the Port Mapper and explicitly assign a static port number to a connection service, using the imq.serviceName.protocolType. port configuration property (where serviceName and protocolType identify the specific connection service, as shown in Table 61). (Only the jms, ssljms, admin, and ssladmin connection services can be configured
Chapter 6 Configuring and Managing Connection Services 97
this way; the httpjms and httpsjms services use different configuration properties, described in Appendix C, HTTP/HTTPS Support). Static ports are generally used only in special situations, however, such as in making connections through a firewall (see Connecting Through a Firewall on page 171), and are not recommended for general use.
Note In cases where two or more hosts are available (such as when more than one network interface card is installed in a computer), you can use broker properties to specify which host the connection services should bind to. The imq.hostname property designates a single default host for all connection services; this can then be overridden, if necessary, with imq.serviceName. protocolType.hostname (for the jms, ssljms, admin, or ssladmin service) or imq.portmapper.hostname (for the Port Mapper itself).
When multiple Port Mapper requests are received concurrently, they are stored in an operating system backlog while awaiting action. The imq.portmapper.backlog property specifies the maximum number of such backlogged requests. When this limit is exceeded, any further requests will be rejected until the backlog is reduced.
Thread Pool Management

Each connection service is multithreaded, supporting multiple connections. The threads needed for these connections are maintained by the broker in a separate thread pool for each service. As threads are needed by a connection, they are added to the thread pool for the service supporting that connection. The threading model you choose specifies whether threads are dedicated to a single connection or shared by multiple connections:
In the dedicated model, each connection to the broker requires two threads: one for incoming and one for outgoing messages. This limits the number of connections that can be supported, but provides higher performance. In the shared model, connections are processed by a shared thread when sending or receiving messages. Because each connection does not require dedicated threads, this model increases the number of possible connections, but at the cost of lower performance because of the additional overhead needed for thread management.
The brokers imq.serviceName. threadpool_model property specifies which of the two models to use for a given connection service. This property takes either of two string values: dedicated or shared. If you dont set the property explicitly, dedicated is assumed by default. You can also set the broker properties imq.serviceName. min_threads and imq.serviceName. max_threads to specify a minimum and maximum number of threads in a services thread pool. When the number of available threads exceeds the specified minimum threshold, Message Queue will shut down threads as they become free until the minimum is reached again, thereby
Managing Connection Services
saving on memory resources. Under heavy loads, the number of threads might increase until the pools maximum number is reached; at this point, new connections are rejected until a thread becomes available. The shared threading model uses distributor threads to assign threads to active connections. The broker property imq.shared.connectionMonitor_limit specifies the maximum number of connections that can be monitored by a single distributor thread. The smaller the value of this property, the faster threads can be assigned to connections. The imq.ping.interval property specifies the time interval, in seconds, at which the broker will periodically test (ping) a connection to verify that it is still active, allowing connection failures to be detected preemptively before an attempted message transmission fails.

Message Queue brokers support connections from both application clients and administrative clients. See Configuring Connection Services on page 95 for a description of the available connection services. The Command utility provides subcommands that you can use for managing both connection services as a whole and individual services; to apply a subcommand to a particular service, use the -n option to specify one of the names listed in the Service Name column of Table 61. Subcommands are available for the following connection service management tasks:

Pausing and Resuming a Connection Service on page 99 Updating Connection Service Properties on page 100 Viewing Connection Service Information on page 101
Pausing and Resuming a Connection Service

Pausing a connection service has the following effects:
The broker stops accepting new client connections on the paused service. If a Message Queue client attempts to open a new connection, it will get an exception. All existing connections on the paused service are kept alive, but the broker suspends all message processing on such connections until the service is resumed. (For example, if a client attempts to send a message, the send method will block until the service is resumed.) The message delivery state of any messages already received by the broker is maintained. (For example, transactions are not disrupted and message delivery will resume when the service is resumed.)
The admin connection service can never be paused; to pause and resume any other service, use the subcommands imqcmd pause svc and imqcmd resume svc. The syntax of the imqcmd pause svc subcommand is as follows:
Chapter 6 Configuring and Managing Connection Services 99
imqcmd pause svc -n serviceName [-b hostName:portNumber] For example, the following command pauses the httpjms service running on the default broker (host localhost at port 7676): imqcmd pause svc -n httpjms -u admin The imqcmd resume svc subcommand resumes operation of a connection service following a pause: imqcmd resume svc -n serviceName [-b hostName:portNumber]
Updating Connection Service Properties

You can use the imqcmd update svc subcommand to change the value of one or more of the service properties listed in Table 62. See Connection Properties on page 337 for a description of these properties.
TABLE 62 Property
Connection Service Properties Updated by Command Utility

Description
port
Port assigned to the service to be updated (does not apply to httpjms or httpsjms) A value of 0 means the port is dynamically allocated by the Port Mapper.
minThreads maxThreads
Minimum number of threads assigned to the service Maximum number of threads assigned to the service
The imqcmd update svc subcommand has the following syntax: imqcmd update svc -n serviceName [-b hostName:portNumber] -o property1=value1 [[-o property2=value2]...] For example, the following command changes the minimum number of threads assigned to the jms connection service on the default broker (host localhost at port 7676) to 20: imqcmd update svc -o minThreads=20 -u admin
100
Viewing Connection Service Information

To list the connection services available on a broker, use the imqcmd list svc subcommand: imqcmd list svc [-b hostName:portNumber] For example, the following command lists all services on the default broker (host localhost at port 7676): imqcmd list svc -u admin Example 61 shows an example of the resulting output.
EXAMPLE 61
Connection Services Listing
-----------------------------------------------Service Name Port Number Service State -----------------------------------------------admin 41844 (dynamic) RUNNING httpjms UNKNOWN httpsjms UNKNOWN jms 41843 (dynamic) RUNNING ssladmin dynamic UNKNOWN ssljms dynamic UNKNOWN
The imqcmd query svc subcommand displays information about a single connection service: imqcmd query svc -n serviceName [-b hostName:portNumber]
For example, the following command displays information about the jms connection service on the default broker (host localhost at port 7676): imqcmd query svc -n jms -u admin
Chapter 6 Configuring and Managing Connection Services
101
Example 62 shows an example of the resulting output.

EXAMPLE 62
Connection Service Information Listing
Service Name Service State Port Number Current Number of Allocated Threads Current Number of Connections Min Number of Threads Max Number of Threads
jms RUNNING 60920 (dynamic) 0 0 10 1000
To display metrics information about a connection service, use the imqcmd metrics svc subcommand: imqcmd metrics svc -n serviceName [-b hostName:portNumber] [-m metricType] [-int interval] [-msp numSamples] The -m option specifies the type of metric information to display:
ttl (default): Messages and packets flowing into and out of the broker by way of the specified connection service rts: Rate of flow of messages and packets into and out of the broker per second by way of the specified connection service cxn: Connections, virtual memory heap, and threads
The -int and -msp options specify, respectively, the interval (in seconds) at which to display the metrics and the number of samples to display in the output. The default values are 5 seconds and an unlimited number of samples. For example, the following command displays cumulative totals for messages and packets handled by the default broker (host localhost at port 7676) by way of the jms connection service: imqcmd metrics svc -n jms -m ttl -u admin
102
Managing Connections

EXAMPLE 63
Connection Service Metrics Listing
------------------------------------------------Msgs Msg Bytes Pkts Pkt Bytes In Out In Out In Out In Out ------------------------------------------------164 100 120704 73600 282 383 135967 102127 657 100 483552 73600 775 876 498815 149948
For a more detailed description of the use of the Command utility to report connection service metrics, see Connection Service Metrics on page 406.
The Command utilitys list cxn and query cxn subcommands display information about individual connections. The subcommand imqcmd list cxn lists all connections for a specified connection service: imqcmd list cxn [-svn serviceName] [-b hostName:portNumber] If no service name is specified, all connections are listed. For example, the following command lists all connections on the default broker (host localhost at port 7676): imqcmd list cxn -u admin
103

EXAMPLE 64
Broker Connections Listing
Listing all the connections on the broker specified by: ----------------------------------Host Primary Port -----------------------------------localhost 7676 --------------------------------------------------------------------------Connection ID User Service Producers Consumers Host --------------------------------------------------------------------------1964412264455443200 guest jms 0 1 127.0.0.1 1964412264493829311 admin admin 1 1 127.0.0.1 Successfully listed connections.
To display detailed information about a single connection, obtain the connection identifier from imqcmd list cxn and pass it to the imqcmd query cxn subcommand: imqcmd query cxn -n connectionID [-b hostName:portNumber] For example, the command imqcmd query cxn -n 421085509902214374 -u admin produces output like that shown in Example 65.
EXAMPLE 65
Connection Information Listing
Connection ID User Service Producers Consumers Host Port Client ID Client Platform
421085509902214374 guest jms 0 1 111.22.333.444 60953
The imqcmd destroy cxn subcommand destroys a connection:

imqcmd destroy cxn -n connectionID [-b hostName:portNumber] For example, the command imqcmd destroy cxn -n 421085509902214374 -u admin destroys the connection shown in Example 65.
105
106
C H A P T E R
Managing Message Delivery
A Message Queue message is routed to its consumer clients by way of a physical destination on a message broker. The broker manages the memory and persistent storage associated with the physical destination and configures its behavior. The broker also manages memory at a system-wide level, to assure that sufficient resources are available to support all destinations. Message delivery also involves the maintenance of state information needed by the broker to route messages to consumers and to track acknowledgements and transactions. This chapter provides information needed to manage message delivery, and includes the following topics:

Configuring and Managing Physical Destinations on page 107 Managing Broker System-Wide Memory on page 121 Managing Durable Subscriptions on page 123 Managing Transactions on page 124
Configuring and Managing Physical Destinations

This section describes how to use the Message Queue Command utility (imqcmd) to manage physical destinations. It includes discussion of a specialized physical destination managed by the broker, the dead message queue, whose properties differ somewhat from those of other destinations.
Note In a broker cluster, you create a physical destination on one broker and the cluster propagates it to all the others. Because the brokers cooperate to route messages across the cluster, client applications can consume messages from destinations on any broker in the cluster. However the persistence and acknowledgment of a message is managed only by the broker to which a message was originally produced.
This section covers the following topics regarding the management of physical destinations:
107
Command Utility Subcommands for Physical Destination Management on page 108 Creating and Destroying Physical Destinations on page 109 Pausing and Resuming a Physical Destination on page 112 Purging a Physical Destination on page 113 Updating Physical Destination Properties on page 114 Viewing Physical Destination Information on page 114 Managing Physical Destination Disk Utilization on page 118 Using the Dead Message Queue on page 120
Note For provider independence and portability, client applications typically use destination administered objects to interact with physical destinations. Chapter 11, Managing Administered Objects, describes how to configure such administered objects for use by client applications. For a general conceptual introduction to physical destinations, see the Message Queue Technical Overview.
Command Utility Subcommands for Physical Destination Management

The Message Queue Command utility (imqcmd) enables you to manage physical destinations interactively from the command line. See Chapter 16, Command Line Reference, for general reference information about the syntax, subcommands, and options of the imqcmd command, and Chapter 18, Physical Destination Property Reference, for specific information on the configuration properties used to specify physical destination behavior. Table 71 lists the imqcmd subcommands for physical destination management. For full reference information about these subcommands, see Table 167.
TABLE 71
Physical Destination Subcommands for the Command Utility

Description
Subcommand
create dst destroy dst pause dst resume dst purge dst compact dst update dst list dst
Create physical destination Destroy physical destination Pause message delivery for physical destination Resume message delivery for physical destination Purge all messages from physical destination Compact physical destination Set physical destination properties List physical destinations
108
TABLE 71
Physical Destination Subcommands for the Command Utility

Description
(Continued)
Subcommand
query dst metrics dst
List physical destination property values Display physical destination metrics
Creating and Destroying Physical Destinations

The subcommand imqcmd create dst creates a new physical destination: imqcmd create dst -t destType -n destName [ [-o property=value] ... ] You supply the destination type (q for a queue or t for a topic) and the name of the destination.
Naming Destinations
Destination names must conform to the rules described below for queue and topic destinations.
Supported Queue Destination Names

Queue destination names must conform to the following rules:
It must contain only alphabetic characters (AZ, az), digit characters (09), underscores (_), and dollar signs ($). It must not contain spaces. It must begin with an alphabetic character (AZ, az), an underscore (_), or a dollar sign ($). It must not begin with the characters mq.
For example, the following command creates a queue destination named XQueue: imqcmd create dst -t q -n XQueue
Supported Topic Destination Names

Topic destination names must conform to the same rules as queue destinations, as specified in Supported Queue Destination Names on page 109, except that Message Queue also supports, in addition, topic destination names that include wildcard characters, representing multiple destinations. These symbolic names allow publishers to publish messages to multiple topics and subscribers to consume messages from multiple topics. Using symbolic names, you can create destinations, as needed, consistent with the wildcard naming scheme. Publishers and subscribers automatically publish to and consume from any added destinations that match the symbolic names. (Wildcard topic subscribers are more common than publishers.)
Chapter 7 Managing Message Delivery 109
The format of a symbolic topic destination name consists of multiple segments, in which wildcard characters (*, **, >) can represent one or more segments of the name. For example, suppose you have a topic destination naming scheme as follows: size.color.shape where the topic name segments can have the following values:

size: large, medium, small, ... color: red, green, blue, ... shape: circle, triangle, square, ...
Message Queue supports the following wildcard characters:

* matches a single segment ** matches one or more segments > matches any number of successive segments
You can therefore indicate multiple topic destinations as follows: large.*.circle would represent:
large.red.circle large.green.circle ...
**.square would represent all names ending in .square, for example:

small.green.square medium.blue.square ...
small.> would represent all destination names starting with small., for example:
small.blue.circle small.red.square ...
To use this multiple destination feature, you create topic destinations using a naming scheme similar to that described above. For example, the following command creates a topic destination named large.green.circle: imqcmd create dst -t t -n large.green.circle Client applications can then create wildcard publishers or wildcard consumers using symbolic destination names, as shown in the following examples:
EXAMPLE 71
Wildcard Publisher
... String DEST_LOOKUP_NAME = "large.*.circle"; Topic t = (Destination) ctx.lookup(DEST_LOOKUP_NAME); TopicPublisher myPublisher = mySession.createPublisher(t) myPublisher.send(myMessage);
In this example, the broker will place a copy of the message in any destination that matches the symbolic name large.*.circle
EXAMPLE 72
Wildcard Subscriber
... String DEST_LOOKUP_NAME = "**.square"; Topic t = (Destination) ctx.lookup(DEST_LOOKUP_NAME); TopicSubscriber mySubscriber = mySession.createSubscriber(t); Message m = mySubscriber.receive();
In this example, a subscriber will be created if there is at least one destination that matches the symbolic name **.square and will receive messages from all destinations that match that symbolic name. If there are no destinations matching the symbolic name, the subscriber will not be registered with the broker until such a destination exists. If you create additional destinations that match a symbolic name, then wildcard publishers created using that symbolic name will subsequently publish to that destination and wildcard subscribers created using that symbolic name will subsequently receive messages from that destination. In addition, Message Queue administration tools, in addition to reporting the total number of publishers (producers) and subscribers (consumers) for a topic destination, will also report the number of publishers that are wildcard publishers (including their corresponding symbolic destination names) and the number of subscribers that are wildcard subscribers (including their symbolic destination names), if any. See Viewing Physical Destination Information on page 114.
Setting Property Values

The imqcmd create dst command may also optionally include any property values you wish to set for the destination, specified with the -o option. For example, the following command creates a topic destination named hotTopic with a maximum message length of 5000 bytes: imqcmd create dst -t t -n hotTopic -o maxBytesPerMsg=5000
See Chapter 18, Physical Destination Property Reference, for reference information about the physical destination properties that can be set with this option. (For auto-created destinations, you set default property values in the brokers instance configuration file; see Table 173 for information on these properties.)
Destroying Destinations
To destroy a physical destination, use the imqcmd destroy dst subcommand: imqcmd destroy dest -t destType -n destName This purges all messages at the specified destination and removes it from the broker; the operation is not reversible. For example, the following command destroys the queue destination named curlyQueue: imqcmd destroy dest -t q -n curlyQueue -u admin
Note You cannot destroy the dead message queue.
Pausing and Resuming a Physical Destination

Pausing a physical destination temporarily suspends the delivery of messages from producers to the destination, from the destination to consumers, or both. This can be useful, for instance, to prevent destinations from being overwhelmed when messages are being produced much faster than they are consumed. You must also pause a physical destination before compacting it (see Managing Physical Destination Disk Utilization on page 118). To pause the delivery of messages to or from a physical destination, use the imqcmd pause dst subcommand: imqcmd pause dest [-t destType -n destName] [-pst pauseType] If you omit the destination type and name (-t and -n options), all physical destinations will be paused. The pause type (-pst) specifies what type of message delivery to pause: PRODUCERS CONSUMERS ALL Pause delivery from message producers to the destination Pause delivery from the destination to message consumers Pause all message delivery (both producers and consumers)
If no pause type is specified, all message delivery will be paused. For example, the following command pauses delivery from message producers to the queue destination curlyQueue:
imqcmd pause dst -t q -n curlyQueue -pst PRODUCERS -u admin The following command pauses delivery to message consumers from the topic destination hotTopic: imqcmd pause dst -t t -n hotTopic -pst CONSUMERS -u admin This command pauses all message delivery to and from all physical destinations: imqcmd pause dst -u admin
Note In a broker cluster, since each broker in the cluster has its own instance of each physical
destination, you must pause each such instance individually. The imqcmd resume dst subcommand resumes delivery to a paused destination: imqcmd resume dest [-t destType -n destName] For example, the following command resumes message delivery to the queue destination curlyQueue: imqcmd resume dst -t q -n curlyQueue -u admin If no destination type and name are specified, all destinations are resumed. This command resumes delivery to all physical destinations: imqcmd resume dst -u admin
Purging a Physical Destination

Purging a physical destination deletes all messages it is currently holding. You might want to do this when a destinations accumulated messages are taking up too much of the systems resources, such as when a queue is receiving messages but has no registered consumers to which to deliver them, or when a topics durable subscribers remain inactive for long periods of time. To purge a physical destination, use the imqcmd purge dst subcommand: imqcmd purge dst -t destType -n destName For example, the following command purges all accumulated messages from the topic destination hotTopic: imqcmd purge dst -t t -n hotTopic -u admin
Chapter 7 Managing Message Delivery
113
Note In a broker cluster, since each broker in the cluster has its own instance of each physical
destination, you must purge each such instance individually.
Tip When restarting a broker that has been shut down, you can use the Broker utilitys -reset messages option to clear out its stale messages: for example,
imqbrokerd -reset messages -u admin This saves you the trouble of purging physical destinations after restarting the broker.
Updating Physical Destination Properties

The subcommand imqcmd update dst changes the values of specified properties of a physical destination: imqcmd update dst -t destType -n destName -o property1=value1 [ [-o property2=value2] ... ] The properties to be updated can include any of those listed in Table 181 (with the exception of the isLocalOnly property, which cannot be changed once the destination has been created). For example, the following command changes the maxBytesPerMsg property of the queue destination curlyQueue to 1000 and the maxNumMsgs property to 2000: imqcmd update dst -t q -n curlyQueue -u admin -o maxBytesPerMsg=1000 -o maxNumMsgs=2000
Note The type of a physical destination is not an updatable property; you cannot use the imqcmd update dst subcommand to change a queue to a topic or a topic to a queue.
Viewing Physical Destination Information

To list the physical destinations on a broker, use the imqcmd list dst subcommand: imqcmd list dst -b hostName:portNumber [-t destType] [-tmp]
114
This lists all physical destinations on the broker identified by hostName and portNumber of the type (queue or topic) specified by destType. If the -t option is omitted, both queues and topics are listed. For example, the following command lists all physical destinations on the broker running on host myHost at port number 4545: imqcmd list dst -b myHost:4545
Note The list of queue destinations always includes the dead message queue (mq.sys.dmq) in addition to any other queue destinations currently existing on the broker.
If you specify the -tmp option, temporary destinations are listed as well. These are destinations created by clients, normally for the purpose of receiving replies to messages sent to other clients. The imqcmd query dst subcommand displays information about a single physical destination: imq query dst -t destType -n destName For example, the following command displays information about the queue destination curlyQueue: imqcmd query dst -t q -n curlyQueue -u admin
115
Example 73 shows an example of the resulting output. You can use the imqcmd update dst subcommand (see Updating Physical Destination Properties on page 114) to change the value of any of the properties listed.
EXAMPLE 73
Physical Destination Information Listing
-----------------------------------Destination Name Destination Type -----------------------------------large.green.circle Topic On the broker specified by: ------------------------Host Primary Port ------------------------localhost 7676 Destination Name Destination Type Destination State Created Administratively Current Number of Messages Actual Remote Held in Transaction Current Message Bytes Actual Remote Held in Transaction Current Number of Producers Current Number of Producer Wildcards Current Number of Consumers Current Number of Consumer Wildcards large.*.circle (1) Max Max Max Max Number of Messages Total Message Bytes Bytes per Message Number of Producers large.green.circle Topic RUNNING true
0 0 0 0 0 0 0 0 1 1
unlimited (-1) unlimited (-1) unlimited (-1) 100 REJECT_NEWEST 1000 false true false false
Limit Behavior Consumer Flow Limit Is Local Destination Use Dead Message Queue XML schema validation enabled XML schema URI List Reload XML schema on failure
116
For destinations in a broker cluster, it is often helpful to know how many messages in a destination are local (produced to the local broker) and how many are remote (produced to a remote broker). Hence, imqcmd query dst reports, in addition to the number and total message bytes of messages in the destination, the number and total bytes of messages that are sent to the destination from remote brokers in the cluster. For topic destinations, imqcmd query dst reports the number of publishers that are wildcard publishers (including their corresponding symbolic destination names) and the number of subscribers that are wildcard subscribers (including their symbolic destination names), if any. To display metrics information about a physical destination, use the imqcmd metrics dst subcommand: imqcmd metrics dst -t destType -n destName [-m metricType] [-int interval] [-msp numSamples]
The -m option specifies the type of metric information to display:
ttl (default): Messages and packets flowing into and out of the destination and residing in memory rts: Rate of flow of messages and packets into and out of the destination per second, along with other rate information con: Metrics related to message consumers dsk: Disk usage
The -int and -msp options specify, respectively, the interval (in seconds) at which to display the metrics and the number of samples to display in the output. The default values are 5 seconds and an unlimited number of samples. For example, the following command displays cumulative totals for messages and packets handled by the queue destination curlyQueue: imqcmd metrics dst -t q -n curlyQueue -m ttl -u admin
117

EXAMPLE 74
Physical Destination Metrics Listing
----------------------------------------------------------------------------------Msgs Msg Bytes Msg Count Total Msg Bytes (k) Largest In Out In Out Current Peak Avg Current Peak Avg Msg (k) ----------------------------------------------------------------------------------3128 3066 1170102 1122340 128 409 29 46 145 10 < 1 4858 4225 1863159 1635458 144 201 33 53 181 42 < 1 2057 1763 820804 747200 84 377 16 71 122 79 < 1
For a more detailed description of the use of the Command utility to report physical destination metrics, see Physical Destination Metrics on page 407.
Managing Physical Destination Disk Utilization

Because of the way message storage is structured in a file-based persistent data store (see File-Based Persistence Properties on page 128), disk space can become fragmented over time, resulting in inefficient utilization of the available resources. Message Queues Command utility (imqcmd) provides subcommands for monitoring disk utilization by physical destinations and for reclaiming unused disk space when utilization drops. To monitor a physical destinations disk utilization, use the imqcmd metrics dst subcommand: imqcmd metrics dst -m dsk -t destType -n destMame This displays the total number of bytes of disk space reserved for the destinations use, the number of bytes currently in use to hold active messages, and the percentage of available space in use (the disk utilization ratio). For example, the following command displays disk utilization information for the queue destination curlyQueue: imqcmd metrics dst -m dsk -t q -n curlyQueue -u admin
118

EXAMPLE 75
Destination Disk Utilization Listing
-------------------------------------Reserved Used Utilization Ratio -------------------------------------804096 675533 84 1793024 1636222 91 2544640 2243808 88
The disk utilization pattern depends on the characteristics of the messaging application using a particular physical destination. Depending on the flow of messages into and out of the destination and their relative size, the amount of disk space reserved might grow over time. If messages are produced at a higher rate than they are consumed, free records should generally be reused and the utilization ratio should be on the high side. By contrast, if the rate of message production is comparable to or lower than the consumption rate, the utilization ratio will likely be low. As a rule, you want the reserved disk space to stabilize and the utilization ratio to remain high. If the system reaches a steady state in which the amount of reserved disk space remains more or less constant with utilization above 75%, there is generally no need to reclaim unused disk space. If the reserved space stabilizes at a utilization rate below 50%, you can use the imqcmd compact dst subcommand to reclaim the disk space occupied by free records: compact dst [-t destType -n destName] This compacts the file-based data store for the designated physical destination. If no destination type and name are specified, all physical destinations are compacted. You must pause a destination (with the imqcmd pause subcommand) before compacting it, and resume it (with imqcmd resume) afterward (see Pausing and Resuming a Physical Destination on page 112): imqcmd pause dst -t q -n curlyQueue -u admin imqcmd compact dst -t q -n curlyQueue -u admin imqcmd resume dst -t q -n curlyQueue -u admin
Tip If a destinations reserved disk space continues to increase over time, try reconfiguring its
maxNumMsgs, maxBytesPerMsg, maxTotalMsgBytes, and limitBehavior properties (see Physical Destination Properties on page 375).
119
Using the Dead Message Queue

The dead message queue, mq.sys.dmq, is a system-created physical destination that holds the dead messages of a broker's physical destinations. The dead message queue is a tool for monitoring, tuning system efficiency, and troubleshooting. For a definition of the term dead message and a more detailed introduction to the dead message queue, see the Message Queue Technical Overview. The broker automatically creates a dead message queue when it starts. The broker places messages on the queue if it cannot process them or if their time-to-live has expired. In addition, other physical destinations can use the dead message queue to hold discarded messages. This can provide information that is useful for troubleshooting the system.
Managing the Dead Message Queue

The physical destination configuration property useDMQ controls a destinations use of the dead message queue. Physical destinations are configured to use the dead message queue by default; to disable a destination from using it, set the destinations useDMQ property to false: imqcmd update dst -t q -n curlyQueue -o useDMQ=false You can enable or disable the use of the dead message queue for all auto-created physical destinations on a broker by setting the brokers imq.autocreate.destination.useDMQ broker property: imqcmd update bkr -o imq.autocreate.destination.useDMQ=false You can manage the dead message queue with the Message Queue Command utility (imqcmd) just as you manage other queues, but with some differences. For example, because the dead message queue is system-created, you cannot create, pause, or destroy it. Also, as shown in Table 72, default values for the dead message queues configuration properties sometimes differ from those of ordinary queues.
TABLE 72 Property
Dead Message Queue Treatment of Physical Destination Properties

Variant Treatment by Dead Message Queue
maxNumMsgs
Default value is 1000, rather than 1 (unlimited) as for ordinary queues. Default value is 10m (10 megabytes), rather than 1 (unlimited) as for ordinary queues. Default value is REMOVE_OLDEST, rather than REJECT_NEWEST as for ordinary queues. FLOW_CONTROL is not supported for the dead message queue.
maxTotalMsgBytes
limitBehavior
maxNumProducers
Does not apply to the dead message queue.
120
Managing Broker System-Wide Memory
TABLE 72 Property
Dead Message Queue Treatment of Physical Destination Properties

Variant Treatment by Dead Message Queue
(Continued)
isLocalOnly
Permanently set to false in broker clusters; the dead message queue in a cluster is always a global physical destination. Does not apply to the dead message queue.
localDeliveryPreferred
Tip By default, the dead message queue stores entire messages. If you do not plan to restore dead messages, you can reduce the size of the dead message queue by setting the brokers imq.destination.DMQ.truncateBody property to true:
imqcmd update bkr -o imq.destination.DMQ.truncateBody=true This will discard the body of all messages and retain only the headers and property data.
Enabling Dead Message Logging

The broker configuration property logDeadMsgs controls the logging of events related to the dead message queue. When dead message logging is enabled, the broker will log the following events:

A message is moved to the dead message queue. A message is discarded from the dead message queue (or from any physical destination that does not use the dead message queue). A physical destination reaches its limits.
Dead message logging is disabled by default. The following command enables it: imqcmd update bkr -o imq.destination.logDeadMsgs=true
Note Dead message logging applies to all physical destinations that use the dead message queue. You cannot enable or disable logging for an individual physical destination.

Once clients are connected to the broker, the routing and delivery of messages can proceed. In this phase, the broker is responsible for creating and managing different types of physical destinations, ensuring a smooth flow of messages, and using resources efficiently. You can use the broker configuration properties described under Routing and Delivery Properties on page 340 to manage these tasks in a way that suits your applications needs. The performance and stability of a broker depend on the system resources (such as memory) available and how efficiently they are utilized. You can set configuration properties to prevent
the broker from becoming overwhelmed by incoming messages or running out of memory. These properties function at three different levels to keep the message service operating as resources become scarce:
Systemwide message limits apply collectively to all physical destinations on the system. These include the maximum number of messages held by a broker (imq.system.max_count) and the maximum total number of bytes occupied by such messages (imq.system.max_size). If either of these limits is reached, the broker will reject any new messages until the pending messages fall below the limit. There is also a limit on the maximum size of an individual message (imq.message.max_size) and a time interval at which expired messages are reclaimed (imq.message.expiration.interval). Individual destination limits regulate the flow of messages to a specific physical destination. The configuration properties controlling these limits are described in Chapter 18, Physical Destination Property Reference. They include limits on the number and size of messages the destination will hold, the number of message producers and consumers that can be created for it, and the number of messages that can be batched together for delivery to the destination. The destination can be configured to respond to memory limits by slowing down the delivery of message by message producers, by rejecting new incoming messages, or by throwing out the oldest or lowest-priority existing messages. Messages deleted from the destination in this way may optionally be moved to the dead message queue rather than discarded outright; the broker property imq.destination.DMQ.truncateBody controls whether the entire message body is saved in the dead message queue, or only the header and property data. As a convenience during application development and testing, you can configure a message broker to create new physical destinations automatically whenever a message producer or consumer attempts to access a nonexistent destination. The broker properties summarized in Table 173 parallel the ones just described, but apply to such auto-created destinations instead of administratively created ones.
System memory thresholds define levels of memory usage at which the broker takes increasingly serious action to prevent memory overload. Four such usage levels are defined:

Green: Plenty of memory is available. Yellow: Broker memory is beginning to run low. Orange: The broker is low on memory. Red: The broker is out of memory. The memory utilization percentages defining these levels are specified by the broker properties imq.green.threshold, imq.yellow.threshold , imq.orange.threshold, and imq.red.threshold , respectively; the default values are 0% for green, 80% for yellow, 90% for orange, and 98% for red. As memory usage advances from one level to the next, the broker responds progressively, first by swapping messages out of active memory into persistent storage and then by throttling back producers of nonpersistent messages, eventually stopping
122
Managing Durable Subscriptions
the flow of messages into the broker. (Both of these measures degrade broker performance.) The throttling back of message production is done by limiting the size of each batch delivered to the number of messages specified by the properties imq.resourceState .count, where resourceState is green , yellow, orange, or red , respectively. The triggering of these system memory thresholds is a sign that systemwide and destination message limits are set too high. Because the memory thresholds cannot always catch potential memory overloads in time, you should not rely on them to control memory usage, but rather reconfigure the system-wide and destination limits to optimize memory resources.
Managing Durable Subscriptions

Message Queue clients subscribing to a topic destination can register as durable subscribers. The corresponding durable subscription has a unique, persistent identity and requires the broker to retain messages addressed to it even when its message consumer (the durable subscriber) becomes inactive. Ordinarily, the broker may delete a message held for a durable subscriber only when the message expires. The Message Queue Command utility provides subcommands for managing a brokers durable subscriptions in the following ways:

Listing durable subscriptions Purging all messages for a durable subscription Destroying a durable subscription
To list durable subscriptions for a specified physical destination, use the imqcmd list dur subcommand: imqcmd list dur -d topicName For example, the following command lists all durable subscriptions to the topic SPQuotes on the default broker (host localhost at port 7676): imqcmd list dur -d SPQuotes
123
Managing Transactions
The resulting output lists the name of each durable subscription to the topic, the client identifier to which it belongs, its current state (active or inactive), and the number of messages currently queued to it. Example 76 shows an example.
EXAMPLE 76
Durable Subscription Information Listing
Name
Number of Durable Sub Messages State ---------------------------------------------------------------myDurable myClientID 1 INACTIVE
Client ID
The imqcmd purge dur subcommand purges all messages for a specified durable subscriber and client identifier: imqcmd purge dur -n subscriberName -c clientID For example, the following command purges all messages for the durable subscription listed in Example 76: imqcmd purge dur -n myCurable -c myClientID The imqcmd destroy dur subcommand destroys a durable subscription, specified by its subscriber name and client identifier: imqcmd destroy dur -n subscriberName -c clientID For example, the following command destroys the durable subscription listed in Example 76: imqcmd destroy dur -n myCurable -c myClientID
All transactions initiated by client applications are tracked by the broker. These can be local Message Queue transactions or distributed transactions managed by a distributed transaction manager. Each transaction is identified by a unique 64-bit Message Queue transaction identifier. Distributed transactions also have a distributed transaction identifier (XID), up to 128 bytes long, assigned by the distributed transaction manager. Message Queue maintains the association between its own transaction identifiers and the corresponding XIDs. The imqcmd list txn subcommand lists the transactions being tracked by a broker:
imqcmd list txn This lists all transactions on the broker, both local and distributed. For each transaction, it shows the transaction ID, state, user name, number of messages and acknowledgments, and creation time. Example 77 shows an example of the resulting output.
EXAMPLE 77
Broker Transactions Listing
--------------------------------------------------------------Transaction ID State User name # Msgs/ Creation time # Acks --------------------------------------------------------------64248349708800 PREPARED guest 64248371287808 PREPARED guest 4/0 0/4 1/30/02 10:08:31 AM 1/30/02 10:09:55 AM
To display detailed information about a single transaction, obtain the transaction identifier from imqcmd list txn and pass it to the imqcmd query txn subcommand: imqcmd query txn -n transactionID This displays the same information as imqcmd list txn, along with the client identifier, connection identification, and distributed transaction identifier (XID). For example, the command imqcmd query txn -n 64248349708800 produces output like that shown in Example 78.
EXAMPLE 78
Transaction Information Listing
Client ID Connection Creation time Number of acknowledgments Number of messages State Transaction ID User name XID
[email protected]:62209->jms:62195 1/30/02 10:08:31 AM 0 4 PREPARED 64248349708800 guest 6469706F6C7369646577696E6465723130313234313431313030373230
If a broker fails, it is possible that a distributed transaction could be left in the PREPARED state without ever having been committed. Until such a transaction is committed, its messages will not be delivered and its acknowledgments will not be processed. Hence, as an administrator,
you might need to monitor such transactions and commit them or roll them back manually. For example, if the brokers imq.transaction.autorollback property (see Table 172) is set to false, you must manually commit or roll back non-distributed transactions and unrecoverable distributed transactions found in the PREPARED state at broker startup, using the Command utilitys commit txn or rollback txn subcommand: imqcmd commit txn -n transactionID imqcmd rollback txn -n transactionID For example, the following command commits the transaction listed in Example 78: imqcmd commit txn -n64248349708800
Note Only transactions in the PREPARED state can be committed . However, transaction in the STARTED, FAILED, INCOMPLETE, COMPLETE, and PREPARED states can be rolled back. You should do so only if you know that the transaction has been left in this state by a failure and is not in the process of being committed by the distributed transaction manager.
126
C H A P T E R
Configuring Persistence Services
For a broker to recover in case of failure, it needs to re-create the state of its message delivery operations. To do this, the broker must save state information to a persistent data store. When the broker restarts, it uses the saved data to re-create destinations and durable subscriptions, recover persistent messages, roll back open transactions, and rebuild its routing table for undelivered messages. It can then resume message delivery. A persistent data store is thus a key aspect of providing for reliable message delivery. This chapter describes the two different persistence implementations supported by the Message Queue broker and how to set each of them up:

Introduction to Persistence Services on page 127 File-Based Persistence on page 128 JDBC-Based Persistence on page 131 Data Store Formats on page 135
Introduction to Persistence Services

A brokers persistent data store holds information about physical destinations, durable subscriptions, messages, transactions, and acknowledgments. Message Queue supports both file-based and JDBC-based persistence modules, as shown in the following figure. File-based persistence uses individual files to store persistent data; JDBC-based persistence uses the Java Database Connectivity (JDBC) interface to connect the broker to a JDBC-based data store. While file-based persistence is generally faster than JDBC-based persistence, some users prefer the redundancy and administrative control provided by a JDBC database. The broker configuration property imq.persist.store (see Table 174) specifies which of the two persistence modules (file or jdbc) to use.
127
File-Based Persistence
FIGURE 81
Persistent Data Stores
Broker File-based Data Store
JDBC-based Data Store
Message Queue brokers are configured by default to use a file-based persistent store, but you can reconfigure them to plug in any data store accessible through a JDBC-compliant driver. The broker configuration property imq.persist.store (see Table 174) specifies which of the two forms of persistence to use.
By default, Message Queue uses a file-based data store, in which individual files store persistent data (such as messages, destinations, durable subscriptions, transactions, and routing information). The file-based data store is located in a directory identified by the name of the broker instance (instanceName) to which the data store belongs: .../instances/instanceName/fs370 (See Appendix A, Distribution-Specific Locations of Message Queue Data, for the location of the instances directory.) Each destination on the broker has its own subdirectory holding messages delivered to that destination.
Note Because the data store can contain messages of a sensitive or proprietary nature, you
should secure the /instances/instanceName/fs370 directory against unauthorized access; see Securing a File-Based Data Store on page 130.
File-Based Persistence Properties

Broker configuration properties related to file-based persistence are listed under File-Based Persistence Properties on page 346. These properties let you configure various aspects of how the file-based data store behaves.
All persistent data other than messages is stored in separate files: one file each for destinations, durable subscriptions, and transaction state information. Most messages are stored in a single file consisting of variable-size records. You can compact this file to alleviate fragmentation as messages are added and removed (see Managing Physical Destination Disk Utilization on page 118). In addition, messages above a certain threshold size are stored in their own individual files rather than in the variable-sized record file. You can configure this threshold size with the broker property imq.persist.file.message.max_record_size. The broker maintains a file pool for these individual message files: instead of being deleted when it is no longer needed, a file is returned to the pool of free files in its destination directory so that it can later be reused for another message. The broker property imq.persist.file.destination.message.filepool.limit specifies the maximum number of files in the pool. When the number of individual message files for a destination exceeds this limit, files will be deleted when no longer needed instead of being returned to the pool. When returning a file to the file pool, the broker can save time at the expense of storage space by simply tagging the file as available for reuse without deleting its previous contents. You can use the imq.persist.file.message.filepool.cleanratio broker property to specify the percentage of files in each destinations file pool that should be maintained in a clean (empty) state rather than simply marked for reuse. The higher you set this value, the less space will be required for the file pool, but the more overhead will be needed to empty the contents of files when they are returned to the pool. If the brokers imq.persist.file.message.cleanup property is true, all files in the pool will be emptied at broker shutdown, leaving them in a clean state; this conserves storage space but slows down the shutdown process. In writing data to the data store, the operating system has some leeway in whether to write the data synchronously or lazily (asynchronously). Lazy storage can lead to data loss in the event of a system crash, if the broker believes the data to have been written to the data store when it has not. To ensure absolute reliability (at the expense of performance), you can require that all data be written synchronously by setting the broker property imq.persist.file.sync.enabled to true. In this case, the data is guaranteed to be available when the system comes back up after a crash, and the broker can reliably resume operation.
Configuring a File-Based Data Store

A file-based data store is automatically created when you create a broker instance. However, you can configure the data store using the properties described in File-Based Persistence Properties on page 128. For example, by default, Message Queue performs asynchronous write operations to disk. However, to attain the highest reliability, you can set the broker property imq.persist.file.sync to write data synchronously instead. See Table 175. When you start a broker instance, you can use the imqbrokerd commands -- reset option to clear the file-based data store. For more information about this option and its suboptions, see Broker Utility on page 314.
Chapter 8 Configuring Persistence Services 129
Securing a File-Based Data Store

The persistent data store can contain, among other information, message files that are being temporarily stored. Since these messages may contain proprietary information, it is important to secure the data store against unauthorized access. This section describes how to secure data in a file-based data store. A broker using file-based persistence writes persistent data to a flat-file data store whose location is platform-dependent (see Appendix A, Distribution-Specific Locations of Message Queue Data): .../instances/instanceName/fs370 where instanceName is a name identifying the broker instance. This directory is created when the broker instance is started for the first time. The procedure for securing this directory depends on the operating system platform on which the broker is running:
On Solaris and Linux, the directorys permissions are determined by the file mode creation mask (umask) of the user who started the broker instance. Hence, permission to start a broker instance and to read its persistent files can be restricted by setting the mask appropriately. Alternatively, an administrator (superuser) can secure persistent data by setting the permissions on the instances directory to 700. On Windows, the directorys permissions can be set using the mechanisms provided by the Windows operating system. This generally involves opening a Properties dialog for the directory.
Optimizing File-Based Transaction Persistence

Because many activities can occur during a transaction, persisting a transaction's state over the complete life cycle of the transaction can adversely affect overall performance, especially when the imq.persist.file.sync.enabled property is set to true to avoid data loss in case of a system crash. In version 4.4 Update 1, Message Queue provides a new transaction logging mechanism that can improve performance of transaction persistence. This new transaction log offers tuning parameters that can improve performance of file-based persistence for other objects, such as message payloads. To enable this new transaction logging mechanism, set the imq.persist.file.newTxnLogenabled broker property to true. After enabling the new transaction log, essential changes to the state of a JMS transaction are written to the transaction log. When the transaction is committed, all details regarding it are gathered and written to the persistent store. Additionally, the logging mechanism periodically performs a checkpoint operation to ensure that the persistent store and the transaction log are synchronized and that the log size remains manageable.
JDBC-Based Persistence
As a further refinement, the operation of the new logging mechanism is subject to the value of the imq.persist.file.sync.enabled broker property:
When imq.persist.file.sync.enabled is true, write operations to the transaction log are written synchronously to disk. Non-transacted message and non-transacted message acknowledgements are also written synchronously to the transaction log before being written asynchronously to the persistent store. When imq.persist.file.sync.enabled is false, write operations to the transaction log are written asynchronously to disk. Non-transacted message and non-transacted message acknowledgements are not written to the transaction log.
The tuning parameters supported by the new transaction logging mechanism are:

imq.persist.file.txnLog.groupCommit imq.persist.file.txnLog.logNonTransactedMsgSend imq.persist.file.txnLog.logNonTransactedMsgAck
Information about these parameters can be found in Table 176.
Instead of using a file-based data store, you can set up a broker to access any data store accessible through a JDBC-compliant driver. This involves setting the appropriate JDBC-related broker configuration properties and using the Database Manager utility (imqdbmgr) to create the proper database schema. See Configuring a JDBC-Based Data Store on page 133 for specifics.
JDBC-Based Persistence Properties

The full set of properties for configuring a broker to use a JDBC database are listed in Table 177. You can specify these properties either in the instance configuration file (config.properties) of each broker instance or by using the -D command line option to the Broker utility (imqbrokerd) or the Database Manager utility (imqdbmgr). In practice, however, JDBC properties are preconfigured by default, depending on the database vendor being used for the data store. The property values are set in the default.properties file, and only need to be explicitly set if you are overriding the default values. In general, you only need to set the following properties:
imq.persist.store This property specifies that a JDBC-based data store (as opposed to the default file-based data store) is used to store persistent data.
imq.persist.jdbc.dbVendor
131
Chapter 8 Configuring Persistence Services
This property identifies the database vendor being used for the data store; all of the remaining properties are qualified by this vendor name.
imq.persist.jdbc.connection.limit This property specifies the maximum number of connections that can be opened to the database.
imq.persist.jdbcvendorName.user This property specifies the user name to be used by the broker in accessing the database. imq.persist.jdbcvendorName.password This property specifies the password for accessing the database, if required; imq.persist.jdbc.vendorName.needpassword is a boolean flag specifying whether a password is needed. For security reasons, the database access password should be specified only in a password file referenced with the -passfile command line option; if no such password file is specified, the imqbrokerd and imqdbmgr commands will prompt for the password interactively.
imq.persist.jdbc.vendorName.property.propName This set of properties represents any additional, vendor-specific properties that are required. imq.persist.jdbc.vendorName.tableoption Specifies the vendor-specific options passed to the database when creating the table schema.
EXAMPLE 81
Broker Properties for MySQL Database
imq.persist.store=jdbc imq.persist.jdbc.dbVendor=mysql imq.persist.jdbc.mysql.user=userName imq.persist.jdbc.mysql.password=password imq.persist.jdbc.mysql.property.url=jdbc:mysql://hostName:port/dataBase
If you expect to have messages that are larger than 1 MB, configure MySQL's max_allowed_packet variable accordingly when starting the database. For more information see Appendix B of the MySQL 5.0 Reference Manual.
EXAMPLE 82
Broker Properties for HADB Database
imq.persist.store=jdbc imq.persist.jdbc.dbVendor=hadb imq.persist.jdbc.hadb.user=userName imq.persist.jdbc.hadb.password=password imq.persist.jdbc.hadb.property.serverlist=hostName:port,hostName:port,...
You can obtain the server list using the hadbm get jdbcURL command.
132
In addition, in an enhanced broker cluster, in which a JDBC database is shared by multiple broker instances, each broker must be uniquely identified in the database (unnecessary for an embedded database, which stores data for only one broker instance). The configuration property imq.brokerid specifies a unique instance identifier to be appended to the names of database tables for each broker. See Enhanced Broker Cluster Properties on page 177. After setting all of the brokers needed JDBC configuration properties, you must also install your JDBC drivers .jar file in the appropriate directory location, depending on your operating-system platform (as listed in Appendix A, Distribution-Specific Locations of Message Queue Data) and then create the database schema for the JDBC-based data store (see To Set Up a JDBC-Based Data Store on page 133).
Configuring a JDBC-Based Data Store

To configure a broker to use a JDBC database, you set JDBC-related properties in the brokers instance configuration file and create the appropriate database schema. The Message Queue Database Manager utility (imqdbmgr) uses your JDBC driver and the broker configuration properties to create the schema and manage the database. You can also use the Database Manager to delete corrupted tables from the database or if you want to use a different database as a data store. See Database Manager Utility on page 329 for more information.
Note If you use an embedded database, it is best to create it under the following directory: .../instances/instanceName/dbstore/databaseName
If an embedded database is not protected by a user name and password, it is probably protected by file system permissions. To ensure that the database is readable and writable by the broker, the user who runs the broker should be the same user who created the embedded database using the imqdbmgr command.
To Set Up a JDBC-Based Data Store

1
Set JDBC-related properties in the brokers instance configuration file. The relevant properties are discussed, with examples, in JDBC-Based Persistence Properties on page 131 and listed in full in Table 177. In particular, you must specify a JDBC-based data store by setting the brokers imq.persist.store property to jdbc. Place a copy of, or a symbolic link to, your JDBC drivers .jar file in the Message Queue external resource files directory, depending on how Message Queue was installed (see Appendix A, Distribution-Specific Locations of Message Queue Data): IPS packages: IMQ_HOME/lib/ext Solaris SVR4 packages: /usr/share/lib/imq/ext
Chapter 8 Configuring Persistence Services 133
Linux RPM packages: /opt/sun/mq/share/lib/ext For example, if you are using HADB on an IPS package-based installation, the following command copies the drivers .jar file to the appropriate location:
cp /opt/SUNWhadb/4/lib/hadbjdbc4.jar IMQ_HOME/lib/ext
The following command creates a symbolic link instead:

ln -s /opt/SUNWhadb/4/lib/hadbjdbc4.jar IMQ_HOME/lib/ext 3
Create the database schema needed for Message Queue persistence. Use the imqdbmgr create all command (for an embedded database) or the imqdbmgr create tbl command (for an external database); see Database Manager Utility on page 329. a. Change to the directory where the Database Manager utility resides, depending on how Message Queue was installed: IPS packages: cd IMQ_HOME/bin Solaris SVR4 packages: cd /usr/bin Linux RPM packages: cd /opt/sun/mq/bin b. Enter the imqdbmgr command:
imqdbmgr create all
To Display Information About a JDBC-Based Data Store

You can display information about a JDBC-based data store using the Database Manager utility (imqdbmgr) as follows:
1
Change to the directory where the Database Manager utility resides, depending on how Message Queue was installed: IPS packages: cd IMQ_HOME/bin Solaris SVR4 packages: cd /usr/bin Linux RPM packages: cd /opt/sun/mq/bin
Enter the imqdbmgr command:

imqdbmgr query
The output should resemble the following

dbmgr query [04/Oct/2005:15:30:20 PDT] Using plugged-in persistent store: version=400 brokerid=Mozart1756
Data Store Formats
database connection url=jdbc:oracle:thin:@Xhome:1521:mqdb database user=scott Running in standalone mode. Database tables have already been created.
Securing a JDBC-Based Data Store

The persistent data store can contain, among other information, message files that are being temporarily stored. Since these messages may contain proprietary information, it is important to secure the data store against unauthorized access. This section describes how to secure data in a JDBC-based data store. A broker using JDBC-based persistence writes persistent data to a JDBC-compliant database. For a database managed by a database server (such as Oracle), it is recommended that you create a user name and password to access the Message Queue database tables (tables whose names start with MQ). If the database does not allow individual tables to be protected, create a dedicated database to be used only by Message Queue brokers. See the documentation provided by your database vendor for information on how to create user name/password access. The user name and password required to open a database connection by a broker can be provided as broker configuration properties. However it is more secure to provide them as command line options when starting up the broker, using the imqbrokerd commands -dbuserand -dbpassword options (see Broker Utility on page 314). For an embedded database that is accessed directly by the broker by means of the databases JDBC driver, security is usually provided by setting file permissions on the directory where the persistent data will be stored, as described above under Securing a File-Based Data Store on page 130 To ensure that the database is readable and writable by both the broker and the Database Manager utility, however, both should be run by the same user.
Data Store Formats

Changes in the file formats for both file-based and JDBC-based persistent data stores were introduced in Message Queue 3.7, with further JDBC changes in version 4.0 and 4.1. As a result of these changes, the persistent data store version numbers have been updated to 370 for file-based data stores and 410 for JDBC-based stores. You can use the imqdbmgr query command to determine the version number of your existing data store. On first startup, the Message Queue Broker utility (imqbrokerd) will check for the presence of an older persistent data store and automatically migrate it to the latest format:

File-based data store versions 200 and 350 are migrated to the version 370 format. JDBC-based data store versions 350, 370, and 400 are migrated to the version 410 format. (If you need to upgrade a version 200 data store, you will need to step through an intermediate Message Queue 3.5 or 3.6 release.)
135
Chapter 8 Configuring Persistence Services
Data Store Formats
The upgrade leaves the older copy of the persistent data store intact, allowing you to roll back the upgrade if necessary. To do so, you can uninstall the current version of Message Queue and reinstall the earlier version you were previously running. The older versions message brokers will locate and use the older copy of the data store.
136
C H A P T E R
Configuring and Managing Security Services
This chapter describes Message Queues facilities for security-related administration tasks, such as configuring user authentication, defining access control, configuring a Secure Socket Layer (SSL) connection service to encrypt client-broker communication, and setting up a password file for administrator account passwords. In addition to Message Queues own built-in authentication mechanisms, you can also plug in a preferred external service based on the Java Authentication and Authorization Service (JAAS) API. This chapter includes the following sections:

Introduction to Security Services on page 137 User Authentication on page 141 User Authorization on page 155 Message Encryption on page 161 Password Files on page 170 Connecting Through a Firewall on page 171
Introduction to Security Services

Message Queue provides security services for user access control (authentication and authorization) and for encryption:

Authentication ensures that only verified users can establish a connection to a broker. Authorization specifies which users or groups have the right to access resources and to perform specific operations. Encryption protects messages from being tampered with during delivery over a connection.
As a Message Queue administrator, you are responsible for setting up the information the broker needs to authenticate users and authorize their actions. The broker properties pertaining to security services are listed under Security Properties on page 351. The boolean property imq.accesscontrol.enabled acts as a master switch that controls whether access control is
137
applied on a brokerwide basis; for finer control, you can override this setting for a particular connection service by setting the imq.serviceName .accesscontrol.enabled property, where serviceName is the name of the connection service, as shown in Table 61: for example, imq.httpjms.accesscontrol.enabled. The following figure shows the components used by the broker to provide authentication and authorization services. These services depend on a user repository containing information about the users of the messaging system: their names, passwords, and group memberships. In addition, to authorize specific operations for a user or group, the broker consults an access control file that specifies which operations a user or group can perform. You can designate a single access control file for the broker as a whole, using the configuration property imq.accesscontrol.file.filename, or for a single connection service with imq.serviceName. accesscontrol.file.filename.
FIGURE 91
Security Support
Broker Flat File User Repository
Authentication
JAAS Authentication Service
LDAP Server User Repository
Authorization
Access Control Properties File accesscontrol.properties
As Figure 91 shows, you can store user data in a flat file user repository that is provided with the Message Queue service, you can access an existing LDAP repository, or you can plug in a Java Authentication and Authorization Service (JAAS) module.
If you choose a flat-file repository, you must use the imqusermgr utility to manage the repository. This option is easy to use and built-in.
138
If you want to use an existing LDAP server, you use the tools provided by the LDAP vendor to populate and manage the user repository. You must also set properties in the broker instance configuration file to enable the broker to query the LDAP server for information about users and groups. The LDAP option is better if scalability is important or if you need the repository to be shared by different brokers. This might be the case if you are using broker clusters.
If you want to plug-in an existing JAAS authentication service, you need to set the corresponding properties in the broker instance configuration file.
The brokers imq.authentication.basic.user_repository property specifies which type of repository to use. In general, an LDAP repository or JAAS authentication service is preferable if scalability is important or if you need the repository to be shared by different brokers (if you are using broker clusters, for instance). See User Authentication on page 141 for more information on setting up a flat-file user repository, LDAP access, or JAAS authentication service.
Authentication
A client requesting a connection to a broker must supply a user name and password, which the broker compares with those stored in the user repository. Passwords transmitted from client to broker are encoded using either base-64 encoding (for flat-file repositories) or message digest (MD5) hashing (for LDAP repositories). The choice is controlled by the imq.authentication.type property for the broker as a whole, or by imq.serviceName. authentication.type for a specific connection service. The imq.authentication.client.response.timeout property sets a timeout interval for authentication requests. As described under Password Files on page 170, you can choose to put your passwords in a password file instead of being prompted for them interactively. The boolean broker property imq.passfile.enabled controls this option. If this property is true, the imq.passfile.dirpath and imq.passfile.name properties give the directory path and file name for the password file. The imq.imqcmd.password property (which can be embedded in the password file) specifies the password for authenticating an administrative user to use the Command utility (imqcmd) for managing brokers, connection services, connections, physical destinations, durable subscriptions, and transactions. If you are using an LDAP-based user repository, there are a whole range of broker properties available for configuring various aspects of the LDAP lookup. The address (host name and port number) of the LDAP server itself is specified by imq.user_repository.ldap.server. The imq.user_repository.ldap.principal property gives the distinguished name for binding to the LDAP repository, while imq.user_repository.ldap.password supplies the associated password. Other properties specify the directory bases and optional JNDI filters for individual user and group searches, the provider-specific attribute identifiers for user and group names, and so forth; see Security Properties on page 351 for details.
Chapter 9 Configuring and Managing Security Services 139
Authorization
Once authenticated, a user can be authorized to perform various Message Queue-related activities. As a Message Queue administrator, you can define user groups and assign individual users membership in them. The default access control file explicitly refers to only one group, admin (see User Groups and Status on page 141). A user in this group has connection permission for the admin connection service, which allows the user to perform administrative functions such as creating destinations and monitoring and controlling a broker. A user in any other group that you define cannot, by default, get an admin service connection. When a user attempts to perform an operation, the broker checks the users name and group membership (from the user repository) against those specified for access to that operation (in the access control file). The access control file specifies permissions to users or groups for the following operations:

Connecting to a broker Accessing destinations: creating a consumer, a producer, or a queue browser for any given destination or for all destinations Auto-creating destinations
For information on configuring authorization, see User Authorization on page 155
Encryption
To encrypt messages sent between clients and broker, you need to use a connection service based on the Secure Socket Layer (SSL) standard. SSL provides security at the connection level by establishing an encrypted connection between an SSL-enabled broker and client. To use an SSL-based Message Queue connection service, you generate a public/private key pair using the Message Queue Key Tool utility (imqkeytool). This utility embeds the public key in a self-signed certificate and places it in a Message Queue key store. The key store is itself password-protected; to unlock it, you must provide a key store password at startup time, specified by the imq.keystore.password property. Once the key store is unlocked, a broker can pass the certificate to any client requesting a connection. The client then uses the certificate to set up an encrypted connection to the broker. For information on configuring encryption, see Message Encryption on page 161
140
User Authentication
User Authentication
Users attempting to connect to a Message Queue message broker must provide a user name and password for authentication. The broker will grant the connection only if the name and password match those in a broker-specific user repository listing the authorized users and their passwords. Each broker instance can have its own user repository, which you as an administrator are responsible for maintaining. This section tells how to create, populate, and manage the user repository. Message Queue can support any of three types of authentication mechanism:
A flat-file repository that is shipped with Message Queue. This type of repository is very easy to populate and manage, using the Message Queue User Manager utility (imqusermgr). See Using a Flat-File User Repository on page 141. A Lightweight Directory Access Protocol (LDAP) server. This could be a new or existing LDAP directory server using the LDAP v2 or v3 protocol. You use the tools provided by the LDAP vendor to populate and manage the user repository. This type of repository is not as easy to use as the flat-file repository, but it is more scalable and therefore better for production environments. See Using an LDAP User Repository on page 147. An external authentication mechanism plugged into Message Queue by means of the Java Authentication and Authorization Service (JAAS) API. See Using JAAS-Based Authentication on page 150.
Using a Flat-File User Repository

Message Queue provides a built-in flat-file user repository and a command line tool, the User Manager utility (imqusermgr), for populating and managing it. Each broker has its own flat-file user repository, created automatically when you start the broker. The user repository resides in a file named passwd, in a directory identified by the name of the broker instance with which the repository is associated: .../instances/instanceName/etc/passwd (See Appendix A, Distribution-Specific Locations of Message Queue Data, for the exact location of the instances directory, depending on your operating system platform.)
User Groups and Status

Each user in the repository can be assigned to a user group, which defines the default access privileges granted to all of its members. You can then specify authorization rules to further restrict these access privileges for specific users, as described in User Authorization on page 155. A users group is assigned when the user entry is first created, and cannot be changed thereafter. The only way to reassign a user to a different group is to delete the original user entry and add another entry specifying the new group.
User Authentication
The flat-file user repository provides three predefined groups: admin user For broker administrators. By default, users in this group are granted the access privileges needed to configure, administer, and manage message brokers. For normal (non-administrative) client users. Newly created user entries are assigned to this group unless otherwise specified. By default, users in this group can connect to all Message Queue connection services of type NORMAL, produce messages to or consume messages from all physical destinations, and browse messages in any queue. For Message Queue clients that do not wish to use a user name known to the broker (for instance, because they do not know of a real user name to use). This group is analogous to the anonymous account provided by most FTPservers. No more than one user at a time can be assigned to this group. You should restrict the access privileges of this group in comparison to the user group, or remove users from the group at deployment time.
anonymous
You cannot rename or delete these predefined groups or create new ones. In addition to its group, each user entry in the repository has a user status: either active or inactive. New user entries added to the repository are marked active by default. Changing a users status to inactive rescinds all of that users access privileges, making the user unable to open new broker connections. Such inactive entries are retained in the user repository, however, and can be reactivated at a later time. If you attempt to add a new user with the same name as an inactive user already in the repository, the operation will fail; you must either delete the inactive user entry or give the new user a different name. To allow the broker to be used immediately after installation without further intervention by the administrator, the flat-file user repository is created with two initial entries, summarized in Table 91:
The admin entry (user name and password admin/admin) enables you to administer the broker with Command utility (imqcmd) commands. Immediately on installation, you should update this initial entry to change its password (see Changing a Users Password on page 145). The guest entry allows clients to connect to the broker using a default user name and password (guest/guest).
You can then proceed to add any additional user entries you need for individual users of your message service.
142
User Authentication
TABLE 91 User Name
Initial Entries in Flat-File User Repository

Password Group Status
admin guest
admin guest
admin anonymous
Active Active
Using the User Manager Utility

The Message Queue User Manager utility (imqusermgr) enables you to populate or edit a flat-file user repository. SeeUser Manager Utility on page 331 for general reference information about the syntax, subcommands, and options of the imqusermgr command.
User Manager Preliminaries

Before using the User Manager, keep the following things in mind:

The imqusermgr command must be run on the host where the broker is installed. If a broker-specific user repository does not yet exist, you must start up the corresponding broker instance to create it. You must have appropriate permissions to write to the repository; in particular, on Solaris and Linux platforms, you must be logged in as the root user or the user who first created the broker instance.
Subcommands and General Options

Table 92 lists the subcommands of the imqusermgr command. For full reference information about these subcommands, see Table 1615.
TABLE 92
User Manager Subcommands

Description
Subcommand
add delete update list
Add user and password to repository Delete user from repository Set users password or active status (or both) Display user information
The general options listed in Table 93 apply to all subcommands of the imqusermgr command.
Chapter 9 Configuring and Managing Security Services
143
User Authentication
TABLE 93 Option
General User Manager Options

Description
-f -s -v -h
1
Perform action without user confirmation Silent mode (no output displayed) Display version information1 Display usage help1
Any other options specified on the command line are ignored.
Displaying the Product Version

To display the Message Queue product version, use the -v option. For example: imqusermgr -v If you enter an imqusermgr command line containing the -v option in addition to a subcommand or other options, the User Manager utility processes only the -v option. All other items on the command line are ignored.
Displaying Help
To display help on the imqusermgr command, use the -h option, and do not use a subcommand. You cannot get help about specific subcommands. For example, the following command displays help about imqusermgr: imqusermgr -h If you enter an imqusermgr command line containing the -h option in addition to a subcommand or other options, the Command utility processes only the -h option. All other items on the command line are ignored.
Adding a User to the Repository

The subcommand imqusermgr add adds an entry to the user repository, consisting of a user name and password: imqusermgr add [-i brokerName] -u userName -p password [-g group] The -u and -p options specify the user name and password, respectively, for the new entry. These must conform to the following conventions:
All user names and passwords must be at least one character long. Their maximum length is limited only by command shell restrictions on the maximum number of characters that can be entered on a command line.
144
User Authentication
A user name cannot contain an asterisk (*), a comma (,), a colon (:), or a new-line or carriage-return character. If a user name or password contains a space, the entire name or password must be enclosed in quotation marks (" ").
The optional -g option specifies the group (admin, user, or anonymous) to which the new user belongs; if no group is specified, the user is assigned to the user group by default. If the broker name (-i option) is omitted, the default broker imqbroker is assumed. For example, the following command creates a user entry on broker imqbroker for a user named AliBaba, with password Sesame, in the admin group: imqusermgr add -u AliBaba -p Sesame -g admin
Deleting a User From the Repository

The subcommand imqusermgr delete deletes a user entry from the repository: imqusermgr delete [-i brokerName] -u userName The -u option specifies the user name of the entry to be deleted. If the broker name (-i option) is omitted, the default broker imqbroker is assumed. For example, the following command deletes the user named AliBaba from the user repository on broker imqbroker: imqusermgr delete -u AliBaba
Changing a Users Password

You can use the subcommand imqusermgr update to change a users password: imqusermgr update [-i brokerName] -u userName -p password The -u identifies the user; -p specifies the new password. If the broker name (-i option) is omitted, the default broker imqbroker is assumed. For example, the following command changes the password for user AliBaba to Shazam on broker imqbroker: imqusermgr update -u AliBaba -p Shazam
145
User Authentication
Note For the sake of security, you should change the password of the admin user from its initial default value (admin) to one that is known only to you. The following command changes the default administrator password for broker mybroker to veeblefetzer:
imqusermgr update -i mybroker -u admin -p veeblefetzer You can quickly confirm that this change is in effect by running any of the command line tools when the broker is running. For example, the following command will prompt you for a password: imqcmd list svc mybroker -u admin Entering the new password (veeblefetzer) should work; the old password should fail. After changing the password, you should supply the new password whenever you use any of the Message Queue administration tools, including the Administration Console.
Activating or Deactivating a User

The imqusermgr update subcommand can also be used to change a users active status: imqusermgr update [-i brokerName] -u userName -a activeStatus The -u identifies the user; -a is a boolean value specifying the users new status as active (true) or inactive (false). If the broker name (-i option) is omitted, the default broker imqbroker is assumed. For example, the following command sets user AliBabas status to inactive on broker imqbroker: imqusermgr update -u AliBaba -a false This renders AliBabe unable to open new broker connections. You can combine the -p (password) and -a (active status) options in the same imqusermgr update command. The options may appear in either order: for example, both of the following commands activate the user entry for AliBaba and set the password to plugh: imqusermgr update -u AliBaba -p plugh -a true imqusermgr update -u AliBaba -a true -p plugh
Viewing User Information

The imqusermgr list command displays information about a user in the user repository: imqusermgr list [-i brokerName] [-u userName]
User Authentication
The command imqusermgr list -u AliBaba displays information about user AliBabe, as shown in Example 91.
EXAMPLE 91
Viewing Information for a Single User
User repository for broker instance: imqbroker ---------------------------------User Name Group Active State ---------------------------------AliBaba admin true
If you omit the -u option imqusermgr list the command lists information about all users in the repository, as in Example 92.
EXAMPLE 92
Viewing Information for All Users
User repository for broker instance: imqbroker -------------------------------------User Name Group Active State -------------------------------------admin admin true guest anonymous true AliBaba admin true testuser1 user true testuser2 user true testuser3 user true testuser4 user false testuser5 user false
Using an LDAP User Repository

You configure a broker to use an LDAP directory server by setting the values for certain configuration properties in the brokers instance configuration file (config.properties). These properties enable the broker instance to query the LDAP server for information about users and groups when a user attempts to connect to the broker or perform messaging operations.
User Authentication
The imq.authentication.basic.user_repository property specifies the kind of user authentication the broker is to use. By default, this property is set to file, for a flat-file user repository. For LDAP authentication, set it to ldap instead: imq.authentication.basic.user_repository=ldap
The imq.authentication.type property controls the type of encoding used when passing a password between client and broker. By default, this property is set to digest, denoting MD5 encoding, the form used by flat-file user repositories. For LDAP authentication, set it to basic instead: imq.authentication.type=basic This denotes base-64 encoding, the form used by LDAP user repositories.
The following properties control various aspects of LDAP access. See Table 179 for more detailed information: imq.user_repository.ldap.server imq.user_repository.ldap.principal imq.user_repository.ldap.password imq.user_repository.ldap.propertyName imq.user_repository.ldap.base imq.user_repository.ldap.uidattr imq.user_repository.ldap.usrfilter imq.user_repository.ldap.grpsearch imq.user_repository.ldap.grpbase imq.user_repository.ldap.gidattr imq.user_repository.ldap.memattr imq.user_repository.ldap.grpfilter imq.user_repository.ldap.timeout imq.user_repository.ldap.ssl.enabled
The imq.user_repository.ldap.userformat property, if set to a value of dn, specifies that the login username for authentication be in DN username format (for example: uid=mquser,ou=People,dc=red,dc=sun,dc=com). In this case, the broker extracts the value of the imq.user.repository.lpdap.uidatr attribute from the DN username, and uses this value as the user name in access control operations (see User Authorization on page 155). If you want the broker to use a secure, encrypted SSL (Secure Socket Layer) connection for communicating with the LDAP server, set the brokers imq.user_repository.ldap.ssl.enabled property to true imq.user_repository.ldap.ssl.enabled=true and the imq.user_repository.ldap.server property to the port used by the LDAP server for SSL communication: for example, imq.user_repository.ldap.server=myhost:7878
148
User Authentication
You will also need to activate SSL communication in the LDAP server. In addition, you may need to edit the user and group names in the brokers access control file to match those defined in the LDAP user repository; see User Authorization on page 155 for more information. For example, to create administrative users, you use the access control file to specify those users and groups in the LDAP directory that can create ADMIN connections. Any user or group that can create an ADMIN connection can issue administrative commands.
To Set Up an Administrative User

The following procedure makes use of a broker's access control file, which is described in User Authorization on page 155.
1
Enable the use of the access control file by setting the broker property imq.accesscontrol.enabled to true, which is the default value. The imq.accesscontrol.enabled property enables use of the access control file.
Open the access control file, accesscontrol.properties. The location for the file is listed in Appendix A,Distribution-Specific Locations of Message Queue Data The file contains an entry such as the following: service connection access control ################################## connection.NORMAL.allow.user=* connection.ADMIN.allow.group=admin The entries listed are examples. Note that the admin group exists by default in the file-based user repository but does not exist by default in the LDAP directory.
To grant Message Queue administrator privileges to users, enter the user names as follows: connection.ADMIN.allow.user= userName[[,userName2] ] The users must be defined in the LDAP directory.
To grant Message Queue administrator privileges to groups, enter the group names as follows: connection.ADMIN.allow.group= groupName[[,groupName2] ] The groups must be defined in the LDAP directory.
149
User Authentication
Using JAAS-Based Authentication

The Java Authentication and Authorization Service (JAAS) API allows you to plug an external authentication mechanism into Message Queue. This section describes the information that the Message Queue message broker makes available to a JAAS-compliant authentication service and explains how to configure the broker to use such a service. The following sources provide further information on JAAS:
For complete information about the JAAS API, see the JavaTM Authentication and Authorization Service (JAAS) Reference Guide at the URL http://java.sun.com/j2se/1.5.0/docs/guide/security/jaas/ JAASRefGuide.html
For information about writing a JAAS login module, see the JavaTM Authentication and Authorization Service (JAAS) LoginModule Developers Guide at http://java.sun.com/j2se/1.5.0/docs/guide/security/jaas/ JAASLMDevGuide.html
JAAS is a core API in Java 2 Standard Edition (J2SE), and is therefore an integral part of Message Queues runtime environment. It 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.
Note You cannot use the Java Management Extensions (JMX) API to change JAAS-related
broker properties. However, once JAAS-based authentication is configured, JMX client applications (like other clients) can be authenticated using this mechanism.
Elements of JAAS
Figure 92 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 wishing to perform authentication using a JAAS-compliant authentication service. The JAAS client communicates with the authentication service using one or more login modules and is responsible for providing a callback handler that the login module can call to obtain the user name, password, and other information needed for authentication. The JAAS-compliant authentication service consists of one or more login modules along with logic to perform the needed authentication. The login module (LoginModule) may include the authentication logic itself, or it may use a private protocol or API to communicate with an external security service that provides the logic.
150
User Authentication
The JAAS configuration file is a text file that the JAAS client uses to locate the login module(s) to be used.
FIGURE 92
JAAS Elements
JAAS Client LoginContext CallbackHandler
JAAS Configuration File
LoginModule Authentication Service Authentication Logic
External Security Infrastructure
JAAS and Message Queue

Figure 93 shows how JAAS is used by the Message Queue broker. It shows a more complex implementation of the JAAS model shown in Figure 92.
151
User Authentication
FIGURE 93
How Message Queue Uses JAAS
Message Queue Client
Message Queue Broker (JAAS Client) VM LoginContext CallbackHandler
LoginModule1
LoginModule2
(Authentication Logic)
LoginModule3
(Authentication Logic)
Authentication Logic
LDAP Server
RDBMS
Local File System
The authentication service layer, consisting of one or more login modules (if needed) and corresponding authentication logic, is separate from the broker. The login modules run in the same Java virtual machine as the broker. The broker is represented to the login module as a login context, and communicates with the login module by means of a callback handler that is part of the broker runtime code. The authentication service also supplies a JAAS configuration file containing entries that reference the login modules. The configuration file specifies the order in which the login modules (if more than one) are to be used and any conditions for their use. When the broker starts up, it locates the configuration file by consulting either the Java system property java.security.auth.login.config or the Java security properties file. The broker 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 module(s) will be used for authentication. The classes for the login modules are found in the Message Queue external resource files directory, whose location depends on the operating system platform you are using; see Appendix A, Distribution-Specific Locations of Message Queue Data, for details. The relation between the configuration file, the login module, and the broker is shown in the following figure. Figure 94.
152
User Authentication
FIGURE 94
Setting Up JAAS Support
MyJAASCFile.config MyEntry1{ com.some.module.LoginModule1 required debug=true com.some.module.LoginModule2 optional debug=true } Entry point into the configuration file is specified with the broker property imq.user_repository.jaas.name=MyEntry1 LoginModule location is in Message Queue external resource files directory. LoginModule classes are dynamically loaded by the broker.
Configuration file location is specified with the Java system property java.security.auth.login.config or in the Java security properties file.
LoginModule1 .java
CallbackHandler LoginModule communicates with the broker using CallbackHandler. Broker
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 login information to the authentication service, and the service uses the 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 normally would, consulting 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. To set up JAAS support for Message Queue, you perform the following general steps. (These steps assume you are creating your own authentication service.) 1. Create one or more login module classes that implement the authentication service. The JAAS callback types that the broker supports are listed below.
User Authentication
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 pass the value of the following information to the login module (authentication service) when requested through the TextInputCallback.getPrompt() with the following strings:

imq.authentication.type: The broker authentication type in effect at runtime imq.accesscontrol.type: The broker access control type in effect at runtime imq.authentication.clientip: The client IP address (null if unavailable) imq.servicename: The name of the connection service (jms, ssljms, admin, or ssladmin) being used by the client imq.servicetype: The type of the connection service (NORMAL or ADMIN) being used by the client
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 handles this callback to provide logging service 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 logging levels ERROR, INFO, WARNING respectively. 2. Create a JAAS configuration file with entries that reference the login module classes created in Step 1 and specify the location of this file. 3. Note the name of the entry in the JAAS configuration file (that references the login module implementation classes). 4. Archive the classes that implement the login modules to a jar file, and place the jar file in the Message Queue lib/ext directory. 5. Set the broker configuration properties that relate to JAAS support. These are described in Table 94. 6. 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 location when you start the broker. imqbrokerd -Djava.security.auth.login.config=JAAS_Config_File_Location
User Authorization
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 that need to be set to set up JAAS support.
TABLE 94 Property
Broker Properties for JAAS Support

Description
imq.authentication.type
Set to basic to indicate Base-64 password encoding. This is the only permissible value for JAAS authentication. Set to jaas to specify JAAS authentication. 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. 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. 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.
imq.authentication.basic.user_repository imq.user_repository.jaas.name
imq.user_repository.jaas.userPrincipalClass
imq.user_repository.jaas.groupPrincipalClass
User Authorization
An access control file contains rules that specify which users (or groups of users) are authorized to perform certain operations on a message broker. These operations include the following:

Creating a connection Creating a message producer for a physical destination Creating a message consumer for a physical destination Browsing a queue destination Auto-creating a physical destination
155
User Authorization
If access control is enabled (that is, if the brokers imq.accesscontrol.enabled configuration property is set to true, the broker will consult its access control file whenever a client attempts one of these operations, to verify whether the user generating the request (or a group to which the user belongs) is authorized to perform the operation. By editing this file, you can restrict access to these operations to particular users and groups. Changes take effect immediately; there is no need to restart the broker after editing the file.
Access Control File Syntax

Each broker has it own access control file, created automatically when the broker is started. The file is named accesscontrol.properties and is located at a path of the form .../instances/brokerInstanceName/etc/accesscontrol.properties (See Appendix A, Distribution-Specific Locations of Message Queue Data, for the exact location, depending on your platform.) The file is formatted as a Java properties file. It starts with a version property defining the version of the file: version=JMQFileAccessControlModel/100 This is followed by three sections specifying the access control for three categories of operations:

Creating connections Creating message producers or consumers, or browsing a queue destination Auto-creating physical destinations
Each of these sections consists of a sequence of authorization rules specifying which users or groups are authorized to perform which specific operations. These rules have the following syntax: resourceType.resourceVariant.operation.access.principalType=principals Table 95 describes the various elements.
TABLE 95 Element
Authorization Rule Elements

Description
resourceType
Type of resource to which the rule applies: connection: Connections queue: Queue destinations topic: Topic destinations
156
User Authorization
TABLE 95 Element
Authorization Rule Elements

Description
(Continued)
resourceVariant
Specific resource (connection service type or destination) to which the rule applies An asterisk (*) may be used as a wild-card character to denote all resources of a given type: for example, a rule beginning with queue.* applies to all queue destinations.
operation
Operation to which the rule applies This syntax element is not used for resourceType=connection.
access
Level of access authorized: allow: Authorize user to perform operation deny: Prohibit user from performing operation Type of principal (user or group) to which the rule applies: user: Individual user group: User group List of principals (users or groups) to whom the rule applies, separated by commas An asterisk (*) may be used as a wild-card character to denote all users or all groups: for example, a rule ending with user=* applies to all users.
principalType
principals
EXAMPLE 93
Example 1
Rule: queue.q1.consume.allow.user=* Description: allows all users to consume messages from the queue destination q1.
EXAMPLE 94
Example 2
Rule: queue.*.consume.allow.user=Snoopy Description: allows user Snoopy to consume messages from all queue destinations.
EXAMPLE 95
Example 3
Rule: topic.t1.produce.deny.user=Snoopy Description: prevents Snoopy from producing messages to the topic destination t1
157
User Authorization
Note You can use Unicode escape (\\uXXXX) notation to specify non-ASCII user, group, or destination names. If you have edited and saved the access control file with these names in a non-ASCII encoding, you can use the Java native2ascii tool to convert the file to ASCII. See the Java Internationalization FAQ at
http://java.sun.com/j2se/1.4/docs/guide/intl/faq.html for more information.
Application of Authorization Rules

Authorization rules in the access control file are applied according to the following principles:
Any operation not explicitly authorized through an authorization rule is implicitly prohibited. For example, if the access control file contains no authorization rules, all users are denied access to all operations. Authorization rules for specific users override those applying generically to all users. For example, the rules queue.q1.produce.allow.user=* queue.q1.produce.deny.user=Snoopy authorize all users except Snoopy to send messages to queue destination q1.
Authorization rules for a specific user override those for any group to which the user belongs. For example, if user Snoopy is a member of group user, the rules queue.q1.consume.allow.group=user queue.q1.consume.deny.user=Snoopy authorize all members of user except Snoopy to receive messages from queue destination q1.
Authorization rules applying generically to all users override those applying to all groups. For example, the rules topic.t1.produce.deny.group=* topic.t1.produce.allow.user=* authorize all users to publish messages to topic destination t1, overriding the rule denying such access to all groups.
Authorization rules for specific resources override those applying generically to all resources of a given type. For example, the rules topic.*.consume.allow.user=Snoopy topic.t1.consume.deny.user=Snoopy
158
User Authorization
authorize Snoopy to subscribe to all topic destinations except t1.
Authorization rules authorizing and denying access to the same resource and operation for the same user or group cancel each other out, resulting in authorization being denied. For example, the rules queue.q1.browse.deny.user=Snoopy queue.q1.browse.allow.user=Snoopy prevent Snoopy from browsing queue q1. The rules topic.t1.consume.deny.group=user topic.t1.consume.allow.group=user prevent all members of group user from subscribing to topic t1.
When multiple authorization rules are specified for the same resource, operation, and principal type, only the last rule applies. The rules queue.q1.browse.allow.user=Snoopy,Linus queue.q1.browse.allow.user=Snoopy authorize user Snoopy, but not Linus, to browse queue destination q1.
Authorization Rules for Connection Services

Authorization rules with the resource type connection control access to the brokers connection services. The rules resourceVariant element specifies the service type of the connection services to which the rule applies, as shown in Table 61; the only possible values are NORMAL or ADMIN. There is no operation element. The default access control file contains the rules connection.NORMAL.allow.user=* connection.ADMIN.allow.group=admin giving all users access to NORMAL connection services (jms, ssljms, httpjms, and httpsjms) and those in the admin group access to ADMIN connection services (admin and ssladmin). You can then add additional authorization rules to restrict the connection access privileges of specific users: for example, the rule connection.NORMAL.deny.user=Snoopy denies user Snoopy access privileges for connection services of type NORMAL. If you are using a file-based user repository, the admin user group is created by the User Manager utility. If access control is disabled (imq.accesscontrol.enabled = false), all users in the admin group automatically have connection privileges for ADMIN connection services. If access control is enabled, access to these services is controlled by the authorization rules in the access control file.
User Authorization
If you are using an LDAP user repository, you must define your own user groups in the LDAP directory, using the tools provided by your LDAP vendor. You can either define a group named admin, which will then be governed by the default authorization rule shown above, or edit the access control file to refer to one or more other groups that you have defined in the LDAP directory. You must also explicitly enable access control by setting the brokers imq.accesscontrol.enabled property to true.
Authorization Rules for Physical Destinations

Access to specific physical destinations on the broker is controlled by authorization rules with a resource type of queue or topic, as the case may be. These rules regulate access to the following operations:

Sending messages to a queue: produce operation Receiving messages from a queue: consume operation Publishing messages to a topic: produce operation Subscribing to and consuming messages from a topic: consume operation Browsing a queue: browse operation
By default, all users and groups are authorized to perform all of these operations on any physical destination. You can change this by editing the default authorization rules in the access control properties file or overriding them with more specific rules of your own. For example, the rule topic.Admissions.consume.deny.group=user denies all members of the user group the ability to subscribe to the topic Admissions.
Authorization Rules for AutoCreated Physical Destinations

When a client creates a message producer or consumer for a physical destination that does not already exist, the broker will auto-create the destination (provided that the brokers imq.autocreate.queue or imq.autocreate.topic property is set to true). The final section of the access control file controls the ability of users and groups to auto-create destinations, and to access any auto-created destinations. This is governed by authorization rules with a resourceType of queue or topic and an operation element of create. the resourceVariant element is omitted, since these rules apply to all auto-created queues or all auto-created topics, rather than any specific destination. The default access control file contains the rules queue.create.allow.user=* topic.create.allow.user=* authorizing all users to have physical destinations auto-created for them by the broker, and to have access to any auto-created destinations. You can edit the file to restrict such authorization for specific users. For example, the rule
Message Encryption
topic.create.deny.user=Snoopy denies user Snoopy the ability to auto-create topic destinations or to access any auto-created topic destinations.
Note The effect of such auto-creation rules must be congruent with that of other physical
destination access rules. For example, if you change the destination authorization rule to prohibit any user from sending a message to a queue, but enable the auto-creation of queue destinations, the broker will create the physical destination if it does not exist, but will not deliver a message to it.
Message Encryption
This section explains how to set up a connection service based on the Secure Socket Layer (SSL) standard, which enables delivery of encrypted messages over the connection. Message Queue supports the following SSL-based connection services:
The ssljms service delivers secure, encrypted messages between a client and a broker, using the TCP/IP transport protocol. The httpsjms service delivers secure, encrypted messages between a client and a broker, using an HTTPS tunnel servlet with the HTTP transport protocol. The ssladmin service creates a secure, encrypted connection between the Message Queue Command utility (imqcmd) and a broker, using the TCP/IP transport protocol. Encrypted connections are not supported for the Administration Console (imqadmin). The cluster connection service is used internally to provide secure, encrypted communication between brokers in a cluster, using the TCP/IP transport protocol. A JMX connector that supports secure, encrypted communication between a JMX client and a broker's MBean server using the RMI transport protocol over TCP.
The remainder of this section describes how to set up secure connections over TCP/IP, using the ssljms, ssladmin, and cluster connection services. For information on setting up secure connections over HTTP with the httpsjms service, see Appendix C, HTTP/HTTPS Support.
Using Self-Signed Certificates

To use an SSL-based connection service over TCP/IP, you generate a public/private key pair using the Key Tool utility (imqkeytool). This utility embeds the public key in a self-signed certificate that is passed to any client requesting a connection to the broker, and the client uses the certificate to set up an encrypted connection. This section describes how to set up an SSL-based service using such self-signed certificates.
Message Encryption
For a stronger level of authentication, you can use signed certificates verified by a certification authority. The use of signed certificates involves some additional steps beyond those needed for self-signed certificates: you must first perform the procedures described in this section and then perform the additional steps in Using Signed Certificates on page 167. Message Queue's support for SSL with self-signed certificates is oriented toward securing on-the-wire data, on the assumption that the client is communicating with a known and trusted server. Configuring SSL with self-signed certificates requires configuration on both the broker and client:

Setting Up an SSL-Based Connection Service Using Self-Signed Certificates on page 162 Configuring and Running an SSL-Based Client Using Self-Signed Certificates on page 166
Setting Up an SSL-Based Connection Service Using Self-Signed Certificates

The following sequence of procedures are needed to set up an SSL-based connection service for using self-signed certificates:
Note Starting with release 4.0, the default value for the client connection factory property imqSSLIsHostTrusted is false. If your application depends on the prior default value of true, you need to reconfigure and to set the property explicitly to true. In particular, old or new clients using self-signed certificates should set this property to true; for example:
java -DimqConnectionType=TLS -DimqSSLIsHostTrusted=true MyApp The administration tool imqcmd is also affected by this change. In addition to using the secure option to specify that it uses a SSL-based admin connection service, the imqSSLIsHostTrusted should be set to true when connecting to a broker configured with a self-signed certificate. You can do this as follows: imqcmd list svc -secure -DimqSSLIsHostTrusted=true Alternatively, you can import the broker's self-signed certificate into the client runtime trust store. Use the procedure in To Install a Signed Certificate on page 168. 1. Generate a self-signed certificate. 2. Enable the desired SSL-based connection services in the broker. These can include the ssljms, ssladmin, or cluster connection services. 3. Start the broker.
To Generate a Self-Signed Certificate

Run the Key Tool utility (imqkeytool) to generate a self-signed certificate for the broker. (On Solaris and Linux operating systems, you may need to run the utility as the root user in order to
Message Encryption
have permission to create the keystore file.) The same certificate can be used for all SSL-based connection services (ssljms, ssladmin, cluster connection services, and the ssljmxrmi connector).
1
Enter the following at the command prompt: imqkeytool -broker The Key Tool utility prompts you for a key store password:
At the prompt type a keystore password. The Keystore utility prompts you for identifying information from which to construct an X.500 distinguished name. The following table shows the prompts and the values to be provided for each. Values are case-insensitive and can include spaces.
Prompt X.500 Attribute Description Example
What is your first and commonName (CN) last name? What is the name of your organizational unit? What is the name of your organization? organizationalUnit (OU) organizationName (ON)
Fully qualified name of mqserver.sun.com server running the broker Name of department or division Name of larger organization, such as a company or government entity Name of city or locality Full (unabbreviated) name of state or province Standard two-letter country code purchasing
Acme Widgets, Inc.
What is the name of localityName (L) your city or locality? What is the name of your state or province? stateName (ST)
San Francisco
California
What is the two-letter country (C) country code for this unit?
US
The Key Tool utility displays the information you entered for confirmation. For example,
Is CN=mqserver.sun.com, OU=purchasing, ON=Acme Widgets, Inc., L=San Francisco, ST=California, C=US correct? 3
Accept the current values and proceed by typing yes. To reenter values, accept the default or enter no. After you confirm, the utility pauses while it generates a key pair.
Message Encryption
The utility asks for a password to lock the key pair (key password).
4
Press return. This will set the same password for both the key password and the keystore password.
Caution Be sure to remember the password you specify. You must provide this password when you start the broker, to allow the broker to open the keystore file. You can store the keystore password in a password file (see Password Files on page 170).
The Key Tool utility generates a self-signed certificate and places it in Message Queues keystore file. The keystore file is located in a directory whose location depends upon the operating system platform, as shown in Appendix A, Distribution-Specific Locations of Message Queue Data. The following are the configurable properties for the Message Queue keystore for SSL-based connection services: imq.keystore.file.dirpath Path to directory containing keystore file (see Appendix A, Distribution-Specific Locations of Message Queue Data, for default value) Name of key store file Ke store password (to be used only in a password file)
imq.keystore.file.name imq.keystore.password
In some circumstances, you may need to regenerate a key pair in order to solve certain problems: for example, if you forget the key store password or if the SSL-based service fails to initialize when you start a broker and you get the exception: java.security.UnrecoverableKeyException: Cannot recover key (This exception may result if you provided a key password different from the keystore password when you generated the self-signed certificate.)
To Regenerate a Key Pair

1
Remove the brokers keystore file. The file is located as shown in Appendix A, Distribution-Specific Locations of Message Queue Data. Run imqkeytool again. The command will generate a new key pair, as described above.
164
Message Encryption
To Enable an SSL-Based Connection Service in the Broker

To enable an SSL-based connection service in the broker, you need to add the corresponding service or services to the imq.service.activelist property.
1
Open the brokers instance configuration file. The instance configuration file is located in a directory identified by the name of the broker instance (instanceName) with which the configuration file is associated (see Appendix A, Distribution-Specific Locations of Message Queue Data): .../instances/instanceName/props/config.properties Add an entry (if one does not already exist) for the imq.service.activelist property and include the desired SSL-based service(s) in the list. By default, the property includes the jms and admin connection services. Add the SSL-based service or services you wish to activate (ssljms, ssladmin, or both): imq.service.activelist=jms,admin,ssljms,ssladmin
Note The SSL-based cluster connection service is enabled using the imq.cluster.transport
property rather than the imq.service.activelist property (see Cluster Connection Service Properties on page 176). To enable SSL for RMI-based JMX connectors, see SSL-Based JMX Connections on page 454.
3
Save and close the instance configuration file.
To Start the Broker

Start the broker, providing the key store password.
Note When you start a broker or client with SSL, you may notice a sharp increase in CPU usage for a few seconds. This is because the JSSE (Java Secure Socket Extension) method java.security.SecureRandom, which Message Queue uses to generate random numbers, takes a significant amount of time to create the initial random number seed. Once the seed is created, the CPU usage level will drop to normal. 1
Start the broker, providing the keystore password. Put the keystore password in a password file, as described in Password Files on page 170 and set the imq.passfile.enabled property to true. You can now do one of the following:
Pass the location of the password file to the imqbrokerd command: imqbrokerd -passfile /passfileDirectory/passfileName
165
Message Encryption
Start the broker without the -passfile option, but specify the location of the password file using the following two broker configuration properties: imq.passfile.dirpath=/passfileDirectory imq.passfile.name=/passfileName
If you are not using a password file, enter the keystore password at the prompt. imqbrokerd You are prompted for the keystore passwrd.
Configuring and Running an SSL-Based Client Using Self-Signed Certificates

The procedure for configuring a client to use an SSL-based connection service differs depending on whether it is an application client (using the ssljms connection service) or a Message Queue administrative client such as imqcmd (using the ssladmin connection service.)
Application Clients
For application clients, you must make sure the client has the following .jar files specified in its CLASSPATH variable: imq.jar jms.jar Once the CLASSPATH files are properly specified, one way to start the client and connect to the brokers ssljms connection service is by entering a command like the following: java -DimqConnectionType=TLS clientAppName This tells the connection to use an SSL-based connection service.
Administrative Clients
For administrative clients, you can establish a secure connection by including the -secure option when you invoke the imqcmd command: for example, imqcmd list svc -b hostName:portNumber -u userName -secure where userName is a valid ADMIN entry in the Message Queue user repository. The command will prompt you for the password.
166
Message Encryption
Listing the connection services is a way to verify that the ssladmin service is running and that you can successfully make a secure administrative connection, as shown in Example 96.
EXAMPLE 96
Connection Services Listing
Listing all the services on the broker specified by: Host localhost Service Name admin httpjms httpsjms jms ssladmin ssljms Primary Port 7676 Port Number 33984 (dynamic) 33983 (dynamic) 35988 (dynamic) dynamic Service State RUNNING UNKNOWN UNKNOWN RUNNING RUNNING UNKNOWN
Successfully listed services.
Using Signed Certificates

Signed certificates provide a stronger level of server authentication than self-signed certificates. You can implement signed certificates only between a client and broker, and currently not between multiple brokers in a cluster. This requires the following extra procedures in addition to the ones described in Using Self-Signed Certificates on page 161. Using signed certificates requires configuration on both the broker and client:

Obtaining and Installing a Signed Certificate on page 167 Configuring the Client to Require Signed Certificates on page 169
Obtaining and Installing a Signed Certificate

The following procedures explain how to obtain and install a signed certificate.
To Obtain a Signed Certificate

1
Use the J2SE keytool command to generate a certificate signing request (CSR) for the self-signed certificate you generated in the preceding section. Information about the keytool command can be found at http://java.sun.com/j2se/1.5.0/docs/tooldocs/solaris/keytool.html Here is an example:
Message Encryption
keytool -certreq -keyalg RSA -alias imq -file certreq.csr -keystore /etc/imq/keystore -storepass myStorePassword This generates a CSR encapsulating the certificate in the specified file (certreq.csr in the example).
2
Use the CSR to generate or request a signed certificate. You can do this by either of the following methods:
Have the certificate signed by a well known certification authority (CA), such as Thawte or Verisign. See your CAs documentation for more information on how to do this. Sign the certificate yourself, using an SSL signing software package. The resulting signed certificate is a sequence of ASCII characters. If you receive the signed certificate from a CA, it may arrive as an e-mail attachment or in the text of a message.
Save the signed certificate in a file. The instructions below use the example name broker.cer to represent the broker certificate.
To Install a Signed Certificate

1
Check whether J2SE supports your certification authority by default. The following command lists the root CAs in the system key store: keytool -v -list -keystore $JAVA_HOME/lib/security/cacerts If your CA is listed, skip the next step.
If your certification authority is not supported in J2SE, import the CAs root certificate into the Message Queue key store. Here is an example: keytool -import -alias ca -file ca.cer -noprompt -trustcacerts -keystore /etc/imq/keystore -storepass myStorePassword where ca.cer is the file containing the root certificate obtained from the CA. If you are using a CA test certificate, you probably need to import the test CA root certificate. Your CA should have instructions on how to obtain a copy.
Import the signed certificate into the key store to replace the original self-signed certificate. Here is an example: keytool -import -alias imq -file broker.cer -noprompt -trustcacerts -keystore /etc/imq/keystore -storepass myStorePassword where broker.cer is the file containing the signed certificate that you received from the CA. The Message Queue key store now contains a signed certificate to use for SSL connections.
168
Message Encryption
Configuring the Client to Require Signed Certificates

You must now configure the Message Queue client runtime to require signed certificates, and ensure that it trusts the certification authority that signed the certificate.
Note By default, starting with release 4.0, the connection factory object that the client will be using to establish broker connections has its imqSSLIsHostTrusted attribute set to false, meaning that the client runtime will attempt to validate all certificates. Validation will fail if the signer of the certificate is not in the client's trust store.
To Configure the Client Runtime to Require Signed Certificates

1
Verify whether the signing authority is registered in the client's trust store. To test whether the client will accept certificates signed by your certification authority, try to establish an SSL connection, as described above under Configuring and Running an SSL-Based Client Using Self-Signed Certificates on page 166. If the CA is in the client's trust store, the connection will succeed and you can skip the next step. If the connection fails with a certificate validation error, go on to the next step. Install the signing CAs root certificate in the clients trust store. The client searches the key store files cacerts and jssecacerts by default, so no further configuration is necessary if you install the certificate in either of those files. The following example installs a test root certificate from the Verisign certification authority from a file named testrootca.cer into the default system certificate file, cacerts. The example assumes that J2SE is installed in the directory $JAVA_HOME/usr/j2se: keytool -import -keystore /usr/j2se/jre/lib/security/cacerts -alias VerisignTestCA -file testrootca.cer -noprompt -trustcacerts -storepass myStorePassword An alternative (and recommended) option is to install the root certificate into the alternative system certificate file, jssecacerts: keytool -import -keystore /usr/j2se/jre/lib/security/jssecacerts -alias VerisignTestCA -file testrootca.cer -noprompt -trustcacerts -storepass myStorePassword A third possibility is to install the root certificate into some other key store file and configure the client to use that as its trust store. The following example installs into the file /home/smith/.keystore: keytool -import -keystore /home/smith/.keystore -alias VerisignTestCA -file testrootca.cer -noprompt -trustcacerts -storepass myStorePassword
Password Files
Since the client does not search this key store by default, you must explicitly provide its location to the client to use as a trust store. You do this by setting the Java system property javax.net.ssl.trustStore once the client is running: javax.net.ssl.trustStore=/home/smith/.keystore
Password Files
Several types of command require passwords. In Table 96, the first column lists the commands that require passwords and the second column lists the reason that passwords are needed.
TABLE 96 Command
Commands That Use Passwords

Description Purpose of Password
imqbrokerd
Start broker
Access a JDBC-based persistent data store, an SSL certificate key store, or an LDAP user repository Authenticate an administrative user who is authorized to use the command Access the data store
imqcmd
Manage broker Manage JDBC-based data store
imqdbmgr
You can specify these passwords in a password file and use the -passfile option to specify the name of the file. This is the format for the -passfile option: imqbrokerd -passfile filePath
Note In previous versions of Message Queue, you could use the -p, -password, -dbpassword,
and -ldappassword options to specify passwords on the command line. As of Message Queue 4.0, these options are deprecated and are no longer supported; you must use a password file instead.
Security Concerns
Typing a password interactively, in response to a prompt, is the most secure method of specifying a password (provided that your monitor is not visible to other people). You can also specify a password file on the command line. For non-interactive use of commands, however, you must use a password file. A password file is unencrypted, so you must set its permissions to protect it from unauthorized access. Set the permissions so that they limit the users who can view the file, but provide read access to the user who starts the broker.
Connecting Through a Firewall
Password File Contents

A password file is a simple text file containing a set of properties and values. Each value is a password used by a command. Table 97 shows the types of passwords that a password file can contain.
TABLE 97 Password
Passwords in a Password File

Affected Commands Description
imq.imqcmd.password
imqcmd
Administrator password for Message Queue Command utility (authenticated for each command) Key store password for SSL-based services Password for opening a database connection, if required Password associated with the distinguished name assigned to a broker for binding to a configured LDAP user repository
imq.keystore.password imq.persist.jdbc.password
imqbrokerd imqbrokerd imqdbmgr imqbrokerd
imq.user_repository.ldap.password
A sample password file is provided as part of your Message Queue installation; see Appendix A, Distribution-Specific Locations of Message Queue Data, for the location of this file, depending on your platform.
Connecting Through a Firewall

When a client application is separated from the broker by a firewall, special measures are needed in order to establish a connection. One approach is to use the httpjms or httpsjms connection service, which can tunnel through the firewall; see Appendix C, HTTP/HTTPS Support, for details. HTTP connections are slower than other connection services, however; a faster alternative is to bypass the Message Queue Port Mapper and explicitly assign a static port address to the desired connection service, and then open that specific port in the firewall. This approach can be used to connect through a firewall using the jms or ssljms connection service (or, in unusual cases, admin or ssladmin).
TABLE 98
Broker Configuration Properties for Static Port Addresses

Configuration Property
Connection Service
jms ssljms admin
imq.jms.tcp.port imq.ssljms.tls.port imq.admin.tcp.port
171
Audit Logging with the Solaris BSM Audit Log
TABLE 98
Broker Configuration Properties for Static Port Addresses

Configuration Property
(Continued)
Connection Service
ssladmin
imq.ssladmin.tls.port
To Enable Broker Connections Through a Firewall

Assign a static port address to the connection service you wish to use. To bypass the Port Mapper and assign a static port number directly to a connection service, set the broker configuration property imq.serviceName.protocolType.port, where serviceName is the name of the connection service and protocolType is its protocol type (see Table 98). As with all broker configuration properties, you can specify this property either in the broker's instance configuration file or from the command line when starting the broker. For example, to assign port number 10234 to the jms connection service, either include the line imq.jms.tcp.port=10234 in the configuration file or start the broker with the command imqbrokerd -name brokerName -Dimq.jms.tcp.port=10234 where brokerName is the name of the broker to be started.
Configure the firewall to allow connections to the port number you assigned to the connection service. You must also allow connections through the firewall to Message Queue's Port Mapper port (normally 7676, unless you have reassigned it to some other port). In the example above, for instance, you would need to open the firewall for ports 10234 and 7676.

Message Queue supports audit logging. When audit logging is enabled, Message Queue generates a record for the following types of events:

Startup, shutdown, restart, and removal of a broker instance User authentication and authorization Reset of a persistent store Creation, purge, and destruction of a physical destination Administrative destruction of a durable subscriber
Message Queue supports logging audit records to the Message Queuebroker log file and to the Solaris BSM audit log:
To log audit records to the Message Queue broker log file, set the imq.audit.enabled broker property to true . All audit records in the broker log contain the keyword AUDIT.
172
To log audit records to the Solaris BSM audit log, set the imq.audit.bsm.disabled broker property to false .
Note To log audit records to the Solaris BSM audit log, you must run the broker as root, and /usr/lib/audit/Audit.jar must be in the broker classpath.
173
174
10
C H A P T E R
1 0
Configuring and Managing Broker Clusters
Message Queue supports the use of broker clusters: groups of brokers working together to provide message delivery services to clients. Clusters enable a message service to scale its operations to meet an increasing volume of message traffic by distributing client connections among multiple brokers. In addition, clusters provide for message service availability. In the case of a conventional cluster, if a broker fails, clients connected to that broker can reconnect to another broker in the cluster and continue producing and consuming messages. In the case of an enhanced cluster, if a broker fails, clients connected to that broker reconnect to a failover broker that takes over the pending work of the failed broker, delivering messages without interruption of service. See the Chapter 4, Broker Clusters, in Sun GlassFish Message Queue 4.4 Technical Overview for a description of conventional and enhanced broker clusters and how they operate. This chapter describes how to configure and manage both conventional and enhanced broker clusters:

Configuring Broker Clusters on page 175 Managing Broker Clusters on page 182
Configuring Broker Clusters

You create a broker cluster by specifying cluster configuration properties for each of its member brokers. Except where noted in this chapter, cluster configuration properties must be set to the same value for each broker in a cluster. This section introduces these properties and the use of a cluster configuration file to specify them:

The Cluster Configuration File on page 176 Cluster Configuration Properties on page 176 Displaying a Cluster Configuration on page 180
175
The Cluster Configuration File

Like all broker properties, cluster configuration properties can be set individually for each broker in a cluster, either in its instance configuration file (config.properties) or by using the -D option on the command line when you start the broker. However, except where noted in this chapter, each cluster configuration property must be set to the same value for each broker in a cluster. For example, to specify the transport protocol for the cluster connection service, you can include the following property in the instance configuration file for each broker in the cluster: imq.cluster.transport=ssl. If you need to change the value of this property, you must change its value in the instance configuration file for every broker in the cluster. For consistency and ease of maintenance, it is generally more convenient to collect all of the common cluster configuration properties into a central cluster configuration file that all of the individual brokers in a cluster reference. Using a cluster configuration file prevents the settings from getting out of synch and ensures that all brokers in a cluster use the same, consistent cluster configuration information. When using a cluster configuration file, each brokers instance configuration file must point to the location of the cluster configuration file by setting the imq.cluster.url property. For example, imq.cluster.url=file:/home/cluster.properties
Note A cluster configuration file can also include broker properties that are not used specifically for cluster configuration. For example, you can place any broker property in the cluster configuration file that has the same value for all brokers in a cluster. For more information, see Connecting Brokers into a Conventional Cluster on page 182
Cluster Configuration Properties

This section reviews the most important cluster configuration properties, grouped into the following categories:

Cluster Connection Service Properties on page 176 Conventional Broker Cluster Properties on page 177 Enhanced Broker Cluster Properties on page 177
A complete list of cluster configuration properties can be found in Table 1712
Cluster Connection Service Properties

The following properties are used to configure the cluster connection service used for internal communication between brokers in the cluster. These properties are used by both conventional and enhanced clusters.
imq.cluster.transport specifies the transport protocol used by the cluster connection service, such as tcp or ssl. imq.cluster.port specifies the port number for the cluster connection service. You might need to set this property, for instance, to specify a static port number for connecting to the broker through a firewall. imq.cluster.hostname specifies the host name or IP address for the cluster connection service, used for internal communication between brokers in the cluster. The default setting works fine, however, explicitly setting the property can be useful if there is more than one network interface card installed in a computer. If you set the value of this property to localhost, the value will be ignored and the default will be used.
Conventional Broker Cluster Properties

The following properties, in addition to those listed in Cluster Connection Service Properties on page 176, are used to configure conventional clusters:
imq.cluster.brokerlist specifies a list of broker addresses defining the membership of the cluster; all brokers in the cluster must have the same value for this property. For example, to create a conventional cluster consisting of brokers at port 9876 on host1, port 5000 on host2, and the default port (7676) on ctrlhost, use the following value: imq.cluster.brokerlist=host1:9876,host2:5000,ctrlhost
imq.cluster.masterbroker specifies which broker in a conventional cluster is the master broker that maintains the configuration change record that tracks the addition and deletion of destinations and durable subscribers. For example: imq.cluster.masterbroker=host2:5000 While specifying a master broker using the imq.cluster.masterbroker is not mandatory for a conventional cluster to function, it guarantees that persistent information propagated across brokers (destinations and durable subscriptions) is always synchronized. See Conventional Clusters in Sun GlassFish Message Queue 4.4 Technical Overview.
Enhanced Broker Cluster Properties

Enhanced broker clusters, which share a JDBC-based data store, require more configuration than do conventional broker clusters. In addition to the properties listed in Cluster Connection Service Properties on page 176, the following categories of properties are used to configure an enhanced cluster:

Enhanced Clusters: General Configuration Properties on page 178 Enhanced Clusters: JDBC Configuration Properties on page 178 Enhanced Clusters: Failure Detection Properties on page 179
Chapter 10 Configuring and Managing Broker Clusters
177
Enhanced Clusters: General Configuration Properties
imq.cluster.ha is a boolean value that specifies if the cluster is an enhanced cluster (true) or a conventional broker (false). The default value is false. If set to true, mechanisms for failure detection and takeover of a failed broker are enabled. Enhanced clusters are self-configuring: any broker configured to use the clusters shared data store is automatically registered as part of the cluster, without further action on your part. If the conventional cluster property, imq.cluster.brokerlist, is specified for a highavailability broker, the property is ignored and a warning message is logged at broker startup.
imq.persist.store specifies the model for a broker's persistent data store. This property must be set to the value jdbc for every broker in an enhanced cluster. imq.cluster.clusterid specifies the cluster identifier, which will be appended to the names of all database tables in the clusters shared persistent store. The value of this property must be the same for all brokers in a given cluster, but must be unique for each cluster: no two running clusters may have the same cluster identifier. imq.brokerid is a broker identifier that must be unique for each broker in the cluster. Hence, this property must be set in each broker's instance configuration file rather than in a cluster configuration file.
Enhanced Clusters: JDBC Configuration Properties

The persistent data store for an enhanced cluster is maintained on a highly-available JDBC database. The highly-availabile database may be Suns MySQL Cluster Edition or High Availability Session Store (HADB), or it may be an open-source or third-party product such as Oracle Corporations Real Application Clusters (RAC). As described in JDBC-Based Persistence Properties on page 131, the imq.persist.jdbc.dbVendor broker property specifies the name of the database vendor, and all of the remaining JDBC-related properties are qualified with this vendor name. The JDBC-related properties are discussed under JDBC-Based Persistence Properties on page 131 and summarized in Table 177. See the example configurations for MySQL and HADB in Example 81 and Example 82, respectively.
178
Note In setting JDBC-related properties for an enhanced cluster, note the following vendor-specific issues:
MySQL Cluster Edition When using MySQL Cluster Edition as a highly-available database, you must specify the NDB Storage Engine rather than the InnoDB Storage Engine set by Message Queue by default. To specify the NDB Storage Engine, set the following broker property for all brokers in the cluster: imq.persist.jdbc.mysql.tableoption=ENGINE=NDBCLUSTER
HADB When using HADB in a Sun Java Application Server environment, if the integration between Message Queue and Application Server is local (that is, there is a one-to-one relationship between Application Server instances and Message Queue brokers), the Application Server will automatically propagate HADB-related properties to each broker in the cluster. However, if the integration is remote (a single Application Server instance using an externally configured broker cluster), then it is your responsibility to configure the needed HADB properties explicitly.
Enhanced Clusters: Failure Detection Properties

The following configuration properties (listed in Table 1712) specify the parameters for the exchange of heartbeat and status information within an enhanced cluster:
imq.cluster.heartbeat.hostname specifies the host name (or IP address) for the heartbeat connection service. imq.cluster.heartbeat.port specifies the port number for the heartbeat connection service. imq.cluster.heartbeat.interval specifies the interval, in seconds, at which heartbeat packets are transmitted. imq.cluster.heartbeat.threshold specifies the number of missed heartbeat intervals after which a broker is considered suspect of failure. imq.cluster.monitor.interval specifies the interval, in seconds, at which to monitor a suspect brokers state information to determine whether it has failed. imq.cluster.monitor.threshold specifies the number of elapsed monitor intervals after which a suspect broker is considered to have failed.
Smaller values for these heartbeat and monitoring intervals will result in quicker reaction to broker failure, but at the cost of reduced performance and increased likelihood of false suspicions and erroneous failure detection.
179
Displaying a Cluster Configuration

To display information about a clusters configuration, use the Command utilitys list bkr subcommand: imqcmd list bkr This lists the current state of all brokers included in the cluster to which a given broker belongs. The broker states are described in the following table:
TABLE 101 Broker State
Broker States
Meaning
OPERATING TAKEOVER_STARTED
Broker is operating For enhanced clusters, broker has begun taking over persistent data store from another broker For enhanced clusters, broker has finished taking over persistent data store from another broker For enhanced clusters, attempted takeover has failed Broker has begun quiescing Broker has finished quiescing Broker has begun shutting down Broker is down Broker state unknown
TAKEOVER_COMPLETE
TAKEOVER_FAILED QUIESCE_STARTED QUIESCE_COMPLETE SHUTDOWN_STARTED BROKER_DOWN UNKNOWN
The results of the imqcmd list bkr command are shown in Example 101 (for a conventional cluster) and Example 102 (for an enhanced cluster).
180
EXAMPLE 101
Configuration Listing for a Conventional Cluster
Listing all the brokers in the cluster that the following broker is a member of: ------------------------Host Primary Port ------------------------localHost 7676 Cluster Is Highly Available ------------------------Address State --------------------whippet:7676 OPERATING greyhound:7676 OPERATING False
EXAMPLE 102
Configuration Listing for an Enhanced Cluster
Listing all the brokers in the cluster that the following broker is a member of: ---------------------------------------------Host Primary Port Cluster Broker ID ---------------------------------------------localHost 7676 brokerA Cluster ID Cluster Is Highly Available myClusterID True
-------------------------------------------------------------------------------------------------------------ID of broker Time since last Broker ID Address State Msgs in store performing takeover status timestamp -------------------------------------------------------------------------------------------------------------brokerA localhost:7676 OPERATING 121 30 sec brokerB greyhound:7676 TAKEOVER_STARTED 52 brokerA 3 hrs brokerC jpgserv:7676 SHUTDOWN_STARTED 12346 10 sec brokerD icdev:7676 TAKEOVER_COMPLETE 0 brokerA 2 min brokerE mrperf:7676 *unknown 12 0 sec brokerG iclab1:7676 QUIESCING 4 2 sec brokerH iclab2:7676 QUIESCE_COMPLETE 8 5 sec
181
Managing Broker Clusters

The following sections describe how to perform various administrative management tasks for conventional and enhanced clusters, respectively.

Managing Conventional Clusters on page 182 Managing Enhanced Clusters on page 187 Converting a Conventional Cluster to an Enhanced Cluster on page 191
Managing Conventional Clusters

The procedures in this section show how to perform the following tasks for a conventional cluster:

Connecting Brokers into a Conventional Cluster on page 182 Adding Brokers to a Conventional Cluster on page 184 Removing Brokers From a Conventional Cluster on page 185 Managing a Conventional Cluster's Configuration Change Record on page 186
Connecting Brokers into a Conventional Cluster

There are two general methods of connecting brokers into a conventional cluster: from the command line (using the -cluster option) or by setting the imq.cluster.brokerlist property in the cluster configuration file. Whichever method you use, each broker that you start attempts to connect to the other brokers in the cluster every five seconds; the connection will succeed once the master broker is started up (if one is configured). If a broker in the cluster starts before the master broker, it will remain in a suspended state, rejecting client connections, until the master broker starts; the suspended broker then will automatically become fully functional. It is therefore a good idea to start the master broker first and then the others, after the master broker has completed its startup. When connecting brokers into a conventional cluster, you should be aware of the following issues:
Mixed broker versions. A conventional cluster can contain brokers of different versions if all brokers have a version at least as great as that of the master broker. If the cluster is not configured to use a master broker, then all brokers must be of the same version. Matching broker property values. In addition to cluster configuration properties, the following broker properties also must have the same value for all brokers in a cluster:

imq.service.activelist imq.autocreate.queue imq.autocreate.topic imq.autocreate.queue.maxNumActiveConsumers imq.autocreate.queue.maxNumBackupConsumers
182
This restriction is particularly important when a cluster contains mixed broker versions that might contain properties with different default values. For example, If you are clustering a Message Queue version 4.1 or later broker together with those from earlier versions than Message Queue 4.1, you must set the value of the imq.autocreate.queue.maxNumActiveConsumers property, which has different default values before and after version 4.1 (1 and -1, respectively), to be the same. Otherwise the brokers will not be able to establish a cluster connection.
Multiple interface cards. On a multi-homed computer, in which there is more than one network interface card, be sure to explicitly set the network interface to be used by the broker for client connection services (imq.hostname) and for the cluster connection service (imq.cluster.hostname). If imq.cluster.hostname is not set, then connections between brokers might not succeed and as a result, the cluster will not be established. Network loopback IP address. You must make sure that no broker in the cluster is given an address that resolves to the network loopback IP address (127.0.0.1). Any broker configured with this address will be unable to connect to other brokers in the cluster. In particular, some Linux installers automatically set the localhost entry to the network loopback address. On such systems, you must modify the system IP address so that all brokers in the cluster can be addressed properly: For each Linux system participating in the cluster, check the /etc/hosts file as part of cluster setup. If the system uses a static IP address, edit the /etc/hosts file to specify the correct address for localhost. If the address is registered with Domain Name Service (DNS), edit the file DNS lookup is performed before consulting the local hosts file. The line in /etc/nsswitch.conf should read as follows: hosts: dns files/etc/nsswitch.conf to change the order of the entries so that
To Connect Brokers Using a Cluster Configuration File

The method best suited for production systems is to use a cluster configuration file to specify the configuration of the cluster:
1
Create a cluster configuration file that uses the imq.cluster.brokerlist property to specify the list of brokers to be connected. If you are using a master broker, identify it with the imq.cluster.masterbroker property in the configuration file.
For each broker in the cluster, set the imq.cluster.url property in the brokers instance configuration file to point to the cluster configuration file. Use the imqbrokerd command to start each broker. If there is a master broker, start it first, then the others after it has completed its startup.
183
To Connect Brokers from the Command Line

1
If you are using a master broker, start it with the imqbrokerd command, using the -cluster option to specify the complete list of brokers to be included in the cluster. For example, the following command starts the broker as part of a cluster consisting of the brokers running at the default port (7676) on host1, at port 5000 on host2, and at port 9876 on the default host (localhost): imqbrokerd -cluster host1,host2:5000,:9876 Once the master broker (if any) is running, start each of the other brokers in the cluster with the imqbrokerd command, using the same list of brokers with the -cluster option that you used for the master broker. The value specified for the -cluster option must be the same for all brokers in the cluster.
To Establish Secure Connections Between Brokers

If you want secure, encrypted message delivery between brokers in a cluster, configure the cluster connection service to use an SSL-based transport protocol:
1
For each broker in the cluster, set up SSL-based connection services, as described in Message Encryptionon page 161. Set each brokers imq.cluster.transport property to ssl, either in the cluster configuration file or individually for each broker.
Adding Brokers to a Conventional Cluster

The procedure for adding a new broker to a conventional cluster depends on whether the cluster uses a cluster configuration file.
To Add a New Broker to a Conventional Cluster Using a Cluster
Configuration File
1 2
Add the new broker to the imq.cluster.brokerlist property in the cluster configuration file. Issue the following command to any broker in the cluster: imqcmd reload cls This forces each broker to reload the imq.cluster.brokerlist property. It is not necessary to issue this command to every broker in the cluster; executing it for any one broker will cause all of them to reload the cluster configuration.
(Optional) Set the value of the imq.cluster.url property in the new brokers instance configuration file (config.properties) to point to the cluster configuration file.
184
Start the new broker. If you did not perform step 3, use the -D option on the imqbrokerd command line to set the value of imq.cluster.url to the location of the cluster configuration file.
To Add a New Broker to a Conventional Cluster Without a Cluster
Configuration File
1
(Optional) Set the values of the following properties in the new brokers instance configuration file (config.properties) : imq.cluster.brokerlist imq.cluster.masterbroker (if necessary) imq.cluster.transport (if you are using a secure cluster connection service) When the newly added broker starts, it connects and exchanges data with all the other brokers in the imq.cluster.brokerlist value.
Modify the imq.cluster.brokerlist property of other brokers in the cluster to include the new broker. This step is not strictly necessary to add a broker to a functioning cluster. However, should any broker need to be restarted, its imq.cluster.brokerlist value must include all other brokers in the cluster, including the newly added broker. Start the new broker. If you did not perform step 1, use the -D option on the imqbrokerd command line to set the property values listed there.
Removing Brokers From a Conventional Cluster

The method you use to remove a broker from a conventional cluster depends on whether you originally created the cluster using a cluster configuration file or by means of command line options.
To Remove a Broker From a Conventional Cluster Using a Cluster
Configuration File
If you originally created a cluster by specifying its member brokers with the imq.cluster.brokerlist property in a central cluster configuration file, it isnt necessary to stop the brokers in order to remove one of them. Instead, you can simply edit the configuration file to exclude the broker you want to remove, force the remaining cluster members to reload the cluster configuration, and reconfigure the excluded broker so that it no longer points to the same cluster configuration file:
1
Edit the cluster configuration file to remove the excluded broker from the list specified for the imq.cluster.brokerlist property.
Chapter 10 Configuring and Managing Broker Clusters 185
Issue the following command to each broker remaining in the cluster: imqcmd reload cls This forces the brokers to reload the cluster configuration.
3 4
Stop the broker youre removing from the cluster. Edit that brokers instance configuration file (config.properties), removing or specifying a different value for its imq.cluster.url property.
To Remove a Broker From a Conventional Cluster Using the Command
Line
If you used the imqbrokerd command from the command line to connect the brokers into a cluster, you must stop each of the brokers and then restart them, specifying the new set of cluster members on the command line:
1 2
Stop each broker in the cluster, using the imqcmd command. Restart the brokers that will remain in the cluster, using the imqbrokerd commands -cluster option to specify only those remaining brokers. For example, suppose you originally created a cluster consisting of brokers A, B, and C by starting each of the three with the command imqbrokerd -cluster A,B,C To remove broker A from the cluster, restart brokers B and C with the command imqbrokerd -cluster B,C
Managing a Conventional Cluster's Configuration Change Record

As noted earlier, a conventional cluster can optionally have one master broker, which maintains a configuration change record to keep track of any changes in the clusters persistent state. The master broker is identified by the imq.cluster.masterbroker configuration property, either in the cluster configuration file or in the instance configuration files of the individual brokers. Because of the important information that the configuration change record contains, it is important to back it up regularly so that it can be restored in case of failure. Although restoring from a backup will lose any changes in the clusters persistent state that have occurred since the backup was made, frequent backups can minimize this potential loss of information. The backup and restore operations also have the positive effect of compressing and optimizing the change history contained in the configuration change record, which can grow significantly over time.
To Back Up the Configuration Change Record
Use the -backup option of the imqbrokerd command, specifying the name of the backup file. For example: imqbrokerd -backup mybackuplog
To Restore the Configuration Change Record

1 2
Shut down all brokers in the cluster. Restore the master brokers configuration change record from the backup file. The command is imqbrokerd -restore mybackuplog
If you assign a new name or port number to the master broker, update the imq.cluster.brokerlist and imq.cluster.masterbroker properties accordingly in the cluster configuration file. Restart all brokers in the cluster.
Managing Enhanced Clusters

This section presents step-by-step procedures for performing a variety of administrative tasks for an enhanced cluster:

Connecting Brokers into an Enhanced Cluster on page 187 Adding and Removing Brokers in an Enhanced Cluster on page 190 Preventing or Forcing Broker Failover on page 190 Backing up a Shared Data Store on page 191
Connecting Brokers into an Enhanced Cluster

Because enhanced clusters are self-configuring, there is no need to explicitly specify the list of brokers to be included in the cluster. Instead, all that is needed is to set each brokers configuration properties appropriately and then start the broker; as long as its properties are set properly, it will automatically be incorporated into the cluster. Enhanced Broker Cluster Properties on page 177 describes the required properties, which include vendor-specific JDBC database properties.
187
Note In addition to creating an enhanced cluster as described in this section, you must also configure clients to successfully reconnect to a failover broker in the event of broker or connection failure. You do this by setting the imqReconnectAttempts connection factory attribute to a value of -1.
The property values needed for brokers in an enhanced cluster can be set separately in each brokers instance configuration file, or they can be specified in a cluster configuration file that all the brokers reference. The procedures are as follows:
To Connect Brokers Using a Cluster Configuration File

The method best suited for production systems is to use a cluster configuration file to specify the configuration of the cluster.
1
Create a cluster configuration file specifying the clusters high-availability-related configuration properties. Enhanced Broker Cluster Properties on page 177 shows the required property values. However, do not include the imq.brokerid property in the cluster configuration file; this must be specified separately for each individual broker in the cluster.
Specify any additional, vendor-specific JDBC configuration properties that might be needed. The vendor-specific properties required for MySQL and HADB are shown in Example 81 and Example 82, respectively.
For each broker in the cluster: a. Start the broker at least once, using the imqbrokerd command. The first time a broker instance is run, an instance configuration file (config.properties) is automatically created. b. Shut down the broker. Use the imqcmd shutdown bkr command. c. Edit the instance configuration file to specify the location of the cluster configuration file. In the brokers instance configuration file, set the imq.cluster.url property to point to the location of the cluster configuration file you created in step 1. d. Specify the broker identifier. Set the imq.brokerid property in the instance configuration file to the brokers unique broker identifier. This value must be different for each broker.
188
Place a copy of, or a symbolic link to, your JDBC drivers .jar file in the Message Queue external resource files directory , depending on how Message Queue was installed (see Appendix A, Distribution-Specific Locations of Message Queue Data): IPS packages: IMQ_HOME/lib/ext Solaris SVR4 packages: /usr/share/lib/imq/ext Linux RPM packages: /opt/sun/mq/share/lib/ext
Create the database schema needed for Message Queue persistence. Use the imqdbmgr create tbl command; see Database Manager Utility on page 329.
Restart each broker with the imqbrokerd command. The brokers will automatically register themselves into the cluster on startup.
To Connect Brokers Using Instance Configuration Files

1
For each broker in the cluster: a. Start the broker at least once, using the imqbrokerd command. The first time a broker instance is run, an instance configuration file (config.properties) is automatically created. b. Shut down the broker. Use the imqcmd shutdown bkr command. c. Edit the instance configuration file to specify the brokers high-availability-related configuration properties. Enhanced Broker Cluster Properties on page 177 shows the required property values. Be sure to set the brokerid property uniquely for each broker. d. Specify any additional, vendor-specific JDBC configuration properties that might be needed. The vendor-specific properties required for MySQL and HADB are shown in Example 81 and Example 82, respectively.
Place a copy of, or a symbolic link to, your JDBC drivers .jar file in the Message Queue external resource files directory, depending on how Message Queue was installed (see Appendix A, Distribution-Specific Locations of Message Queue Data): IPS packages: IMQ_HOME/lib/ext Solaris SVR4 packages: /usr/share/lib/imq/ext Linux RPM packages: /opt/sun/mq/share/lib/ext
Create the database schema needed for Message Queue persistence. Use the imqdbmgr create tbl command; see Database Manager Utility on page 329. Restart each broker with the imqbrokerd command. The brokers will automatically register themselves into the cluster on startup.
Adding and Removing Brokers in an Enhanced Cluster

Because enhanced clusters are self-configuring, the procedures for adding and removing brokers are simpler than for a conventional cluster.
To Add a New Broker to an Enhanced Cluster

1
Set the new brokers high-availability-related properties, as described in the preceding section. You can do this either by specifying the individual properties in the brokers instance configuration file (config.properties) or, if there is a cluster configuration file, by setting the brokers imq.cluster.url property to point to it. Start the new broker with the imqbrokerd command. The broker will automatically register itself into the cluster on startup.
To Remove a Broker from an Enhanced Cluster

1
Make sure the broker is not running. If necessary, use the command imqcmd shutdown bkr to shut down the broker.
Remove the broker from the cluster with the command imqdbmgr remove bkr This command deletes all database tables for the corresponding broker.
Preventing or Forcing Broker Failover

Although the takeover of a failed brokers persistent data by a failover broker in an enhanced cluster is normally automatic, there may be times when you want to prevent such failover from occurring. To suppress automatic failover when shutting down a broker, use the -nofailover option to the imqcmd shutdown bkr subcommand: imqcmd shutdown bkr -nofailover -b hostName:portNumber where hostName and portNumber are the host name and port number of the broker to be shut down.
Conversely, you may sometimes need to force a broker failover to occur manually. (This might be necessary, for instance, if a failover broker were to itself fail before completing the takeover process.) In such cases, you can initiate a failover manually from the command line: first shut down the broker to be taken over with the -nofailover option, as shown above, then issue the command imqcmd takeover bkr -n brokerID where brokerID is the broker identifier of the broker to be taken over. If the specified broker appears to be running, the Command utility will display a confirmation message: The broker associated with brokerID last accessed the database # seconds ago. Do you want to take over for this broker? You can suppress this message, and force the takeover to occur unconditionally, by using the -f option to the imqcmd takeover bkr command: imqcmd takeover bkr -f -n brokerID
Note The imqcmd takeover bkr subcommand is intended only for use in failed-takeover
situations. You should use it only as a last resort, and not as a general way of forcibly taking over a running broker.
Backing up a Shared Data Store

For durability and reliability, it is a good idea to back up an enhanced clusters shared data store periodically to backup files. This creates a snapshot of the data store that you can then use to restore the data in case of catastrophic failure. The command for backing up the data store is imqdbmgr backup -dir backupDir where backupDir is the path to the directory in which to place the backup files. To restore the data store from these files, use the command imqdbmgr restore -restore backupDir
Converting a Conventional Cluster to an Enhanced Cluster

The best approach to converting a conventional broker cluster to an enhanced broker cluster is to drain your messaging system of all persistent data before attempting the conversion. This lets you create a new shared data store without worrying about loss of data. However, if you are using individual JDBC-based data stores for your brokers, a utility is available for converting a standalone datastore to a shared data store.
Cluster Conversion : File-Based Data Store

If the brokers in your conventional cluster are using file-based data stores, use the following procedure to convert to an enhanced cluster.
1
Drain down your messaging system of all persistent data. Stop all producer clients from producing messages, and wait for all messages in the system to be consumed. Shut down all client applications. Shut down all brokers in the conventional cluster. Reconfigure all brokers for an enhanced cluster. See Enhanced Broker Cluster Properties on page 177. It is recommended that you use a cluster configuration file to specify cluster configuration property values, such as the imq.cluster.clusterid, imq.persist.store, and additional shared JDBC database properties. Start all brokers in the enhanced cluster. See Connecting Brokers into an Enhanced Cluster on page 187. Configure client applications to re-connect to failover brokers. Client re-connection behavior is specified by connection handling attributes of the connection factory administered objects (see the Connection Handling on page 381). In the case of enhanced broker clusters, the imqAddressList, imqAddressListBehavior, and imqAddressListIterations attributes are ignored, however the imqReconnectAttempts attribute should be set to a value of -1 (unlimited). Start all client applications. Resume messaging operations
2 3 4
7 8
Cluster Conversion: JDBC-Based Data Store

If the brokers in your conventional cluster are using JDBC-based data stores, use the following procedure to convert to an enhanced cluster. The procedure assumes that individual standalone broker data stores reside on the same JDBC database server.
1
Back up all persistent data in the standalone JDBC-based data store of each broker. Use proprietary JDBC database tools.
2
192
Shut down all client applications.

3 4
Shut down all brokers in the conventional cluster. Convert each standalone data store to a shared data store. Use the Message Queue Database Manager utility (imqdbmgr) subcommand imqdbmgr upgrade hastore to convert an existing standalone JDBC database to a shared JDBC database.
Reconfigure all brokers for an enhanced cluster. See Enhanced Broker Cluster Properties on page 177. It is recommended that you use a cluster configuration file to specify cluster configuration property values, such as the imq.cluster.clusterid, imq.persist.store, and additional shared JDBC database properties. Start all brokers in the enhanced cluster. See Connecting Brokers into an Enhanced Cluster on page 187. Configure client applications to re-connect to failover brokers. Client re-connection behavior is specified by connection handling attributes of the connection factory administered objects (see the Connection Handling on page 381). In the case of enhanced broker clusters, the imqAddressList, imqAddressListBehavior, and imqAddressListIterations attributes are ignored, however the imqReconnectAttempts attribute should be set to a value of -1 (unlimited). Start all client applications. Resume messaging operations.
8 9
193
194
11
C H A P T E R
1 1
Managing Administered Objects
Administered objects encapsulate provider-specific configuration and naming information, enabling the development of client applications that are portable from one JMS provider to another. A Message Queue administrator typically creates administered objects for client applications to use in obtaining broker connections for sending and receiving messages. This chapter tells how to use the Object Manager utility (imqobjmgr) to create and manage administered objects. It contains the following sections:

Object Stores on page 195 Administered Object Attributes on page 198 Using the Object Manager Utility on page 205
Object Stores
Administered objects are placed in a readily available object store where they can be accessed by client applications by means of the Java Naming and Directory Interface (JNDI). There are two types of object store you can use: a standard Lightweight Directory Access Protocol (LDAP) directory server or a directory in the local file system.
LDAP Server Object Stores

An LDAP server is the recommended object store for production messaging systems. LDAP servers are designed for use in distributed systems and provide security features that are useful in production environments. LDAP implementations are available from a number of vendors. To manage an object store on an LDAP server with Message Queue administration tools, you may first need to configure the server to store Java objects and perform JNDI lookups; see the documentation provided with your LDAP implementation for details.
195
Object Stores
To use an LDAP server as your object store, you must specify the attributes shown in Table 111. These attributes fall into the following categories:
Initial context. The java.naming.factory.initial attribute specifies the initial context for JNDI lookups on the server. The value of this attribute is fixed for a given LDAP object store. Location. The java.naming.provider.url attribute specifies the URL and directory path for the LDAP server. You must verify that the specified directory path exists. Security. The java.naming.security.principal, java.naming.security.credentials, and java.naming.security.authentication attributes govern the authentication of callers attempting to access the object store. The exact format and values of these attributes depend on the LDAP service provider; see the documentation provided with your LDAP implementation for details and to determine whether security information is required on all operations or only on those that change the stored data.
TABLE 111 Attribute
LDAP Object Store Attributes

Description
java.naming.factory.initial
Initial context for JNDI lookup Example: com.sun.jndi.ldap.LdapCtxFactory
java.naming.provider.url
Server URL and directory path Example: ldap://myD.com:389/ou=mq1,o=App where administered objects are stored in the directory /App/mq1.
java.naming.security.principal
Identity of the principal for authenticating callers The format of this attribute depends on the authentication scheme: for example, uid=homerSimpson,ou=People,o=mq If this attribute is unspecified, the behavior is determined by the LDAP service provider.
java.naming.security.credentials
Credentials of the authentication principal The value of this attribute depends on the authentication scheme: for example, it might be a hashed password, a clear-text password, a key, or a certificate. If this property is unspecified, the behavior is determined by the LDAP service provider.
196
Object Stores
TABLE 111 Attribute
LDAP Object Store Attributes
(Continued)
Description
java.naming.security.authentication
Security level for authentication: none: No security simple: Simple security strong: Strong security For example, if you specify simple, you will be prompted for any missing principal or credential values. This will allow you a more secure way of providing identifying information. If this property is unspecified, the behavior is determined by the LDAP service provider.
File-System Object Stores

Message Queue also supports the use of a directory in the local file system as an object store for administered objects. While this approach is not recommended for production systems, it has the advantage of being very easy to use in development environments. Note, however, that for a directory to be used as a centralized object store for clients deployed across multiple computer nodes, all of those clients must have access to the directory. In addition, any user with access to the directory can use Message Queue administration tools to create and manage administered objects. To use a file-system directory as your object store, you must specify the attributes shown in Table 112. These attributes have the same general meanings described above for LDAP object stores; in particular, the java.naming.provider.url attribute specifies the directory path of the directory holding the object store. This directory must exist and have the proper access permissions for the user of Message Queue administration tools as well as the users of the client applications that will access the store.
TABLE 112 Attribute
File-system Object Store Attributes

Description
java.naming.factory.initial
Initial context for JNDI lookup Example: com.sun.jndi.fscontext.RefFSContextFactory
java.naming.provider.url
Directory path Example: file:///C:/myapp/mqobjs
Chapter 11 Managing Administered Objects
197
Administered Object Attributes

Message Queue administered objects are of two basic kinds:

Connection factories are used by client applications to create connections to brokers. Destinations represent locations on a broker with which client applications can exchange (send and retrieve) messages.
Each type of administered object has certain attributes that determine the objects properties and behavior. This section describes how to use the Object Manager command line utility (imqobjmgr) to set these attributes; you can also set them with the GUI Administration Console, as described in Working With Administered Objects on page 58.
Connection Factory Attributes

Client applications use connection factory administered objects to create connections with which to exchange messages with a broker. A connection factorys attributes define the properties of all connections it creates. Once a connection has been created, its properties cannot be changed; thus the only way to configure a connections properties is by setting the attributes of the connection factory used to create it. Message Queue defines two classes of connection factory objects:

ConnectionFactory objects support normal messaging and nondistributed transactions. XAConnectionFactory objects support distributed transactions.
Both classes share the same configuration attributes, which you can use to optimize resources, performance, and message throughput. These attributes are listed and described in detail in Chapter 19, Administered Object Attribute Reference, and are discussed in the following sections below:

Connection Handling on page 198 Client Identification on page 201 Reliability And Flow Control on page 203 Queue Browser and Server Sessions on page 204 Standard Message Properties on page 204 Message Header Overrides on page 204
Connection Handling
Connection handling attributes specify the broker address to which to connect and, if required, how to detect connection failure and attempt reconnection. They are summarized in Table 191.
Broker Address List

The most important connection handling attribute is imqAddressList, which specifies the broker or brokers to which to establish a connection. The value of this attribute is a string containing a broker address or (in the case of a broker cluster) multiple addresses separated by commas. Broker addresses can use a variety of addressing schemes, depending on the connection service to be used (see Configuring Connection Services on page 95) and the method of establishing a connection:
mq uses the brokers Port Mapper to assign a port dynamically for either the jms or ssljms connection service. mqtcp bypasses the Port Mapper and connects directly to a specified port, using the jms connection service. mqssl makes a Secure Socket Layer (SSL) connection to a specified port, using the ssljms connection service. http makes a Hypertext Transport Protocol (HTTP) connection to a Message Queue tunnel servlet at a specified URL, using the httpjms connection service. https makes a Secure Hypertext Transport Protocol (HTTPS) connection to a Message Queue tunnel servlet at a specified URL, using the httpsjms connection service.
These addressing schemes are summarized in Table 192. The general format for each broker address is scheme://address where scheme is one of the addressing schemes listed above and address denotes the broker address itself. The exact syntax for specifying the address varies depending on the addressing scheme, as shown in the Description column of Table 192. Table 193 shows examples of the various address formats. In a multiple-broker cluster environment, the address list can contain more than one broker address. If the first connection attempt fails, the Message Queue client runtime will attempt to connect to another address in the list, and so on until the list is exhausted. Two additional connection factory attributes control the way this is done:
imqAddressListBehavior specifies the order in which to try the specified addresses. If this attribute is set to the string PRIORITY, addresses will be tried in the order in which they appear in the address list. If the attribute value is RANDOM, the addresses will instead be tried in random order; this is useful, for instance, when many Message Queue clients are sharing the same connection factory object, to prevent them from all attempting to connect to the same broker address. imqAddressListIterations specifies how many times to cycle through the list before giving up and reporting failure. A value of 1 denotes an unlimited number of iterations: the client runtime will keep trying until it succeeds in establishing a connection or until the end of time, whichever occurs first.
199
Note Because enhanced clusters are self-configuring (see Cluster Configuration Properties on page 176 and Connecting Brokers into an Enhanced Cluster on page 187), their membership can change over time as brokers enter and leave the cluster. In this type of cluster, the value of each member brokers imqAddressList attribute is updated dynamically so that it always reflects the clusters current membership.
Automatic Reconnection
By setting certain connection factory attributes, you can configure a client to reconnect automatically to a broker in the event of a failed connection. For standalone brokers or those belonging to a conventional broker cluster (see Conventional Clusters in Sun GlassFish Message Queue 4.4 Technical Overview), you enable this behavior by setting the connection factorys imqReconnectEnabled attribute to true. The imqReconnectAttempts attribute controls the number of reconnection attempts to a given broker address; imqReconnectInterval specifies the interval, in milliseconds, to wait between attempts. If the broker is part of a conventional cluster, the failed connection can be restored not only on the original broker, but also on a different one in the cluster. If reconnection to the original broker fails, the client runtime will try the other addresses in the connection factorys broker address list (imqAddressList). The imqAddressListBehavior and imqAddressListIterations attributes control the order in which addresses are tried and the number of iterations through the list, as described in the preceding section. Each address is tried repeatedly at intervals of imqReconnectInterval milliseconds, up to the maximum number of attempts specified by imqReconnectAttempts. Note, however, that in a conventional cluster, such automatic reconnection only provides connection failover and not data failover: persistent messages and other state information held by a failed or disconnected broker can be lost when the client is reconnected to a different broker instance. While attempting to reestablish a connection, Message Queue does maintain objects (such as sessions, message consumers, and message producers) provided by the client runtime. Temporary destinations are also maintained for a time when a connection fails, because clients might reconnect and access them again; after giving clients time to reconnect and use these destinations, the broker will delete them. In circumstances where the client-side state cannot be fully restored on the broker on reconnection (for instance, when using transacted sessions, which exist only for the duration of a connection), automatic reconnection will not take place and the connections exception handler will be called instead. It is then up to the client application to catch the exception, reconnect, and restore state. By contrast, in an enhanced cluster (see Enhanced Clusters in Sun GlassFish Message Queue 4.4 Technical Overview), another broker can take over a failed brokers persistent state and proceed to deliver its pending messages without interruption of service. In this type of cluster, automatic reconnection is always enabled. The connection factorys imqReconnectEnabled, imqAddressList, and imqAddressListIterations attributes are ignored. The client runtime is automatically redirected to the failover broker. Because there
might be a short time lag during which the failover broker takes over from the failed broker, the imqReconnectAttempts connection factory attribute should be set to a value of -1 (client runtime continues connect attempts until successful). Automatic reconnection supports all client acknowledgment modes for message consumption. Once a connection has been reestablished, the broker will redeliver all unacknowledged messages it had previously delivered, marking them with a Redeliver flag. Client applications can use this flag to determine whether a message has already been consumed but not yet acknowledged. (In the case of nondurable subscribers, however, the broker does not hold messages once their connections have been closed. Thus any messages produced for such subscribers while the connection is down cannot be delivered after reconnection and will be lost.) Message production is blocked while automatic reconnection is in progress; message producers cannot send messages to the broker until after the connection has been reestablished.
Periodic Testing (Pinging) of Connections

The Message Queue client runtime can be configured to periodically test, or ping, a connection, allowing connection failures to be detected preemptively before an attempted message transmission fails. Such testing is particularly important for client applications that only consume messages and do not produce them, since such applications cannot otherwise detect when a connection has failed. Clients that produce messages only infrequently can also benefit from this feature. The connection factory attribute imqPingInterval specifies the frequency, in seconds, with which to ping a connection. By default, this interval is set to 30 seconds; a value of 1 disables the ping operation. The response to an unsuccessful ping varies from one operating-system platform to another. On some platforms, an exception is immediately thrown to the client applications exception listener. (If the client does not have an exception listener, its next attempt to use the connection will fail.) Other platforms may continue trying to establish a connection to the broker, buffering successive pings until one succeeds or the buffer overflows.
Client Identification
The connection factory attributes listed in Table 194 support client authentication and the setting of client identifiers for durable subscribers.
Client Authentication
All attempts to connect to a broker must be authenticated by user name and password against a user repository maintained by the message service. The connection factory attributes imqDefaultUsername and imqDefaultPassword specify a default user name and password to be used if the client does not supply them explicitly when creating a connection.
Chapter 11 Managing Administered Objects 201
As a convenience for developers who do not wish to bother populating a user repository during application development and testing, Message Queue provides a guest user account with user name and password both equal to guest. This is also the default value for the imqDefaultUsername and imqDefaultPassword attributes, so that if they are not specified explicitly, clients can always obtain a connection under the guest account. In a production environment, access to broker connections should be restricted to users who are explicitly registered in the user repository.
Client Identifier
The Java Message Service Specification requires that a connection provide a unique client identifier whenever the broker must maintain a persistent state on behalf of a client. Message Queue uses such client identifiers to keep track of durable subscribers to a topic destination. When a durable subscriber becomes inactive, the broker retains all incoming messages for the topic and delivers them when the subscriber becomes active again. The broker identifies the subscriber by means of its client identifier. While it is possible for a client application to set its own client identifier programmatically using the connection objects setClientID method, this makes it difficult to coordinate client identifiers to ensure that each is unique. It is generally better to have Message Queue automatically assign a unique identifier when creating a connection on behalf of a client. This can be done by setting the connection factorys imqConfiguredClientID attribute to a value of the form ${u}factoryID The characters ${u} must be the first four characters of the attribute value. (Any character other than u between the braces will cause an exception to be thrown on connection creation; in any other position, these characters have no special meaning and will be treated as plain text.) The value for factoryID is a character string uniquely associated with this connection factory object. When creating a connection for a particular client, Message Queue will construct a client identifier by replacing the characters ${u} with ${u:userName}, where userName is the user name authenticated for the connection. This ensures that connections created by a given connection factory, although identical in all other respects, will each have their own unique client identifier. For example, if the user name is Calvin and the string specified for the connection factorys imqConfiguredClientID attribute is ${u}Hobbes, the client identifier assigned will be ${u:Calvin}Hobbes.
202
Note This scheme will not work if two clients both attempt to obtain connections using the default user name guest, since each would have a client identifier with the same ${u} component. In this case, only the first client to request a connection will get one; the second clients connection attempt will fail, because Message Queue cannot create two connections with the same client identifier.
Even if you specify a client identifier with imqConfiguredClientID, client applications can override this setting with the connection method setClientID. You can prevent this by setting the connection factorys imqDisableSetClientID attribute to true. Note that for an application that uses durable subscribers, the client identifier must be set one way or the other: either administratively with imqConfiguredClientID or programmatically with setClientID.
Reliability And Flow Control

Because payload messages sent and received by clients and control messages (such as broker acknowledgments) used by Message Queue itself pass over the same client-broker connection, excessive levels of payload traffic can interfere with the delivery of control messages. To help alleviate this problem, the connection factory attributes listed in Table 195 allow you to manage the relative flow of the two types of message. These attributes fall into four categories:
Acknowledgment timeout specifies the maximum time (imqAckTimeout) to wait for a broker acknowledgment before throwing an exception. Connection flow metering limits the transmission of payload messages to batches of a specified size (imqConnectionFlowCount), ensuring periodic opportunities to deliver any accumulated control messages. Connection flow control limits the number of payload messages (imqConnectionFlowLimit) that can be held pending on a connection, waiting to be consumed. When the limit is reached, delivery of payload messages to the connection is suspended until the number of messages awaiting consumption falls below the limit. Use of this feature is controlled by a boolean flag (imqConnectionFlowLimitEnabled). Consumer flow control limits the number of payload messages (imqConsumerFlowLimit) that can be held pending for any single consumer, waiting to be consumed. (This limit can also be specified as a property of a specific queue destination, consumerFlowLimit.) When the limit is reached, delivery of payload messages to the consumer is suspended until the number of messages awaiting consumption, as a percentage of imqConsumerFlowLimit, falls below the limit specified by the imqConsumerFlowThreshold attribute. This helps improve load balancing among multiple consumers by preventing any one consumer from starving others on the same connection.
The use of any of these flow control techniques entails a trade-off between reliability and throughput; see Client Runtime Message Flow Adjustments on page 282 for further discussion.
Queue Browser and Server Sessions

Table 196 lists connection factory attributes affecting client queue browsing and server sessions. The imqQueueBrowserMaxMessagesPerRetrieve attribute specifies the maximum number of messages to retrieve at one time when browsing the contents of a queue destination; imqQueueBrowserRetrieveTimeout gives the maximum waiting time for retrieving them. (Note that imqQueueBrowserMaxMessagesPerRetrieve does not affect the total number of messages browsed, only the way they are batched for delivery to the client runtime: fewer but larger batches or more but smaller ones. Changing the attribute's value may affect performance, but will not affect the total amount of data retrieved; the client application will always receive all messages in the queue.) The boolean attribute imqLoadMaxToServerSession governs the behavior of connection consumers in an application server session: if the value of this attribute is true, the client will load up to the maximum number of messages into a server session; if false, it will load only a single message at a time.
Standard Message Properties

The Java Message Service Specification defines certain standard message properties, which JMS providers (such as Message Queue) may optionally choose to support. By convention, the names of all such standard properties begin with the letters JMSX. The connection factory attributes listed in Table 197 control whether the Message Queue client runtime sets certain of these standard properties. For produced messages, these include the following: JMSXUserID JMSXAppID JMSXProducerTXID Identity of the user sending the message Identity of the application sending the message Transaction identifier of the transaction within which the message was produced
For consumed messages, they include JMSXConsumerTXID JMSXRcvTimestamp Transaction identifier of the transaction within which the message was consumed Time the message was delivered to the consumer
Message Header Overrides

You can use the connection factory attributes listed in Table 198 to override the values set by a client for certain JMS message header fields. The settings you specify will be used for all messages produced by connections obtained from that connection factory. Header fields that you can override in this way are JMSDeliveryMode JMSExpiration JMSPriority
204
Delivery mode (persistent or nonpersistent) Expiration time Priority level
Using the Object Manager Utility
There are two attributes for each of these fields: one boolean, to control whether the field can be overridden, and another to specify its value. For instance, the attributes for setting the priority level are imqOverrideJMSPriority and imqJMSPriority. There is also an additional attribute, imqOverrideJMSHeadersToTemporaryDestinations, that controls whether override values apply to temporary destinations.
Note Because overriding message headers may interfere with the needs of specific applications,
these attributes should only be used in consultation with an applications designers or users.
Destination Attributes
The destination administered object that identifies a physical queue or topic destination has only two attributes, listed in Table 199. The important one is imqDestinationName, which gives the name of the physical destination that this administered object represents; this is the name that was specified with the -n option to the imqcmd create dst command that created the physical destination. (Note that there is not necessarily a one-to-one relationship between destination administered objects and the physical destinations they represent: a single physical destination can be referenced by more than one administered object, or by none at all.) There is also an optional descriptive string, imqDestinationDescription, which you can use to help identify the destination object and distinguish it from others you may have created.

The Message Queue Object Manager utility (imqobjmgr) allows you to create and manage administered objects. The imqobjmgr command provides the following subcommands for performing various operations on administered objects: add delete list query update Add an administered object to an object store Delete an administered object from an object store List existing administered objects in an object store Display information about an administered object Modify the attributes of an administered object
See Object Manager Utility on page 327 for reference information about the syntax, subcommands, and options of the imqobjmgr command. Most Object Manager operations require you to specify the following information as options to the imqobjmgr command:
The JNDI lookup name (-l) of the administered object

205
This is the logical name by which client applications can look up the administered object in the object store, using the Java Naming and Directory Interface.
The attributes of the JNDI object store (-j) See Object Stores on page 195 for information on the possible attributes and their values. The type (-t) of the administered object Possible types include the following: q t cf qf tf xcf xqf xtf Queue destination Topic destination Connection factory Queue connection factory Topic connection factory Connection factory for distributed transactions Queue connection factory for distributed transactions Topic connection factory for distributed transactions
The attributes (-o) of the administered object See Administered Object Attributes on page 198 for information on the possible attributes and their values.
Adding Administered Objects

The imqobjmgr commands add subcommand adds administered objects for connection factories and topic or queue destinations to the object store. Administered objects stored in an LDAP object store must have lookup names beginning with the prefix cn=; lookup names in a file-system object store need not begin with any particular prefix, but must not include the slash character (/).
Note The Object Manager lists and displays only Message Queue administered objects. If an object store contains a nonMessage Queue object with the same lookup name as an administered object that you wish to add, you will receive an error when you attempt the add operation.

To enable client applications to create broker connections, add a connection factory administered object for the type of connection to be created: a queue connection factory or a topic connection factory, as the case may be. Example 111 shows a command to add a queue
connection factory (administered object type qf) to an LDAP object store. The object has lookup name cn=myQCF and connects to a broker running on host myHost at port number 7272, using the jms connection service.
EXAMPLE 111
imqobjmgr add -l "cn=myQCF" -j "java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory" -j "java.naming.provider.url=ldap://mydomain.com:389/o=imq" -j "java.naming.security.principal=uid=homerSimpson,ou=People,o=imq" -j "java.naming.security.credentials=doh" -j "java.naming.security.authentication=simple" -t qf -o "imqAddressList=mq://myHost:7272/jms"
Adding a Destination
When creating an administered object representing a destination, it is good practice to create the physical destination first, before adding the administered object to the object store. Use the Command utility (imqcmd) to create the physical destination, as described in Creating and Destroying Physical Destinations on page 109. The command shown in Example 112 adds an administered object to an LDAP object store representing a topic destination with lookup name myTopic and physical destination name
207
physTopic. The command for adding a queue destination would be similar, except that the administered object type (-t option) would be q (for queue destination) instead of t (for topic destination).
EXAMPLE 112
Adding a Destination to an LDAP Object Store
imqobjmgr add -l "cn=myTopic" -j "java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory" -j "java.naming.provider.url=ldap://mydomain.com:389/o=imq" -j "java.naming.security.principal=uid=homerSimpson,ou=People,o=imq" -j "java.naming.security.credentials=doh" -j "java.naming.security.authentication=simple" -t t -o "imqDestinationName=physTopic"
Example 113 shows the same command, but with the administered object stored in a Solaris file system instead of an LDAP server.
EXAMPLE 113
Adding a Destination to a File-System Object Store
imqobjmgr add -l "cn=myTopic" -j "java.naming.factory.initial=com.sun.jndi.fscontext.RefFSContextFactory" -j "java.naming.provider.url=file:///home/foo/imq_admin_objects" -t t -o "imqDestinationName=physTopic"
Deleting Administered Objects

To delete an administered object from the object store, use the imqobjmgr delete subcommand, specifying the lookup name, type, and location of the object to be deleted. The command shown in Example 114 deletes the object that was added in Adding a Destination on page 207 above.
EXAMPLE 114
Deleting an Administered Object
208
imqobjmgr delete -l "cn=myTopic" -j "java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory" -j "java.naming.provider.url=ldap://mydomain.com:389/o=imq" -j "java.naming.security.principal=uid=homerSimpson,ou=People,o=imq" -j "java.naming.security.credentials=doh" Sun GlassFish Message Queue 4.4 Administration Guide June 2010 -j "java.naming.security.authentication=simple" -t t
Listing Administered Objects

You can use the imqobjmgr list subcommand to get a list of all administered objects in an object store or those of a specific type. Example 115 shows how to list all administered objects on an LDAP server.
EXAMPLE 115
Listing All Administered Objects
imqobjmgr list -j "java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory" -j "java.naming.provider.url=ldap://mydomain.com:389/o=imq" -j "java.naming.security.principal=uid=homerSimpson,ou=People,o=imq" -j "java.naming.security.credentials=doh" -j "java.naming.security.authentication=simple"
209
Example 116 lists all queue destinations (type q).

EXAMPLE 116
Listing Administered Objects of a Specific Type
imqobjmgr list -j "java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory" -j "java.naming.provider.url=ldap://mydomain.com:389/o=imq" -j "java.naming.security.principal=uid=homerSimpson,ou=People,o=imq" -j "java.naming.security.credentials=doh" -j "java.naming.security.authentication=simple" -t q
Viewing Administered Object Information

The imqobjmgr query subcommand displays information about a specified administered object, identified by its lookup name and the attributes of the object store containing it. Example 117 displays information about an object whose lookup name is cn=myTopic.
EXAMPLE 117
Viewing Administered Object Information
imqobjmgr query -l "cn=myTopic" -j "java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory" -j "java.naming.provider.url=ldap://mydomain.com:389/o=imq" -j "java.naming.security.principal=uid=homerSimpson,ou=People,o=imq" -j "java.naming.security.credentials=doh" -j "java.naming.security.authentication=simple"
Modifying Administered Object Attributes

To modify the attributes of an administered object, use the imqobjmgr update subcommand. You supply the objects lookup name and location, and use the -o option to specify the new attribute values.
210
Example 118 changes the value of the imqReconnectAttempts attribute for the queue connection factory that was added to the object store in Example 111.
EXAMPLE 118
Modifying an Administered Objects Attributes
imqobjmgr update -l "cn=myQCF" -j "java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory" -j "java.naming.provider.url=ldap://mydomain.com:389/o=imq" -j "java.naming.security.principal=uid=homerSimpson,ou=People,o=imq" -j "java.naming.security.credentials=doh" -j "java.naming.security.authentication=simple" -t qf -o "imqReconnectAttempts=3"
Using Command Files

The -i option to the imqobjmgr command allows you to specify the name of a command file that uses Java property file syntax to represent all or part of the subcommand clause. This feature is especially useful for specifying object store attributes, which typically require a lot of typing and are likely to be the same across multiple invocations of imqobjmgr. Using a command file can also allow you to avoid exceeding the maximum number of characters allowed for the command line.
211
Example 119 shows the general syntax for an Object Manager command file. Note that the version property is not a command line option: it refers to the version of the command file itself (not that of the Message Queue product) and must be set to the value 2.0.
EXAMPLE 119
Object Manager Command File Syntax
version=2.0 cmdtype=[ add | delete | list | query | update ] obj.lookupName=lookup name objstore.attrs.objStoreAttrName1=value1 objstore.attrs.objStoreAttrName2=value2 . . . objstore.attrs.objStoreAttrNameN=valueN obj.type=[ q | t | cf | qf | tf | xcf | xqf | xtf | e ] obj.attrs.objAttrName1=value1 obj.attrs.objAttrName2=value2 . . . obj.attrs.objAttrNameN=valueN
As an example, consider the Object Manager command shown earlier in Example 111, which adds a queue connection factory to an LDAP object store. This command can be encapsulated in a command file as shown in Example 1110. If the command file is named MyCmdFile, you can then execute the command with the command line
212
imqobjmgr -i MyCmdFile
EXAMPLE 1110
Example Command File
version=2.0 cmdtype=add obj.lookupName=cn=myQCF objstore.attrs.java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory objstore.attrs.java.naming.provider.url=ldap://mydomain.com:389/o=imq objstore.attrs.java.naming.security.principal=uid=homerSimpson,ou=People,o=imq objstore.attrs.java.naming.security.credentials=doh objstore.attrs.java.naming.security.authentication=simple obj.type=qf obj.attrs.imqAddressList=mq://myHost:7272/jms
A command file can also be used to specify only part of the imqobjmgr subcommand clause, with the remainder supplied directly on the command line. For example, the command file shown in Example 1111 specifies only the attribute values for an LDAP object store.
EXAMPLE 1111
Partial Command File
version=2.0 objstore.attrs.java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory objstore.attrs.java.naming.provider.url=ldap://mydomain.com:389/o=imq objstore.attrs.java.naming.security.principal=uid=homerSimpson,ou=People,o=imq objstore.attrs.java.naming.security.credentials=doh objstore.attrs.java.naming.security.authentication=simple
You could then use this command file to specify the object store in an imqobjmgr command while supplying the remaining options explicitly, as shown in Example 1112.
EXAMPLE 1112
Using a Partial Command File
imqobjmgr add -l "cn=myQCF" -i MyCmdFile -t qf -o "imqAddressList=mq://myHost:7272/jms"
Additional examples of command files can be found at the following locations, depending on how Message Queue was installed:
IPS packages Solaris SVR4 packages Linux RPM packages
IMQ_HOME/examples/imqobjmgr /usr/demo/imq/imqobjmgr /opt/sun/mq/examples/imqobjmgr
214
12
C H A P T E R
1 2
Configuring and Managing Bridge Services
Message-Oriented Middleware (MOM) systems use a broad spectrum of technologies and standards to provide messaging services. Often, these technologies and standards are incompatible, leading to MOM systems that cannot communicate with each other in a larger enterprise application context. To alleviate this inability to communicate, Message Queue incorporates the Bridge Service Manager, which supports individual bridge services of various types. Each type of bridge service provides connectivity at the broker level to a MOM technology or standard that would otherwise be unavailable in Message Queue. This chapter provides information about the administrative components of the Bridge Service Manager, and shows how to configure and manage the two types of bridge services currently available:

The Bridge Service Manager on page 215 Configuring and Managing JMS Bridge Services on page 217 Configuring and Managing STOMP Bridge Services on page 235
The Bridge Service Manager

The Message Queue Bridge Service Manager is an application that runs in same JVM as a broker to manage the bridges configured for the broker. Two administrative components control operation of the Bridge Service Manager:

Bridge-related broker properties The Bridge Manager utility (imqbridgermgr)
The following sections introduce these two components.
215
The Bridge Service Manager
Bridge-Related Broker Properties

The operation of the Bridge Service Manager is in part controlled by several broker properties. These broker properties, all of which begin with imq.bridge, are listed in tables under Bridge Properties on page 363. Some of the properties apply to all bridges configured for the broker, while others apply only to a specific bridge. The properties that apply to a specific bridge all begin with imq.bridge.bridgeName, where bridgeName is:
The same as the type of the bridge for bridge services that support only one bridge instance per broker, such as the STOMP bridge service A name you specify for a bridge instance for bridge services that support multiple bridge instances per broker, such as the JMS bridge service
Of all the bridge-related broker properties, the two most important are imq.bridge.enabled and imq.bridge.activelist:
The imq.bridge.enabled property controls whether the Bridge Service Manager is enabled on the broker. The imq.bridge.activelist property contains a comma-separated list bridges (by name) to be loaded when the broker starts.
To Enable the Bridge Service Manager

1 2 3
Set the imq.bridge.enabled broker property to true. Set the imq.bridge.admin.user broker property to the user name of the admin user. Set the imq.bridge.admin.password broker property to the password of the admin user. Alternatively, you can specify the password using the -passfile option when you use the imqbrokerd command to start the broker hosting the bridge service manager. Set the imq.bridge.activelist broker property to a comma-separated list of bridges to instantiate at broker startup.
Bridge Manager Utility

The Bridge Manager utility (imqbridgemgr) is the interface to the bridge management functions of the Bridge Service Manager. It provides commands to:

Stop and start bridges Pause and resume bridges List configured bridges
216
Configuring and Managing JMS Bridge Services
Manage type-dependent subcomponents of bridges, such as the links within a JMS bridge service
The imqbridgemgr utility uses the same command line syntax as the other Message Queue utilities:
imqbridgemgr subcommand commandArgument [ options ]
For example, the following command lists all bridges of type JMS on the broker localhost:7373:
imqbridgemgr list bridge -t jms -b localhost:7373
For the complete set of subcommands, command arguments, and options supported by the imqbridgemgr utility, see Bridge Manager Utility on page 332.
Logging of Bridge Services

Each bridge managed by the Bridge Service Manager for a broker has its own log file. Where these log files are stored depends on how Message Queue was installed: From IPS packages: IMQ_VARHOME/instances/broker-name/bridges/bridge-name/ From Solaris SVR4 packages: /var/imq/instances/broker-name/bridges/bridge-name/ From Linux RPM packages: /var/opt/sun/mq/instances/broker-name/bridges/bridge-name/ The JMS and STOMP bridge services use the Java logging facility, which can be configured by the Java logging configuration file. The logging level for a bridge can be controlled by setting the imq.bridge.bridge-name.level property in the Java logging configuration file. Then, the Java system property java.util.logging.config.file can be set to the Java logging configuration file when the broker is started; as in:
imqbrokerd -Djava.util.logging.config.file=config-file

Because the JMS specification does not dictate the communication protocol between brokers and clients, each JMS provider (including Message Queue) has defined and uses its own propriety protocol. This situation has led to non-interoperability across JMS providers. The JMS bridge service in Message Queue 4.4 closes this gap by enabling a Message Queue broker to map its destinations to destinations in external JMS providers. This mapping effectively allows the Message Queue broker to communicate with clients of the external JMS provider.
Chapter 12 Configuring and Managing Bridge Services 217
The JMS bridge service supports mapping destinations to external JMS providers that:

Are JMS 1.1 compliant Support JNDI administrative objects Use connection factories of type javax.jms.ConnectionFactory or javax.jms.XAConnectionFactory Support the XA interfaces as a resource manager for transacted mapping
As an administrative and management convenience, the JMS bridge service supports the creation of any number of JMS bridges in a broker. Each JMS bridge in the broker is identified by a unique name, has its own configuration, and is managed separately from other JMS bridges in the broker. The following subsections provide information about JMS bridges and how to configure and manage them:

JMS Bridge Components on page 218 JMS Bridge Features on page 219 Message Processing Sequence Across a Link in a JMS Bridge on page 224 Configuring a JMS Bridge on page 225 Starting and Stopping JMS Bridges on page 233 Starting and Stopping Links in a JMS Bridge on page 234
JMS Bridge Components

A JMS bridge consists of two primary components:
One or more links, each of which maps between a destination in the Message Queue broker and a destination in an external JMS provider or in another Message Queue broker A default Dead Message Queue (DMQ) where undeliverable messages are sent. Additional, special-purpose DMQs can also be specified.
To provide destination mapping, each link consists of:
A source: the destination from which the JMS bridge receives messages. The source consists of a connection factory for creating connections to a JMS provider and a destination in that provider. A target: the destination to which the JMS bridge forwards messages received from the source. The target consists of a connection factory for creating connections to a JMS provider and a destination in that provider. Additionally, a target can optionally specify a message transformer that alters messages from the source before forwarding them to the target destination.
Links are unidirectional. Links that have an external JMS provider or another Message Queue broker as their source are called inbound links, and links that have the Message Queue broker as their source are called outbound links.
To configure these components, you specify several imq.bridge.bridgeName broker properties, and you create an XML configuration file that specifies the links, sources, targets, connection factories, destinations, and DMQs in the bridge. This XML configuration file must conform to the JMS bridge DTD.
JMS Bridge Features

To provide flexible, high-performing message transfer between mapped destinations, a JMS bridge offers these features:

Pooled, Shared, and Dedicated Connections on page 219 Transactional Message Transfer on page 219 JMS Bridges in High Availability (HA) Broker Clusters on page 220 Message Transformation During Message Delivery on page 221 JMSReplyTo Header Processing on page 221 Dead Message Queue (DMQ) Processing on page 221
Pooled, Shared, and Dedicated Connections

A JMS bridge uses the connection factories configured for link sources, link targets, and DMQs to create connections to the Message Queue broker and the external JMS provider. When making connections, the JMS bridge follows these rules to determine whether to use a pooled connection, a shared connection, or a dedicated connection:

For link source connections, the JMS bridge always uses a dedicated connection. For link target and DMQ connections, the JMS bridge uses:
A pooled connection if the link target's or DMQ's stay-connected attribute is false and the connection factory has no JMS client identifier configured. A dedicated connection if the link target's or DMQ's stay-connected attribute is true or if the link target's or DMQ's clientid attribute is set A shared connection in all other cases
Transactional Message Transfer

Each JMS bridge includes a built-in XA transaction coordinator that enables its links to be configured as "transacted" such that message transfer from the source to the target is done in a XA distributed transaction. For a link to be configured as transacted, both the link source and link target must specify connection factories of type javax.jms.XAConnectionFactory. The built-in XA transaction coordinator logs transaction records using the same type of store as the Message Queue broker in which the JMS bridge resides. For file-based transaction logging, the transaction log for a JMS bridge is located at:
IMQ_VARHOME/instances/brokerInstance/bridges/bridgeName/txlog.bridgeNane
For JDBC-based transaction logging, the built-in XA transaction coordinator uses the same JDBC store as the Message Queue broker in which the JMS bridge resides.
Resource Manager Registration and The Built-In XA Transaction Coordinator

When a JMS bridge is started, it registers all its Resource Managers (RMs) with the built-in XA transaction coordinator so that the coordinator can identify specific RMs during recovery. For connection factories, the JMS bridge only registers the factory as an RM if the factory's multi-rm attribute value is false. A connection factory with a multi-rm attribute value of true should have each of its RMs identified by a connection factory whose multi-rmattribute value of false in order to participate in transactional message transfer. Additionally, the JMS bridge uses a connection factory's ref-name attribute value as part of its RM name when registering RMs with the built-in XA transaction coordinator, so this attribute should not be changed between restarts of the bridge if transaction recovery is desired between restarts.
JMS Bridges in High Availability (HA) Broker Clusters

Message Queue supports JMS bridges in HA broker clusters, but some special constraints apply due to the inherent nature of HA broker clusters:
Each JMS bridge must have a name that is unique across all the JMS bridges in all the brokers in the cluster. Each JMS bridge must have the same bridge configuration across all the brokers in the cluster. The imq.bridge.enabled broker property must have the same value across all brokers in the cluster. Before broker startup, the imq.bridge.activelist broker property for each broker lists only those JMS bridges that are to be owned by that broker.
To ensure that bridges in the cluster have the same configuration across all brokers in the cluster, all bridge-related broker properties except for imq.bridge.activelist should be specified in the centralized cluster properties file defined by the imq.cluster.url broker property. A table in the cluster's HA store is used to maintain a consistent record of JMS bridge ownership by the brokers in the cluster. During broker startup, the JMS bridge service compares the broker's imq.bridge.activelist property value to this table's entries before starting any JMS bridges, with the following consequences:
If a JMS bridge named in imq.bridge.activelist does not appear in the table, it is added to the table and associated with the broker.
220
If a JMS bridge name in imq.bridge.activelist does appear in the table, and the table entry already associates the bridge with a different broker, the bridge name is removed from imq.bridge.activelist. If an entry in the table associates a JMS bridge with the broker, and that bridge's name is not in imq.bridge.activelist, the bridge name is added to imq.bridge.activelist.
Message Transformation During Message Delivery

A link target or a DMQ can specify a message transformer to process the message before it is delivered to the target destination or DMQ destination. This message transformer must be a Java class that extends the Message Queue bridge com.sun.messaging.bridge.service.MessageTransformer abstract class and has javax.jms.Message as its formal type parameters. To specify a message transformer, set the message-transformer-class attribute of a link target or a DMQ to the fully qualified class name of the Java class. During message transfer processing, the JMS message to be transferred to a target, plus any property subelements of the link's target element or the dmq element, are passed to the message transformer's MessageTransformer.transform() method, and the returned JMS message is sent to the target destination.
JMSReplyTo Header Processing

In a JMS message, the JMSReplyTo header value is provider dependent. Therefore, unless both the source provider and target provider are Message Queue, the JMS bridge sets an existing JMSReplyTo header to a null value before passing the message to a link target or, if specified, the message transformer for the link target. This default behavior can be overridden by setting the retain-replyto attribute of the link's target element to true. Overriding the default behavior is useful when:

The message transformer for a link target handles processing of the JMSReplyTo header. Both the link source and link target have the same JMS provider, and clients of the target provider instance need to send reply messages back across the JMS bridge to the JMSReplyTo destination in the source provider instance. To successfully implement this case:
The JMSReplyTo destination must exist (or be able to be auto-created) in the target provider instance. A JMS bridge link must be defined with its source set to the JMSReplyTo destination in the target provider instance and its target set to the JMSReplyTo destination in the source provider instance.
Dead Message Queue (DMQ) Processing

Each JMS bridge includes a built-in Dead Message Queue (DMQ) named built-in-dmq. This DMQ is a designated Queue destination named imq.bridge.jms.dmq in the broker hosting the
JMS bridge. You can also configure additional DMQs for the JMS bridge, in which case the DMQ can use any JMS destination in any configured JMS provider.
Note In a production environment, the built-in DMQ, imq.bridge.jms.dmq, should be
administratively created and have its access controls set appropriately before starting a broker that uses JMS bridge services. When a DMQ uses Message Queue as the JMS provider, it can be configured such that messages sent to it will automatically be transferred to the Message Queue broker's DMQ. To do so, set physical destination properties of the JMS bridge's DMQ as follows:
useDMQ=true limitBehavior=REMOVE_OLDEST maxNumMsgs=0
When a message is sent to the DMQ, the JMS bridge follows this sequence with the built-in DMQ first: 1. The bridge creates a new DMQ javax.jms.ObjectMessage object and sets the properties listed in Table 121 to the ObjectMessage. 2. If the DMQ has defined a message transformer, the original message is passed to the transformer's MessageTransformer.transform() method. 3. The body of the javax.jms.ObjectMessage is set to the transformed message (or original message if no message transformer is defined). If this action fails (usually because the message is not serializable), the body of the ObjectMessage is instead set to the toString() value of the original message. 4. The javax.jms.ObjectMessage is sent (up to send-attempts times) to the DMQ's destination with a timeToLive value based on the DMQ's time-to-live-in-millis attribute and with the same JMSDeliveryMode and JMSPriority as the original message. 5. If sending the message fails, the bridge repeats Steps 2 through 4 for each DMQ defined in the bridge's XML configuration file in the order they appear in the file, stopping when a send attempt succeeds, unless it is the built-in DMQ. 6. If the message can't be sent to any DMQ, a log message is generated, containing the properties and headers of the original message and the properties set in Step 1.
222
TABLE 121 Property
DMQ Message Propeties

Type Description
JMS_SUN_JMSBRIDGE_DMQ_BODY_TRUNCATED
String
If unable to set the original message or the transformed message (if the DMQ has a message transformer) to the body of the DMQ ObjectMessage. In that case the message's toString() is set to the body of the DMQ ObjectMessage. The Exception.getMessage() if exception occurred or detailed comments on the failure; null if none. One of: MESSAGE_EXPIRED, SEND_FAILURE, ACK_FAILURE, TRANSFORM_FAILURE, COMMIT_FAILURE. The timestamp when the JMS bridge sends the message to the DMQ. The original message's getJMSCorrelationID(). The original message's source destination name. The original message's getJMSType(). The orginal message's getJMSMessageID(), or null if not available. The ConnectionMetaData.getJMSProviderName of the connection the original message was received on; if not available, the source connection factory's getClass().getName(). The original message's getJMSTimestamp(). The name of the target destination where the original message was intended to send to. The ConnectionMetaData.getJMSProviderName of the connection the original message was intended to send on; if not available, the target connection factory's getClass().getName().
JMS_SUN_JMSBRIDGE_DMQ_EXCEPTION
String
JMS_SUN_JMSBRIDGE_DMQ_REASON
String
JMS_SUN_JMSBRIDGE_DMQ_TIMESTAMP
String String String String String String
JMS_SUN_JMSBRIDGE_SOURCE_CORRELATIONID
JMS_SUN_JMSBRIDGE_SOURCE_DESTINATION
JMS_SUN_JMSBRIDGE_SOURCE_JMSTYPE JMS_SUN_JMSBRIDGE_SOURCE_MESSAGEID
JMS_SUN_JMSBRIDGE_SOURCE_PROVIDER
JMS_SUN_JMSBRIDGE_SOURCE_TIMESTAMP JMS_SUN_JMSBRIDGE_TARGET_DESTINATION
Long String String
JMS_SUN_JMSBRIDGE_TARGET_PROVIDER
Chapter 12 Configuring and Managing Bridge Services
223
Message Processing Sequence Across a Link in a JMS Bridge

A JMS bridge link receives messages in the order sent by the link's source JMS provider and transfer them in the same order to the link's target JMS provider. A link follows this sequence to transfer each message: 1. The link receives a JMS message from its source. 2. The link checks the JMSExpiration header to determine whether the message has expired. If it has, a log message is generated, the JMS message is sent to the DMQ, and no further action is taken. 3. If the message has a JMSReplyTo header and the link target's retain-replyto attribute is false, the JMSReplyTo header value is set to null. 4. If the link target has defined a message transformer, the transformer's MessageTransformer.transform() method is called. If the call fails or if the message transformer returns a null value, a log message is generated and then processing continues as follows:
In Message Queue 4.4, the untransformed message is sent to the DMQ and processing continues on the untransformed message. In Message Queue 4.4 Update 1, if the target's consume-no-transfer-on-transform-error XML attribute is true, the untransformed message is sent to the DMQ, consumed from the source, but not sent to the target. In Message Queue 4.4 Update 1, if the target's consume-no-transfer-on-transform-error XML attribute is false, the link is stopped and the message is neither consumed from the source nor sent to the target.
5. Beginning with Message Queue 4.4 Update 1, if the message-transfer-tag-bridge-name attribute of the jmsbridge element is true, the JMS_SUN_JMSBRIDGE_NAME property is added to the message and set to the name of the bridge. 6. The message is sent to the link target's destination with a timeToLive value based on the JMSExpiration header and current GMT time and with the same JMSDeliveryMode and JMSPriority values as the original message. If sending to the link target's destination fails and the link is not transacted, a log message is generated, the JMS message is sent to the DMQ, and processing continues. 7. The source message is acknowledged using JMS CLIENT_ACKNOWLEDGE if the link is not transacted. If the acknowledgement fails, a log message is generated and the JMS message is sent to the DMQ. 8. Beginning in Message Queue 4.4 Update 1, if the message processing was successful, an INFO log message is generated. Message processing for messages across transacted links follows the same processing sequence, except JTA interfaces are used to coordinate the source and target resource managers to transfer
the message in an XA distributed transaction. For transacted links, failure to send the message to the link target's destination does not cause the JMS message to be sent to the DMQ; instead, the transaction is rolled back. However, if the attempt to commit the transaction fails, a log message is generated and the JMS message is sent to the DMQ. The quality of message transfer under failures depends on whether the link transferring the message is transacted:

Transacted links: once-only-once Non-transacted links: at-least-once
Configuring a JMS Bridge

To configure a JMS bridge, you specify several imq.bridge.bridgeName broker properties, where bridgeName is a name you choose for the JMS bridge. Additionally, you create an XML configuration file that specifies the links, sources, targets, connection factories, destinations, and DMQs in the bridge. The url of this configuration file is provided as the value of the imq.bridge.bridgeName.xml property
Specifying the Broker Properties for a JMS Bridge

Table 122 lists the broker properties you can specify for a JMS bridge. In this table, name is the name of the JMS bridge, which must be unique across all bridges in the broker.
TABLE 122
Broker Properties for a JMS Bridge

Type Default Value Description
Property
imq.bridge.name.type imq.bridge.name.xmlurl
String String
None None
The bridge type of the bridge named name. For JMS bridges, specify a value of JMS or jms. The URL where the XML configuration file for the JMS bridge name is stored. Examples: http://webserver/imq/jmsbridge1.config.xml (for a file on a Web server) file:/net/fileserver/imq/jmsbridge1.config.xml (for a file on a shared drive)
imq.bridge.name.autostart imq.bridge.name.logfile.limit
Boolean Integer
true
Should the JMS bridge name be automatically started when the broker is started? The approximate maximum number of bytes the JMS bridge name writes to any one log file. A value of 0 (zero) indicates that there is no maximum limit.
225
TABLE 122 Property
Broker Properties for a JMS Bridge

Type
(Continued)
Default Value Description
imq.bridge.name.logfile.count imq.bridge.tm.props imq.bridge.name.tm.props
Integer String
1 None
The number of log files the JMS bridge name cycles through. Each of these properties specifies a list of key-value pairs for the built-in transaction coordinator for the JMS bridge name. The list consists of one or more key=value pairs separated by commas. When the imq.persist.store is file, the built-in transaction coordinator supports these keys: txlogSize, txlogSync, and txlogMmap. If the same key appears in both properties, the value specified in imq.bridge.name.tm.props takes precedence.
Creating the XML Configuration File for a JMS Bridge

As mentioned earlier, the XML configuration file for a JMS bridge specifies the following components of the bridge:

Links Sources Targets Connection factories Destinations DMQs
The configuration file must conform to the JMS bridge DTD, which is stored at:
IMQ_HOME/lib/dtd/sun_jmsbridge_Version.dtd
The basic structure of configuration file is:

<jmsbridge name=bridgeName otherAttributes> <link name=linkName otherAttributes> [ <description>linkDescription</description> ] <source connection-factory-ref=connFactoryRef destination-ref=destRef otherAttributes> [ <description>sourceDescription</description> </source> <target connection-factory-ref=connFactoryRef destination-ref=destRef otherAttributes> [ <description>targetDescription</description> ] [ <property name=propName value=propValue /> ] ... </target> </link> <dmq name=dmqName otherAttributes> /* use name="built-in-dmq" for the built-in DMQ */ [ <description>dmqDescription</description> ] [ <property name=propName value=propValue /> ] ...
</dmq> <connection-factory ref-name=connFactoryRef otherAttributes> [ <description>connFactoryDescription</description> ] [ <property name=propName value=propValue /> ] ... </connection-factory> <destination ref-name=destRef otherAttributes> [ <description>destDescription</description> ] [ <property name=propName value=propValue /> ] ... </destination> ... </jmsbridge>
From this abbreviated structure for the bridge XML configuration file, note that source and target are subelements of link, while connection-factory and destination are peer elements to link, not subelements of source and target. Connection factories and destinations are associated with sources and targets by matching connection-factory ref-name and destination ref-name attributes values to source and target connection-factory-ref and destination-ref attribute values, respectively. As a result of this association by name-matching instead of by subelement inclusion, you can use the same connection factories and destinations across sources and targets in multiple links, thus streamlining the configuration file and making it more manageable. The following subsections describe the attributes you can specify for the elements in the JMS bridge XML configuration file.
jmsbridge Attributes
Table 123 lists the attributes for the jmsbridge element in the JMS Bridge XML configuration file.
TABLE 123 Attribute
jmsbridge Attributes
Type Description
name
String
Unique name for this JMS bridge. Default value: no default
message-transfer-tag-bridge-name1
Boolean
Should the JMS_SUN_JMSBRIDGE_NAME property be defined and set to the name of the bridge for each message before transferring to the link target? Default value: false
First available in Message Queue 4.4 Update 1
link Attributes
Table 124 lists the attributes for the link element in the JMS Bridge XML configuration file.
TABLE 124 Attribute
link Attributes
Type Description
enabled
Boolean
If false, the link will not be started Default value: true
name
String
Unique identifier for this link Default value: no default
transacted
Boolean
If true, each message transfer from source to target will be done in a XA distributed transaction. The connection factories specified by the source and target must be javax.jms.XAConnectionFactory objects. If false, CLIENT_ACKNOWLEDGE mode will be used on the source The connection factories specified by the source and target must be javax.jms.ConnectionFactory objects. Default value: true
source Attributes
Table 125 lists the attributes for the source element in the JMS Bridge XML configuration file.
TABLE 125 Attribute
source Attributes
Type Description
clientid
String
A JMS client identifier for the message consumer connection Default value: not set
connection-factory-ref
String
The ref-name attribute value of the connection-factory element to associate with this source. Default value: no default
destination-ref
String
The ref-name attribute value of the destination element to associate with this source. Default value: no default
durable-sub
String
A JMS durable subscription name. This attribute is ignored if the source's destination is not a javax.jms.Topic object. Default value: not set
selector
String
A JMS selector for the message consumer Default value: not set
228
target Attributes
Table 126 lists the attributes for the target element in the JMS Bridge XML configuration file.
TABLE 126 Attribute
target Attributes
Type Description
clientid
String
A JMS client identifier for the message producer connection; if set, use a dedicated connection. Default value: not set
connection-factory-ref
String
The ref-name attribute value of the connection-factory element to associate with this target. Default value: no default
consume-no-transfer-on-transform-error
Boolean
Controls processing when the message transformer's MessageTransformer.transform() method returns a null value or throws java.lang.Throwable: If true, the message is sent to the DMQ and consumed from the source but not sent to the target.
If false, the link is stopped, and the message is neither consumed from the source nor transferred to the target.
Default value: false destination-ref String The ref-name attribute value of the destination element to associate with this target. Beginning in Message Queue 4.4 Update 1, the value AS_SOURCE is also supported. This value causes the target destination name and type to be set to the source message's javax.jms.Message.getJMSDestination(), unless overridden by the message transformer's MessageTransformer.branchTo(). Default value: no default message-transformer-class String A fully qualified class name that extends the Message Queue bridge MessageTransformer class. For more information, see Message Transformation During Message Delivery on page 221. Place this class under the IMQ_HOME/lib/ext directory. Default value: not set retain-replyto Boolean Should the value of the source message's JMSReplyTo header (if specified) be retained? For more information, see JMSReplyTo Header Processing on page 221. Default value: false
1
First available inMessage Queue 4.4 Update 1
229
TABLE 126 Attribute
target Attributes
(Continued)
Type Description
stay-connected
Boolean
If true, the message producer connection will stay connected, and be dedicated. Default value: true
dmq Attributes
Table 127 lists the attributes for the dmq element in the JMS Bridge XML configuration file.
TABLE 127 Attribute
dmq Attributes
Type Description
client-id
String
JMS client identifier for the DMQ producer connection. If set, the connection will be dedicated. Default value: not set
connection-factory-ref1
String
The ref-name attribute value of the connection-factory element to associate with this DMQ. This connection factory must be a javax.jms.ConnectionFactory object. Default value: no default
destination-ref1
String
The ref-name attribute value of the destination element to associate with this DMQ. Default value: no default
enabled1
Boolean
Is this DMQ is enabled? Default value: true
message-transformer-class
String
A fully qualified class name that extends the Message Queue bridge MessageTransformer class. For more information, see Message Transformation During Message Delivery on page 221. Default value: not set
name
String
The unique identifier of this DMQ. Default value: no default
send-attempt-interval-in-seconds
Integer
How long to wait before attempting to resend an undeliverable message to this DMQ. Default value: 5
This attribute is ignored for the built-in DMQ, built-in-dmq
230
TABLE 127 Attribute
dmq Attributes
(Continued)
Type Description
send-attempts
Integer
The number of attempts to send (or resend) an undeliverable message to this DMQ. Default value: 3
stay-connected
Boolean
If true, the DMQ producer connection will stay connected and be dedicated. Default value: true
time-to-live-in-millis
Integer
Time-to-live in milliseconds for messages going to this DMQ. The value 0 means forever. Default value: 0
This attribute is ignored for the built-in DMQ, built-in-dmq
connection-factory Attributes
Table 128 lists the attributes for the connection-factory element in the JMS Bridge XML configuration file.
TABLE 128 Attribute
Type Description
connect-attempt-interval-in-seconds
Integer
How long to wait before each connect attempt. Default value: 5
connect-attempts
Integer
The number of attempts for connecting. The value -1 means retry forever Default value: -1
idle-timeout-in-seconds
Integer
Close a connection if it is idle for more than this long. The value 0 indicates no idle timeout. This attribute is ignored for sources and for targets and DMQs that have their stay-connected attribute set to true. Default value: 1800
231
TABLE 128 Attribute
(Continued)
Type Description
lookup-name
String
JNDI lookup name. If specified, the JNDI environment properties must specified as property subelements of this connection-factory element. The object returned by the lookup must be either javax.jms.ConnectionFactory or javax.jms.XAConnectionFactory type If not specified, a default connection factory to the Message Queue broker hosting the bridge is created with the properties in the property subelements. Default value: not set
multi-rm
Boolean
Set to true if this connection factory will potentially create XA connections to more than one XA resource manager (that is, XAResource.isSame() is false among them). Also, add separate connection-factory for each such resource manager so that they will be registered separately to the built-in XA transaction coordinator. Default value: false
password
String
The password for the user specified in username. Default value: not set
ref-name
String
Unique name for this connection factory. Default value: no default
username
String
The user name to be used to create connections from this connection factory. If this attribute is set, the password attribute must also be set. If not set, connections are created using the no-argument createConnection() method of the connection factory. Default value: not set
First available inMessage Queue 4.4 Update 1
destination Attributes
Table 129 lists the attributes for the destination element in the JMS Bridge XML configuration file.
232
TABLE 129 Attribute
destination Attributes
Type Description
lookup-name
String
JNDI lookup name for the destination. If specified, the JNDI environment properties must specified as property subelements of this destination element. Default value: not set
name
String
The JMS destination name of this destination. This attribute is ignored if lookup-name is specified. Default value: not set
ref-name
String
Unique name for this destination. Default value: no default
type
queue or topic
The JMS destination type of this destination. This attribute is ignored if lookup-name is specified Default value: queue
Starting and Stopping JMS Bridges

JMS bridges can be started automatically when the broker hosting the bridge starts, or manually using the imqbridgemgr utility. Similarly, JMS bridges are stopped automatically when the broker hosting the bridge is shut down, or manually using the imqbridgemgr utility. When a JMS bridge is started, the JMS bridge manager performs these tasks: 1. Parse and validate the bridge's XML configuration file. 2. Initialize all links and DMQs that have their enabled attribute set to true. 3. If any enabled links have their transacted attribute set to true: a. Initialize the built-in XA transaction coordinator. b. Register resource managers (RMs) for all potential XA connection factories. c. Perform XA recovery for available RMs. 4. Create connection pools and shared connections as needed. 5. Ensure that all DMQs are ready. 6. Start all enabled links. When a JMS bridge is stopped, the JMS bridge manager performs these tasks: 1. Stop all started and paused links. 2. Wait until all pooled connections are returned to their respective pools and until all references to shared connections are returned.
3. Close all connection pools and shared connections. This effectively causes all physical connections to JMS providers to close.
To Configure a JMS Bridge to Start at Broker Startup

Follow these steps to configure a JMS bridge so that it starts automatically when the broker hosting it is started.
1
Confirm that the bridge service manager is enabled. See To Enable the Bridge Service Manager on page 216 for instructions.
2 3
Add the name of the bridge to the imq.bridge.activelist broker property. Confirm that the imq.bridge.bridgeName.autostart broker property is set to true.
To Start a JMS Bridge Manually
Enter the imqbridgemgr start bridge command, specifying the bridge name and the broker. For example, to start the bridge mq2external hosted by the broker running on myhost:8886, enter this command:
imqbridgemgr start bridge -bn mq2external -b myhost:8886
To Stop a JMS Bridge Manually
Enter the imqbridgemgr stop bridge command, specifying the bridge name and the broker. For example, to stop the bridge mq2external hosted by the broker running on myhost:8886, enter this command:
imqbridgemgr stop bridge -bn mq2external -b myhost:8886
Starting and Stopping Links in a JMS Bridge

Links in a JMS bridge are started automatically when the bridge starts. Similarly, links are stopped automatically when the bridge is stopped. Additionally, once a JMS bridge is started, any of its links can be paused, resumed, stopped or restarted manually using the imqbridgemgr utility.
234
Configuring and Managing STOMP Bridge Services
To Stop a Link Manually
Enter the imqbridgemgr stop link command, specifying the link name, the bridge name, and the broker. For example, to stop the link link1 in the bridge mq2external hosted by the broker running on myhost:8886, enter this command:
imqbridgemgr stop link -ln link1 -bn mq2external -b myhost:8886
To Start a Link Manually

A link cannot be started manually unless it is enabled; that is, the enabled attribute of its link element in the bridge's XML configuration file is set to true.
Enter the imqbridgemgr start link command, specifying the link name, the bridge name, and the broker. For example, to start the link link1 in the bridge mq2external hosted by the broker running on myhost:8886, enter this command:
imqbridgemgr start link -ln link1 -bn mq2external -b myhost:8886

The STOMP (Streaming Text Oriented Messaging Protocol) open source project at http://stomp.codehaus.org defines a simple wire protocol that clients written in any language can use to communicate with any messaging provider that supports the STOMP protocol. Message Queue 4.4 provides support for the STOMP protocol through the STOMP bridge service. This service enables a Message Queue broker to communicate with STOMP clients. The STOMP bridge service provides the features needed to fully integrate STOMP messaging into the JMS messaging environment of Message Queue:
Registration with the Message Queue Port Mapper service so that STOMP clients can discover the service dynamically Support for TCP and SSL/TLS connections, including SSL/TLS connections requiring client authentication Automatic conversion of STOMP frame messages to and from JMS BytesMessage and TextMessage types Extensible message handling and transformation (by defining a custom message transformer) Support for the full STOMP protocol, including the STOMP JMS bindings
235
The following subsections provide information about the STOMP bridge and how to configure and manage it:

Configuring the STOMP Bridge on page 236 Starting and Stopping the STOMP Bridge on page 237 Message Processing Sequence Across the STOMP Bridge on page 237 STOMP Protocol Features and the STOMP Bridge on page 239
Configuring the STOMP Bridge

To configure the STOMP bridge, you specify several imq.bridge.stomp broker properties in the broker hosting the bridge. These properties, which control the various features of the STOMP bridge, are listed in Table 1210.
TABLE 1210
Broker Properties for the STOMP Bridge Service

Property
imq.bridge.stomp.tcp.enabled imq.bridge.stomp.tcp.port
Boolean Integer
true 7672
Does the STOMP bridge accept TCP connections? The port on which the STOMP bridge listens for TCP connections, provided that imq.bridge.stomp.tcp.enabled is true. Does the STOMP bridge accept SSL/TLS connections? If true, a keystore must be created using the imqkeytool utility before starting the broker.
imq.bridge.stomp.tls.enabled
Boolean
false
imq.bridge.stomp.tls.port
Integer
7673
The port on which the STOMP bridge listens for SSL/TLS connections, provided that imq.bridge.stomp.tls.enabled is true. Do SSL/TLS connections require client authentication? The maximum number of unacknowledged messages that the STOMP bridge will deliver on a transacted STOMP subscription. The STOMP client must then acknowledge the messages and commit the transaction. The fully qualified class name of a class that extends the Message Queue bridge MessageTransformer abstract class (with formal type parameters as javax.jms.Message). Place this class under the IMQ_HOME/lib/ext directory. The approximate maximum number of bytes the STOMP bridge writes to any one log file. A value of 0 (zero) indicates that there is no maximum limit.
imq.bridge.stomp.tls.requireClientAuth Boolean imq.bridge.stomp.consumerFlowLimit Integer
false 1000
imq.bridge.stomp.messageTransformer
String
None
imq.bridge.stomp.logfile.limit
Integer
236
TABLE 1210 Property

Type Default Value
(Continued)
Description
imq.bridge.stomp.logfile.count
Integer
The number of log files the STOMP bridge cycles through.
Starting and Stopping the STOMP Bridge

The STOMP bridge is started automatically when the broker hosting the bridge starts. Similarly, the STOMP bridge is stopped automatically when the broker hosting it is stopped. The STOMP bridge can be stopped and restarted manually using the imqbridgemgr utility.
To Activate the STOMP Bridge

1
Confirm that the bridge service manager is enabled. See To Enable the Bridge Service Manager on page 216 for instructions. Add the name stomp to the list of bridge names in the imq.bridge.activelist broker property.
To Stop the STOMP Bridge Manually
Enter the imqbridgemgr stop bridge command, specifying the bridge type and the broker. For example, to stop the STOMP bridge hosted by the broker running on myhost:8886, enter this command:
imqbridgemgr stop bridge -t STOMP -b myhost:8886
To Start the STOMP Bridge Manually
Enter the imqbridgemgr start bridge command, specifying the bridge type and the broker. For example, to start the STOMP bridge hosted by the broker running on myhost:8886, enter this command:
imqbridgemgr start bridge -t STOMP -b myhost:8886
Message Processing Sequence Across the STOMP Bridge

The STOMP bridge processes messages differently depending on whether the message is a STOMP frame message being received from a STOMP client or a JMS message being sent to a STOMP client.
For STOMP frame messages received from a STOMP client, the STOMP bridge performs these tasks: 1. Convert the STOMP frame message to a JMS BytesMessage if the content-length header is present; otherwise, convert it to a JMS TextMessage using UTF-8 as the message encoding. 2. If a custom message transformer is defined for the bridge, pass the JMS message to the transformer's MessageTransformer.transform() method. 3. Send the message to its destination. For JMS messages sent to a STOMP client, the STOMP bridge performs these tasks: 1. If a custom message transformer is defined for the bridge, pass the JMS message to the transformer's MessageTransformer.transform() method. 2. If the transformed message (or original message when no custom transformer is defined) is not a JMS TextMessage or JMS BytesMessage message, close the STOMP connection and stop processing the message. 3. Convert the JMS message to a STOMP frame message, using UTF-8 encoding for all headers and for the message body of a JMS TextMessage message. 4. Send the message to the STOMP client.
Message Transformation During Message Processing

The message transformation between STOMP frame messages and JMS messages that the STOMP bridge automatically provides is sufficient in most applications. However, if you need to perform special processing or to send JMS message types other than BytesMessage or TextMessage to STOMP clients, you can define a custom message transformer for the STOMP bridge. This custom message transformer is a Java class that extends the Message Queue Bridge MessageTransformer abstract class by implementing the class's transform() method. Then, place the class file in the IMQ_HOME/lib/ext directory and set the imq.bridge.stomp.messageTransformer broker property of the broker hosting the STOMP bridge to the fully qualified class name of the class. When implementing the transform() method, keep these points in mind:

The formal parameters T and S must be of type javax.jms.Message. " The source and target arguments will be either "STOMP" and "SUN_MQ" or "SUN_MQ" and "STOMP", respectively. A source argument value of "STOMP" indicates that the message argument is from a STOMP client SEND frame received by the STOMP bridge. A source argument value of "SUN_MQ" indicates that the message argument is from a Message Queue destination.
238
The readOnly argument will be false if the source argument is "STOMP" and true if the source argument is "SUN_MQ". If the source argument is "STOMP", the properties argument contains, as key/value pairs, any arbitrary user headers that the STOMP bridge was unable to convert to JMS message properties in the message argument. Otherwise, the properties argument is null. The charsetName argument should be ignored unless the source argument is "STOMP" and the message argument is a JMS BytesMessage message. This combination of argument values indicates that the message is from a STOMP client and has already been converted to a BytesMessage message. The returned message must be in write-only mode if the source argument is "STOMP" and in read-only mode if the source argument is "SUN_MQ".
STOMP Protocol Features and the STOMP Bridge

The STOMP bridge supports the full STOMP protocol, including all additional STOMP headers for the STOMP JMS bindings, as listed at http://stomp.codehaus.org/Stomp+JMS. The following table clarifies how the STOMP bridge handles certain command and header combinations that might be otherwise be subject to multiple interpretations.
TABLE 1211 STOMP Frame Command
STOMP Bridge Handling of Selected Command/Header Combinations

STOMP Frame Header Handling by the STOMP Bridge
CONNECT
login passcode
The STOMP bridge requires these headers to be specified; otherwise, it returns an ERROR frame.
239

(Continued)
SEND SUBSCRIBE UNSUBSCRIBE MESSAGE
destination
MQ STOMP bridge interprets prefixes in destination header values as follows: /queue/: the prefix is followed by the name of a Queue /topic/: the prefix is followed by the name of a Topic /temp-queue/: the prefix is followed by the name of a TemporaryQueue /temp-topic/: the prefix is followed by the name of a TemporaryTopic Note that the following two prefixes are reserved to be used only for send reply messages to a MESSAGE frame's replyto destination, and should only be used in the same CONNECT session in which the MESSAGE is received. /temp-queue/temporary_destination://queue/ /temp-topic/temporary_destination://topic/
SEND
expires priority persistent
When these headers are not specified for SEND, the message will be sent with the same default values as for a Message Queue Java client.
SEND
user specific headers
On SEND, a user can specify additional headers beyond the ones specified in the STOMP protocol and STOMP JMS Bindings. These headers are transformed to String properties of the converted JMS message. Therefore, the keys for these headers must be valid JMS property names. If any are not, and a custom message transformer is specified for STOMP bridge, the invalid ones are passed in the properties argument to the transformer's transform() method. Supported as described in the STOMP JMS Bindings on SUBSCRIBE.
SUBSCRIBE
selector
240

(Continued)
SUBSCRIBE
id
A STOMP client should always specify an id header for SUBSCRIBE. If no "id" header is specified, the STOMP bridge assigns it a default value of /subscription-to/STOMP-destination-name. All SUBSCRIBE id values must be unique in the scope of the STOMP client connection to the STOMP bridge; otherwise, an ERROR frame will be returned.
SUBSCRIBE
transaction
For a STOMP subscription to receive messages in a transaction, the SUBSCRIBE frame must specify a transaction header with a transaction identifier whose transaction state is started. If the transaction does not exist, an ERROR frame is returned. After the transaction completes (using either COMMIT or ABORT), message delivery to the transacted subscription is paused until the next transaction BEGIN. For transacted subscriptions, aborting a transaction will cause the STOMP bridge to stop message delivery to all transacted subscriptions in the CONNECT session. Then, upon the next BEGIN, the STOMP bridge restarts the message delivery sequence to all the transacted subscriptions in the CONNECT session, including all unconsumed messages that had been previously delivered. For STOMP ack:auto (the default), a subscribed message is considered acknowledged as soon as it is sent to the STOMP client. Unsubscribes a durable subscription, with these provisions: destination and id headers, if specfied, are ignored. An ERROR frame is returned if the connection (CONNECT) has no client-id. If an active subscriber with the durable name exists on the connection, it is first closed, and then the durable subscriber is unsubscribed.
ABORT
transaction
SUBSCRIBE
ack
UNSUBSCRIBE
durable-subscriber-name
241

(Continued)
BEGIN
transaction
Transactions are at STOMP CONNECT session level. Nested transactions are not supported. On attempts to start a nested transaction, an ERROR frame is returned. The transaction identifier will also be used for SUBSCRIBE frame to create a transacted subscription.
ACK
subscription
ACK should always specify a subscription header specifying the subscription id that the message to be acked was delivered to. If a subcriber id is not specified, the STOMP bridge default subscription id prefix is used to find the first matching subscription id with the prefix to ack the message. If the subscription for the specified subscription id was not created as transacted, and a transaction header is specified for the ACK, an ERROR frame is returned; ACK on a message ID, if found, will ACK all earlier messages delivered to the subscription in addition to the message with the given message ID.
ACK
transaction
For transacted subscription, an ACK for a message ID automatically ACKs all ealier messages sent to the transacted subscription in addition to the message with the given message ID. For transacted subscription, a message is considered consumed only when it is explicitly or implicitly ACKed in a transaction and there is a subsequent successful COMMIT on that transaction. If the transaction header is not specified but the subscription header is specified and the subscription is a transacted subscription, the message is ACKed in the current transaction if there is a current transaction. If there is no current transaction, an ERROR frame is returned. The STOMP bridge always sets the content-length header for MESSAGE and ERROR frames sent to STOMP clients.
MESSAGE ERROR
content-length
242

(Continued)
SEND MESSAGE
reply-to
The STOMP bridge permits SEND from different STOMP CONNECT sessions as well as from the same CONNECT session to send reply messages to a STOMP reply-to header of temporary destination: In the same CONNECT session, when SUBSCRIBE and SEND reply, use the same temporary destination string that is used in the SEND's reply-to header.
In a different CONNECT session, upon receiving a MESSAGE with a reply-to header of a temporary destination, use the same temporary destination string in the MESSAGE's reply-to header to SEND a reply to the reply-to temporary destination. This technique can also be used for sending the reply message when in the same CONNECT session.
243
244
13
C H A P T E R

1 3
Monitoring Broker Operations
This chapter describes the tools you can use to monitor a broker and how you can get metrics data. The chapter has the following sections: Monitoring Services on page 245 Introduction to Monitoring Tools on page 246 Configuring and Using Broker Logging on page 248 Using the Command Utility to Display Metrics Interactively on page 254 Using the JMX Administration API on page 259 Using the Java ES Monitoring Console on page 259 Using the Message-Based Monitoring API on page 260
Reference information on specific metrics is available in Chapter 21, Metrics Information Reference
Monitoring Services
The broker includes components for monitoring and diagnosing application and broker performance. These include the components and services shown in the following figure:

Broker code that logs broker events. A metrics generator that provides. The metrics generator provides information about broker activity, such as message flow in and out of the broker, the number of messages in broker memory and the memory they consume, the number of open connections, and the number of threads being used. The boolean broker property imq.metrics.enabled controls whether such information is logged and the imq.metrics.interval property specifies how often metrics information is generated.
A logger component that writes out information to a number of output channels. A comprehensive set of Java Management Extensions (JMX) MBeans that expose broker resources using the JMX API
245
Introduction to Monitoring Tools
Support for the Java ES Monitoring Framework A metrics message producer that sends JMS messages containing metrics information to topic destinations for consumption by JMS monitoring clients.
Broker properties for configuring the monitoring services are listed under Monitoring Properties on page 357.
FIGURE 131
Monitoring Services Support
Output Channels Broker Code Logger Log File

ERROR WARNING INFO
Console syslog (Solaris)
Metrics Generator Metrics Message Producer
Command Utility (imqcmd metrics) Topic Destinations
JMX MBeans
JMX Client Application
Broker Resources
Java ES Monitoring Framework
Java ES Monitoring Console

There are five tools (or interfaces) for monitoring Message Queue information, as described briefly below:

Log files provide a long-term record of metrics data, but cannot easily be parsed. The Command Utility (imqcmd metrics) lets you interactively sample information tailored to your needs, but does not provide historical information or allow you to manipulate the data programmatically.
246
The Java Management Extensions (JMX) Administration API lets you perform broker resource configuration and monitoring operations programmatically from within a Java application. You can write your own JMX administration application or use the standard Java Monitoring and Management Console (jconsole). The Sun Java Enterprise System Monitoring Framework (JESMF) and Monitoring Console offers a common, Web-based graphical interface shared with other Java ES components, but can monitor only a subset of all Message Queue entities and operations. The Message-based Monitoring API lets you extract metrics information from messages produced by the broker to metrics topic destinations. However, to use it, you must write a Message Queue client application to capture, analyze, and display the metrics data.
The following tabel compares the different tools.

TABLE 131
Benefits and Limitations of Metrics Monitoring Tools

Benefits

Metrics Monitoring Tool
Limitations

Log files
Regular sampling Creates a historical record
Local monitoring only Data format difficult to read; no parsing tools Need to configure broker properties; must shut down and restart broker to take effect Broker metrics only; no destination or connection service metrics No flexibility in selection of data Same reporting interval for all metrics data; cannot be changed on the fly Possible performance penalty if interval set too short Difficult to analyze data programmatically No single command gets all data No historical record; difficult to see historical trends
Command Utility (imqcmd metrics)
Remote monitoring Convenient for spot-checking Data presented in easy-to-read tabular format Easy to select specific data of interest Reporting interval set in command option; can be changed on the fly
Chapter 13 Monitoring Broker Operations
247
Configuring and Using Broker Logging
TABLE 131
Benefits and Limitations of Metrics Monitoring Tools

Benefits

(Continued)
Might need to configure broker's JMX support
Metrics Monitoring Tool
Limitations
JMX Administration API
Remote monitoring Data can be analyzed programmatically and presented in any format Easy to select specific data of interest Can use standard Java Monitoring and Management Console (jconsole) Web-based graphical interface Data presented in easy-to-read format Common interface shared with other JES components No performance penalty; pulls data from brokers existing data monitoring infrastructure Remote monitoring Data can be analyzed programmatically and presented in any format Easy to select specific data of interest
Java ES Monitoring Console
Limited subset of data available Data cannot be analyzed programmatically No historical record; difficult to see historical trends
Message-based Monitoring API
Need to configure broker properties; must shut down and restart broker to take effect Same reporting interval for all metrics data; cannot be changed on the fly
In addition to the differences shown in the table, each tool gathers a somewhat different subset of the metrics information generated by the broker. For information on which metrics data is gathered by each monitoring tool, see Chapter 21, Metrics Information Reference.

The Message Queue Logger takes information generated by broker code, a debugger, and a metrics generator and writes that information to a number of output channels: to standard output (the console), to a log file, and, on Solaris platforms, to the syslog daemon process. You can specify the type of information gathered by the Logger as well as the type of information the Logger writes to each of the output channels. For example, you can specify that you want metrics information written out to a log file.
248
This section describes the configuration and use of the Logger for monitoring broker activity. It includes the following topics:

Logger Properties on page 249 Log Message Format on page 249 Default Logging Configuration on page 250 Changing the Logging Configuration on page 251
Logger Properties
The imq.log.file.dirpath and imq.log.file.filename broker properties identify the log file to use and the imq.log.console.stream property specifies whether console output is directed to stdout or stderr. The imq.log.level property controls the categories of metric information that the Logger gathers: ERROR, WARNING, or INFO. Each level includes those above it, so if you specify, for example, WARNING as the logging level, error messages will be logged as well. There is also an imq.destination.logDeadMsgs property that specifies whether to log entries when dead messages are discarded or moved to the dead message queue. The imq.log.console.output and imq.log.file.output properties control which of the specified categories the Logger writes to the console and the log file, respectively. In this case, however, the categories do not include those above them; so if you want, for instance, both errors and warnings written to the log file and informational messages to the console, you must explicitly set imq.log.file.output to ERROR|WARNING and imq.log.console.output to INFO. On Solaris platforms another property, imq.log.syslog.output, specifies the categories of metric information to be written to the syslog daemon. In the case of a log file, you can specify the point at which the file is closed and output is rolled over to a new file. Once the log file reaches a specified size (imq.log.file.rolloverbytes) or age (imq.log.file.rolloversecs), it is saved and a new log file created. See Monitoring Properties on page 357 for additional broker properties related to logging and subsequent sections for details about how to configure the Logger and how to use it to obtain performance information.
Log Message Format

A logged message consists of a time stamp, a message code, and the message itself. The volume of information included varies with the logging level you have set. The broker supports three logging levels: ERROR, WARNING , and INFO (see Table 132). Each level includes those above it (for example, WARNING includes ERROR).
Chapter 13 Monitoring Broker Operations 249
TABLE 132
Logging Levels
Description
Logging Level
ERROR WARNING INFO
Serious problems that could cause system failure Conditions that should be heeded but will not cause system failure Metrics and other informational messages
The default logging level is INFO, so messages at all three levels are logged by default. The following is an example of an INFO message: [13/Sep/2000:16:13:36 PDT] [B1004]: Starting the broker service using tcp [25374,100] with min threads 50 and max threads of 500 You can change the time zone used in the time stamp by setting the broker configuration property imq.log.timezone (see Table 1711).
Default Logging Configuration

A broker is automatically configured to save log output to a set of rolling log files. The log files are located in a directory identified by the instance name of the associated broker (see Appendix A, Distribution-Specific Locations of Message Queue Data): .../instances/instanceName/log
Note For a broker whose life cycle is controlled by the Application Server, the log files are located in a subdirectory of the domain directory for the domain for which the broker was started:
.../appServerDomainDir/imq/instances/imqbroker/log The log files are simple text files. The system maintains nine backup files named as follows, from earliest to latest: log.txt log_1.txt log_2.txt ... log_9.txt By default, the log files are rolled over once a week. You can change this rollover interval, or the location or names of the log files, by setting appropriate configuration properties:
To change the directory in which the log files are kept, set the property imq.log.file.dirpath to the desired path.
250
To change the root name of the log files from log to something else, set the imq.log.file.filename property. To change the frequency with which the log files are rolled over, set the property imq.log.file.rolloversecs.
See Table 1711 for further information on these properties.
Changing the Logging Configuration

Log-related properties are described in Table 1711.
To Change the Logger Configuration for a Broker

1 2 3
Set the logging level. Set the output channel (file, console, or both) for one or more logging categories. If you log output to a file, configure the rollover criteria for the file. You complete these steps by setting Logger properties. You can do this in one of two ways:
Change or add Logger properties in the config.properties file for a broker before you start the broker. Specify Logger command line options in the imqbrokerd command that starts the broker. You can also use the broker option -D to change Logger properties (or any broker property).
Options passed on the command line override properties specified in the broker instance configuration files. The following imqbrokerd options affect logging: -metrics interval -loglevel level -silent -tty Logging interval for broker metrics, in seconds Logging level (ERROR, WARNING, INFO, or NONE) Silent mode (no logging to console) Log all messages to console
The following sections describe how you can change the default configuration in order to do the following:

Change the output channel (the destination of log messages) Change rollover criteria
Changing the Output Channel

By default, error and warning messages are displayed on the terminal as well as being logged to a log file. (On Solaris, error messages are also written to the systems syslog daemon.)
You can change the output channel for log messages in the following ways:
To have all log categories (for a given level) output displayed on the screen, use the -tty option to the imqbrokerd command. To prevent log output from being displayed on the screen, use the -silent option to the imqbrokerd command. Use the imq.log.file.output property to specify which categories of logging information should be written to the log file. For example,
imq.log.file.output=ERROR
Use the imq.log.console.output property to specify which categories of logging information should be written to the console. For example,
imq.log.console.output=INFO
On Solaris, use the imq.log.syslog.output property to specify which categories of logging information should be written to Solaris syslog. For example,
imq.log.syslog.output=NONE
Note Before changing Logger output channels, you must make sure that logging is set at a level that supports the information you are mapping to the output channel. For example, if you set the logging level to ERROR and then set the imq.log.console.output property to WARNING, no messages will be logged because you have not enabled the logging of WARNING messages.
Changing Log File Rollover Criteria

There are two criteria for rolling over log files: time and size. The default is to use a time criteria and roll over files every seven days.
To change the time interval, you need to change the property imq.log.file.rolloversecs. For example, the following property definition changes the time interval to ten days:
imq.log.file.rolloversecs=864000
To change the rollover criteria to depend on file size, you need to set the imq.log.file.rolloverbytes property. For example, the following definition directs the broker to rollover files after they reach a limit of 500,000 bytes
imq.log.file.rolloverbytes=500000
If you set both the time-related and the size-related rollover properties, the first limit reached will trigger the rollover. As noted before, the broker maintains up to nine rollover files. You can set or change the log file rollover properties when a broker is running. To set these properties, use the imqcmd update bkr command.
252
Sending Metrics Data to Log Files

This section describes the procedure for using broker log files to report metrics information. For general information on configuring the Logger, see Configuring and Using Broker Logging on page 248.
To Use Log Files to Report Metrics Information

1
Configure the brokers metrics generation capability: a. Confirm imq.metrics.enabled=true Generation of metrics for logging is turned on by default. b. Set the metrics generation interval to a convenient number of seconds. imq.metrics.interval=interval This value can be set in the config.properties file or using the -metrics interval command line option when starting up the broker.
Confirm that the Logger gathers metrics information:

imq.log.level=INFO
This is the default value. This value can be set in the config.properties file or using the -loglevel level command line option when starting up the broker.
3
Confirm that the Logger is set to write metrics information to the log file:
imq.log.file.output=INFO
This is the default value. It can be set in the config.properties file.

4
Start up the broker. The following shows sample broker metrics output to the log file:
[21/Jul/2004:11:21:18 PDT] Connections: 0 JVM Heap: 8323072 bytes (7226576 free) Threads: 0 (14-1010) In: 0 msgs (0bytes) 0 pkts (0 bytes) Out: 0 msgs (0bytes) 0 pkts (0 bytes) Rate In: 0 msgs/sec (0 bytes/sec) 0 pkts/sec (0 bytes/sec) Rate Out: 0 msgs/sec (0 bytes/sec) 0 pkts/sec (0 bytes/sec)
For reference information about metrics data, see Chapter 21, Metrics Information Reference
Logging Dead Messages

You can monitor physical destinations by enabling dead message logging for a broker. You can log dead messages whether or not you are using a dead message queue.
Using the Command Utility to Display Metrics Interactively
If you enable dead message logging, the broker logs the following types of events:

A physical destination exceeded its maximum size. The broker removed a message from a physical destination, for a reason such as the following:

The destination size limit has been reached. The message time to live expired. The message is too large. An error occurred when the broker attempted to process the message.
If a dead message queue is in use, logging also includes the following types of events:

The broker moved a message to the dead message queue. The broker removed a message from the dead message queue and discarded it.
The following is an example of the log format for dead messages:

[29/Mar/2006:15:35:39 PST] [B1147]: Message 8-129.145.180.87(e7:6b:dd:5d:98:aa)35251-1143675279400 from destination Q:q0 has been placed on the DMQ because [B0053]: Message on destination Q:q0 Expired: expiration time 1143675279402, arrival time 1143675279401, JMSTimestamp 1143675279400
Dead message logging is disabled by default. To enable it, set the broker attribute imq.destination.logDeadMsgs.

A Message Queue broker can report metrics of the following types:

Java Virtual Machine (JVM) metrics. Information about the JVM heap size. Brokerwide metrics. Information about messages stored in a broker, message flows into and out of a broker, and memory use. Messages are tracked in terms of numbers of messages and numbers of bytes. Connection Service metrics. Information about connections and connection thread resources, and information about message flows for a particular connection service. Destination metrics. Information about message flows into and out of a particular physical destination, information about a physical destinations consumers, and information about memory and disk space usage.
The imqcmd command can obtain metrics information for the broker as a whole, for individual connection services, and for individual physical destinations. To obtain metrics data, you generally use the metrics subcommand of imqcmd. Metrics data is written at an interval you specify, or the number of times you specify, to the console screen.
254
You can also use the query subcommand to view similar data that also includes configuration information. See imqcmd query on page 258 for more information.
imqcmd metrics
The syntax and options of imqcmd metrics are shown in Table 133 and Table 134, respectively.
TABLE 133
imqcmd metrics Subcommand Syntax

Metrics Data Provided
Subcommand Syntax
metrics bkr [-b hostName:portNumber] [-m metricType] [-int interval] [-msp numSamples] metrics svc -n serviceName [-b hostName:portNumber] [-m metricType] [-int interval] [-msp numSamples] metrics dst -t destType -n destName [-b hostName:portNumber] [-m metricType] [-int interval] [-msp numSamples]
TABLE 134
Displays broker metrics for the default broker or a broker at the specified host and port.
Displays metrics for the specified service on the default broker or on a broker at the specified host and port.
Displays metrics information for the physical destination of the specified type and name.
imqcmd metrics Subcommand Options

Description
Subcommand Options
-b hostName: portNumber -int interval
Specifies the hostname and port of the broker for which metrics data is reported. The default is localhost:7676. Specifies the interval (in seconds) at which to display the metrics. The default is 5 seconds.
255
TABLE 134
imqcmd metrics Subcommand Options

Description
(Continued)
Subcommand Options
-m metricType
Specifies the type of metric to display: ttl Displays metrics on messages and packets flowing into and out of the broker, service, or destination (default metric type). rts Displays metrics on rate of flow of messages and packets into and out of the broker, connection service, or destination (per second). cxn Displays connections, virtual memory heap, and threads (brokers and connection services only). con Displays consumer-related metrics (destinations only). dsk Displays disk usage metrics (destinations only).
-msp numSamples -n destName -n serviceName -t destType
Specifies the number of samples displayed in the output. The default is an unlimited number (infinite). Specifies the name of the physical destination (if any) for which metrics data is reported. There is no default. Specifies the connection service (if any) for which metrics data is reported. There is no default. Specifies the type (queue or topic) of the physical destination (if any) for which metrics data is reported. There is no default.
To Use the metrics Subcommand

1
Start the broker for which metrics information is desired. See Starting Brokers on page 70. Issue the appropriate imqcmd metrics subcommand and options as shown in Table 133 and Table 134.
Metrics Outputs: imqcmd metrics

This section contains examples of output for the imqcmd metrics subcommand. The examples show brokerwide, connection service, and physical destination metrics.
Brokerwide Metrics
To get the rate of message and packet flow into and out of the broker at 10 second intervals, use the metrics bkr subcommand:
imqcmd metrics bkr -m rts -int 10 -u admin
This command produces output similar to the following (see data descriptions in Table 212):
-------------------------------------------------------Msgs/sec Msg Bytes/sec Pkts/sec Pkt Bytes/sec In Out In Out In Out In Out -------------------------------------------------------0 0 27 56 0 0 38 66 10 0 7365 56 10 10 7457 1132 0 0 27 56 0 0 38 73 0 10 27 7402 10 20 1400 8459 0 0 27 56 0 0 38 73
Connection Service Metrics

To get cumulative totals for messages and packets handled by the jms connection service, use the metrics svc subcommand:
imqcmd metrics svc -n jms -m ttl -u admin
------------------------------------------------Msgs Msg Bytes Pkts Pkt Bytes In Out In Out In Out In Out ------------------------------------------------164 100 120704 73600 282 383 135967 102127 657 100 483552 73600 775 876 498815 149948
Physical Destination Metrics

To get metrics information about a physical destination, use the metrics dst subcommand:
imqcmd metrics dst -t q -n XQueue -m ttl -u admin
----------------------------------------------------------------------------Msgs Msg Bytes Msg Count Total Msg Bytes (k) Largest In Out In Out Current Peak Avg Current Peak Avg Msg (k) ----------------------------------------------------------------------------200 200 147200 147200 0 200 0 0 143 71 0 300 200 220800 147200 100 200 10 71 143 64 0 300 300 220800 220800 0 200 0 0 143 59 0
To get information about a physical destinations consumers, use the following metrics dst subcommand:
imqcmd metrics dst -t q -n SimpleQueue -m con -u admin
-----------------------------------------------------------------Active Consumers Backup Consumers Msg Count Current Peak Avg Current Peak Avg Current Peak Avg -----------------------------------------------------------------1 1 0 0 0 0 944 1000 525
imqcmd query
The syntax and options of imqcmd query are shown in Table 135 along with a description of the metrics data provided by the command.
TABLE 135
imqcmd query Subcommand Syntax

Metrics Data Provided
Subcommand Syntax
query bkr [-b hostName: portNumber] or query svc -n serviceName [-b hostName:portNumber] or query dst -t destType -n destName [-b hostName:portNumber]
Information on the current number of messages and message bytes stored in broker memory and persistent store (see Viewing Broker Information on page 92).
Information on the current number of allocated threads and number of connections for a specified connection service (see Viewing Connection Service Information on page 101).
Information on the current number of producers, active and backup consumers, and messages and message bytes stored in memory and persistent store for a specified destination (see Viewing Physical Destination Information on page 114).
Note Because of the limited metrics data provided by imqcmd query , this tool is not represented in the tables presented in Chapter 21, Metrics Information Reference.
258
Using the Java ES Monitoring Console
Using the JMX Administration API

The broker implements a comprehensive set of Java Management Extensions (JMX) MBeans that represent the broker's manageable resources. Using the JMX API, you can access these MBeans to perform broker configuration and monitoring operations programmatically from within a Java application. In this way, the MBeans provide a Java application access to data values representing static or dynamic properties of a broker, connection, destination, or other resource. The application can also receive notifications of state changes or other significant events affecting the resource. JMX-based administration provides dynamic, fine grained, programmatic access to the broker. You can use this kind of administration in a number of ways.
You can include JMX code in your JMS client application to monitor application performance and, based on the results, to reconfigure the Message Queue resources you use to improve performance. You can write JMX client applications that monitor the broker to identify use patterns and performance problems, and you can use the JMX API to reconfigure the broker to optimize performance. You can write a JMX client application to automate regular maintenance tasks. You can write a JMX client application that constitutes your own version of the Command utility (imqcmd), and you can use it instead of imqcmd. You can use the standard Java Monitoring and Management Console (jconsole) that can provide access to the broker's MBeans.
For information on JMX infrastructure and configuring the broker's JMX support, see Appendix D, JMX Support. To manage a Message Queue broker using the JMX architecture, see Sun GlassFish Message Queue 4.4 Developers Guide for JMX Clients.
Using the Java ES Monitoring Console

Message Queue supports the Sun Java System Monitoring Framework (JESMF), which allows Java Enterprise System (Java ES) components to be monitored using a common graphical interface, the Sun Java System Monitoring Console. Administrators can use the Monitoring Console to view performance statistics, create rules for automatic monitoring, and acknowledge alarms. If you are running Message Queue along with other Java ES components, you may find it more convenient to use a single interface to manage all of them. The Java ES Monitoring Framework defines a common data model, the Common Monitoring Model (CMM), to be used by all Java ES component products. This model enables a centralized and uniform view of all Java ES components. Message Queue exposes the following objects through the Common Monitoring Model:
Using the Message-Based Monitoring API
The installed product The broker instance name The broker Port Mapper Each connection service Each physical destination The persistent data store The user repository
Each of these objects is mapped to a CMM object whose attributes can be monitored using the Java ES Monitoring Console. The reference tables in Chapter 22, JES Monitoring Framework Reference, identify those attributes that are available for JESMF monitoring. For detailed information about the mapping of Message Queue objects to CMM objects, see the Sun Java Enterprise System Monitoring Guide. To enable JESMF monitoring, you must do the following: 1. Enable and configure the Monitoring Framework for all of your monitored components, as described in the Sun Java Enterprise System Monitoring Guide. 2. 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 Java ES Monitoring Framework will not affect broker performance, because all the work of gathering metrics is done by the Monitoring Framework, which pulls data from the brokers existing data monitoring infrastructure. For information on metric information provided by the Java ES Monitoring Framework, see Chapter 22, JES Monitoring Framework Reference.

Message Queue provides a Metrics Message Producer, which receives information from the Metrics Generator at regular intervals and writes the information into metrics messages,. The Metrics Message Producer then sends these messages to one of a number of metric topic destinations, depending on the type of metric information contained in the messages. You can access this metrics information by writing a client application that subscribes to the metrics topic destinations, consumes the messages in these destinations, and processes the metrics information contained in the messages. This allows you to create custom monitoring tools to support messaging applications. For details of the metric quantities reported in each type of metrics message, see Chapter 4, Using the Metrics Monitoring API, in Sun GlassFish Message Queue 4.4 Developers Guide for Java Clients There are five metrics topic destinations, whose names are shown in Table 136, along with the type of metrics messages delivered to each destination.
TABLE 136 Topic Name
Metrics Topic Destinations

Description
mq.metrics.broker mq.metrics.jvm mq.metrics.destination_list mq.metrics.destination.queue.queueName mq.metrics.destination.topic.topicName
Broker metrics Java Virtual Machine metrics List of destinations and their types Destination metrics for queue queueName Destination metrics for topic topicName
The broker properties imq.metrics.topic.enabled and imq.metrics.topic.interval control, respectively, whether messages are sent to metric topic destinations and how often. The imq.metrics.topic.timetolive and imq.metrics.topic.persist properties specify the lifetime of such messages and whether they are persistent. Besides the information contained in the body of a metrics message, the header of each message includes properties that provide the following additional information:

The message type The address (host name and port number) of the broker that sent the message The time the metric sample was taken
These properties are useful to client applications that process metrics messages of different types or from different brokers.
Setting Up Message-Based Monitoring

This section describes the procedure for using the message-based monitoring capability to gather metrics information. The procedure includes both client development and administration tasks.
To Set Up Message-based Monitoring

1
Write a metrics monitoring client. See the Message Queue Developers Guide for Java Clients for instructions on programming clients that subscribe to metrics topic destinations, consume metrics messages, and extract the metrics data from these messages. Configure the brokers Metrics Message Producer by setting broker property values in the config.properties file: a. Enable metrics message production. Set imq.metrics.topic.enabled=true
The default value is true. b. Set the interval (in seconds) at which metrics messages are generated. Set imq.metrics.topic.interval=interval . The default is 60 seconds. c. Specify whether you want metrics messages to be persistent (that is, whether they will survive a broker failure). Set imq.metrics.topic.persist . The default is false. d. Specify how long you want metrics messages to remain in their respective destinations before being deleted. Set imq.metrics.topic.timetolive . The default value is 300 seconds.
3
Set any access control you desire on metrics topic destinations. See the discussion in Security and Access Considerations on page 262 below. Start up your metrics monitoring client. When consumers subscribe to a metrics topic, the metrics topic destination will automatically be created. Once a metrics topic has been created, the brokers metrics message producer will begin sending metrics messages to the metrics topic.
Security and Access Considerations

There are two reasons to restrict access to metrics topic destinations:

Metrics data might include sensitive information about a broker and its resources. Excessive numbers of subscriptions to metrics topic destinations might increase broker overhead and negatively affect performance.
Because of these considerations, it is advisable to restrict access to metrics topic destinations. Monitoring clients are subject to the same authentication and authorization control as any other client. Only users maintained in the Message Queue user repository are allowed to connect to the broker. You can provide additional protections by restricting access to specific metrics topic destinations through an access control file, as described in User Authorization on page 155. For example, the following entries in an accesscontrol.properties file will deny access to the mq.metrics.broker metrics topic to everyone except user1 and user 2.
topic.mq.metrics.broker.consume.deny.user=* topic.mq.metrics.broker.consume.allow.user=user1,user2
The following entries will only allow users user3 to monitor topic t1.
topic.mq.metrics.destination.topic.t1.consume.deny.user=* topic.mq.metrics.destination.topic.t1.consume.allow.user=user3
Depending on the sensitivity of metrics data, you can also connect your metrics monitoring client to a broker using an encrypted connection. For information on using encrypted connections, see Message Encryption on page 161.
Metrics Outputs: Metrics Messages

The metrics data outputs you get using the message-based monitoring API is a function of the metrics monitoring client you write. You are limited only by the data provided by the metrics generator in the broker. For a complete list of this data, see Chapter 21, Metrics Information Reference.
263
264
14
C H A P T E R

1 4
Analyzing and Tuning a Message Service
This chapter covers a number of topics about how to analyze and tune a Message Queue service to optimize the performance of your messaging applications. It includes the following topics: About Performance on page 265 Factors Affecting Performance on page 268 Adjusting Configuration To Improve Performance on page 278
About Performance
This section provides some background information on performance tuning.
The Performance Tuning Process

The performance you get out of a messaging application depends on the interaction between the application and the Message Queue service. Hence, maximizing performance requires the combined efforts of both the application developer and the administrator. The process of optimizing performance begins with application design and continues on through tuning the message service after the application has been deployed. The performance tuning process includes the following stages:

Defining performance requirements for the application Designing the application taking into account factors that affect performance (especially tradeoffs between reliability and performance) Establishing baseline performance measures Tuning or reconfiguring the message service to optimize performance
The process outlined above is often iterative. During deployment of the application, a Message Queue administrator evaluates the suitability of the message service for the applications general performance requirements. If the benchmark testing meets these requirements, the
265
About Performance
administrator can tune the system as described in this chapter. However, if benchmark testing does not meet performance requirements, a redesign of the application might be necessary or the deployment architecture might need to be modified.
Aspects of Performance
In general, performance is a measure of the speed and efficiency with which a message service delivers messages from producer to consumer. However, there are several different aspects of performance that might be important to you, depending on your needs. Connection Load Message throughput Latency Stability Efficiency The number of message producers, or message consumers, or the number of concurrent connections a system can support. The number of messages or message bytes that can be pumped through a messaging system per second. The time it takes a particular message to be delivered from message producer to message consumer. The overall availability of the message service or how gracefully it degrades in cases of heavy load or failure. The efficiency of message delivery; a measure of message throughput in relation to the computing resources employed.
These different aspects of performance are generally interrelated. If message throughput is high, that means messages are less likely to be backlogged in the broker, and as a result, latency should be low (a single message can be delivered very quickly). However, latency can depend on many factors: the speed of communication links, broker processing speed, and client processing speed, to name a few. In any case, the aspects of performance that are most important to you generally depends on the requirements of a particular application.
Benchmarks
Benchmarking is the process of creating a test suite for your messaging application and of measuring message throughput or other aspects of performance for this test suite. For example, you could create a test suite by which some number of producing clients, using some number of connections, sessions, and message producers, send persistent or nonpersistent messages of a standard size to some number of queues or topics (all depending on your messaging application design) at some specified rate. Similarly, the test suite includes some number of consuming clients, using some number of connections, sessions, and message
About Performance
consumers (of a particular type) that consume the messages in the test suites physical destinations using a particular acknowledgment mode. Using your standard test suite you can measure the time it takes between production and consumption of messages or the average message throughput rate, and you can monitor the system to observe connection thread usage, message storage data, message flow data, and other relevant metrics. You can then ramp up the rate of message production, or the number of message producers, or other variables, until performance is negatively affected. The maximum throughput you can achieve is a benchmark for your message service configuration. Using this benchmark, you can modify some of the characteristics of your test suite. By carefully controlling all the factors that might have an effect on performance (see Application Design Factors Affecting Performance on page 270), you can note how changing some of these factors affects the benchmark. For example, you can increase the number of connections or the size of messages five-fold or ten-fold, and note the effect on performance. Conversely, you can keep application-based factors constant and change your broker configuration in some controlled way (for example, change connection properties, thread pool properties, JVM memory limits, limit behaviors, file-based versus JDBC-based persistence, and so forth) and note how these changes affect performance. This benchmarking of your application provides information that can be valuable when you want to increase the performance of a deployed application by tuning your message service. A benchmark allows the effect of a change or a set of changes to be more accurately predicted. As a general rule, benchmarks should be run in a controlled test environment and for a long enough period of time for your message service to stabilize. (Performance is negatively affected at startup by the just-in-time compilation that turns Java code into machine code.)
Baseline Use Patterns

Once a messaging application is deployed and running, it is important to establish baseline use patterns. You want to know when peak demand occurs and you want to be able to quantify that demand. For example, demand normally fluctuates by number of end users, activity levels, time of day, or all of these. To establish baseline use patterns you need to monitor your message service over an extended period of time, looking at data such as the following:

Number of connections Number of messages stored in the broker (or in particular physical destinations) Message flows into and out of a broker (or particular physical destinations) Numbers of active consumers
Chapter 14 Analyzing and Tuning a Message Service
267
Factors Affecting Performance
You can also use average and peak values provided in metrics data. It is important to check these baseline metrics against design expectations. By doing so, you are checking that client code is behaving properly: for example, that connections are not being left open or that consumed messages are not being left unacknowledged. These coding errors consume broker resources and could significantly affect performance. The base-line use patterns help you determine how to tune your system for optimal performance. For example:
If one physical destination is used significantly more than others, you might want to set higher message memory limits on that physical destination than on others, or to adjust limit behaviors accordingly. If the number of connections needed is significantly greater than allowed by the maximum thread pool size, you might want to increase the thread pool size or adopt a shared thread model. If peak message flows are substantially greater than average flows, that might influence the limit behaviors you employ when memory runs low.
In general, the more you know about use patterns, the better you are able to tune your system to those patterns and to plan for future needs.

Message latency and message throughput, two of the main performance indicators, generally depend on the time it takes a typical message to complete various steps in the message delivery process. These steps are shown below for the case of a persistent, reliably delivered message. The steps are described following the illustration.
268
FIGURE 141
Message Delivery Through a Message Queue Service
Broker
1 2 3 4 5 MyQDest 8 9 10 6 Consuming Client 7 Client Runtime Data Store
Producing Client Client Runtime
Payload messages Control messages
Message Delivery Steps

1. The message is delivered from producing client to broker. 2. The broker reads in the message. 3. The message is placed in persistent storage (for reliability). 4. The broker confirms receipt of the message (for reliability). 5. The broker determines the routing for the message. 6. The broker writes out the message. 7. The message is delivered from broker to consuming client. 8. The consuming client acknowledges receipt of the message (for reliability). 9. The broker processes client acknowledgment (for reliability). 10. The broker confirms that client acknowledgment has been processed. Since these steps are sequential, any one of them can be a potential bottleneck in the delivery of messages from producing clients to consuming clients. Most of the steps depend on physical
269
characteristics of the messaging system: network bandwidth, computer processing speeds, message service architecture, and so forth. Some, however, also depend on characteristics of the messaging application and the level of reliability it requires. The following subsections discuss the effect of both application design factors and messaging system factors on performance. While application design and messaging system factors closely interact in the delivery of messages, each category is considered separately.
Application Design Factors Affecting Performance

Application design decisions can have a significant effect on overall messaging performance. The most important factors affecting performance are those that affect the reliability of message delivery. Among these are the following:

Delivery Mode (Persistent/Nonpersistent Messages) on page 271 Use of Transactions on page 271 Acknowledgment Mode on page 272 Durable and Nondurable Subscriptions on page 273
Other application design factors affecting performance are the following:

Use of Selectors (Message Filtering) on page 273 Message Size on page 273 Message Body Type on page 274
The sections that follow describe the effect of each of these factors on messaging performance. As a general rule, there is a tradeoff between performance and reliability: factors that increase reliability tend to decrease performance. Table 141 shows how the various application design factors generally affect messaging performance. The table shows two scenariosone high-reliability, low-performance, and one high-performance, low-reliabilityand the choices of application design factors that characterize each. Between these extremes, there are many choices and tradeoffs that affect both reliability and performance.
TABLE 141
Comparison of High-Reliability and High-Performance Scenarios

High-Reliability, Low-Performance Scenario High-Performance, Low-Reliability Scenario
Application Design Factor
Delivery mode Use of transactions Acknowledgment mode
Persistent messages Transacted sessions AUTO_ACKNOWLEDGE or CLIENT_ACKNOWLEDGE
Nonpersistent messages No transactions DUPS_OK_ACKNOWLEDGE
270
TABLE 141
Comparison of High-Reliability and High-Performance Scenarios

High-Reliability, Low-Performance Scenario
(Continued)
High-Performance, Low-Reliability Scenario
Application Design Factor
Durable/nondurable subscriptions Use of selectors Message size Message body type
Durable subscriptions Message filtering Large number of small messages Complex body types
Nondurable subscriptions No message filtering Small number of large messages Simple body types
Delivery Mode (Persistent/Nonpersistent Messages)

Persistent messages guarantee message delivery in case of broker failure. The broker stores the message in a persistent store until all intended consumers acknowledge they have consumed the message. Broker processing of persistent messages is slower than for nonpersistent messages for the following reasons:
A broker must reliably store a persistent message so that it will not be lost should the broker fail. The broker must confirm receipt of each persistent message it receives. Delivery to the broker is guaranteed once the method producing the message returns without an exception. Depending on the client acknowledgment mode, the broker might need to confirm a consuming clients acknowledgment of a persistent message.
For both queues and topics with durable subscribers, performance was approximately 40% faster for nonpersistent messages. We obtained these results using 10k-sized messages and AUTO_ACKNOWLEDGE mode.
Use of Transactions
A transaction is a guarantee that all messages produced in a transacted session and all messages consumed in a transacted session will be either processed or not processed (rolled back) as a unit. Message Queue supports both local and distributed transactions. A message produced or acknowledged in a transacted session is slower than in a nontransacted session for the following reasons:

Additional information must be stored with each produced message. In some situations, messages in a transaction are stored when normally they would not be (for example, a persistent message delivered to a topic destination with no subscriptions would normally be deleted, however, at the time the transaction is begun, information about subscriptions is not available).
271
Information on the consumption and acknowledgment of messages within a transaction must be stored and processed when the transaction is committed.
Note To improve performance, Message Queue message brokers are configured by default to
use a memory-mapped file to store transaction data. On file systems that do not support memory-mapped files, you can disable this behavior by setting the broker property imq.persist.file.transaction.memorymappedfile.enabled to false.
Acknowledgment Mode
One mechanism for ensuring the reliability of JMS message delivery is for a client to acknowledge consumption of messages delivered to it by the Message Queue broker. If a session is closed without the client acknowledging the message or if the broker fails before the acknowledgment is processed, the broker redelivers that message, setting a JMSRedelivered flag. For a nontransacted session, the client can choose one of three acknowledgment modes, each of which has its own performance characteristics:
AUTO_ACKNOWLEDGE. The system automatically acknowledges a message once the consumer has processed it. This mode guarantees at most one redelivered message after a provider failure. CLIENT_ACKNOWLEDGE. The application controls the point at which messages are acknowledged. All messages processed in that session since the previous acknowledgment are acknowledged. If the broker fails while processing a set of acknowledgments, one or more messages in that group might be redelivered. DUPS_OK_ACKNOWLEDGE. This mode instructs the system to acknowledge messages in a lazy manner. Multiple messages can be redelivered after a provider failure.
(Using CLIENT_ACKNOWLEDGE mode is similar to using transactions, except there is no guarantee that all acknowledgments will be processed together if a provider fails during processing.) Acknowledgment mode affects performance for the following reasons:
Extra control messages between broker and client are required in AUTO_ACKNOWLEDGE and CLIENT_ACKNOWLEDGE modes. The additional control messages add additional processing overhead and can interfere with JMS payload messages, causing processing delays. In AUTO_ACKNOWLEDGE and CLIENT_ACKNOWLEDGE modes, the client must wait until the broker confirms that it has processed the clients acknowledgment before the client can consume additional messages. (This broker confirmation guarantees that the broker will not inadvertently redeliver these messages.) The Message Queue persistent store must be updated with the acknowledgment information for all persistent messages received by consumers, thereby decreasing performance.
272
Durable and Nondurable Subscriptions

Subscribers to a topic destination fall into two categories, those with durable and nondurable subscriptions. Durable subscriptions provide increased reliability but slower throughput, for the following reasons:
The Message Queue message service must persistently store the list of messages assigned to each durable subscription so that should a broker fail, the list is available after recovery. Persistent messages for durable subscriptions are stored persistently, so that should a broker fail, the messages can still be delivered after recovery, when the corresponding consumer becomes active. By contrast, persistent messages for nondurable subscriptions are not stored persistently (should a broker fail, the corresponding consumer connection is lost and the message would never be delivered).
We compared performance for durable and nondurable subscribers in two cases: persistent and nonpersistent 10k-sized messages. Both cases use AUTO_ACKNOWLEDGE acknowledgment mode. We found an effect on performance only in the case of persistent messages which slowed durables by about 30%
Use of Selectors (Message Filtering)

Application developers often want to target sets of messages to particular consumers. They can do so either by targeting each set of messages to a unique physical destination or by using a single physical destination and registering one or more selectors for each consumer. A selector is a string requesting that only messages with property values that match the string are delivered to a particular consumer. For example, the selector NumberOfOrders >1 delivers only the messages with a NumberOfOrders property value of 2 or more. Creating consumers with selectors lowers performance (as compared to using multiple physical destinations) because additional processing is required to handle each message. When a selector is used, it must be parsed so that it can be matched against future messages. Additionally, the message properties of each message must be retrieved and compared against the selector as each message is routed. However, using selectors provides more flexibility in a messaging application.
Message Size
Message size affects performance because more data must be passed from producing client to broker and from broker to consuming client, and because for persistent messages a larger message must be stored. However, by batching smaller messages into a single message, the routing and processing of individual messages can be minimized, providing an overall performance gain. In this case, information about the state of individual messages is lost.
Chapter 14 Analyzing and Tuning a Message Service 273
In our tests, which compared throughput in kilobytes per second for 1k, 10k, and 100k-sized messages to a queue destination and AUTO_ACKNOWLEDGE acknowledgment mode, we found that nonpersistent messaging was about 50% faster for 1k messages, about 20% faster for 10k messages, and about 5% faster for 100k messages. The size of the message affected performance significantly for both persistent and nonpersistent messages. 100k messages are about 10 times faster than 10k, and 10k are about 5 times faster than 1k.
Message Body Type

JMS supports five message body types, shown below roughly in the order of complexity:

BytesMessage contains a set of bytes in a format determined by the application. TextMessage is a simple Java string. StreamMessage contains a stream of Java primitive values. MapMessage contains a set of name-value pairs. ObjectMessage contains a Java serialized object.
While, in general, the message type is dictated by the needs of an application, the more complicated types (MapMessage and ObjectMessage) carry a performance cost: the expense of serializing and deserializing the data. The performance cost depends on how simple or how complicated the data is.
Message Service Factors Affecting Performance

The performance of a messaging application is affected not only by application design, but also by the message service performing the routing and delivery of messages. The following sections discuss various message service factors that can affect performance. Understanding the effect of these factors is key to sizing a message service and diagnosing and resolving performance bottlenecks that might arise in a deployed application. The most important factors affecting performance in a Message Queue service are the following:

Hardware on page 275 Operating System on page 275 Java Virtual Machine (JVM) on page 275 Connections on page 275 Broker Limits and Behaviors on page 277 Message Service Architecture on page 277 Data Store Performance on page 277 Client Runtime Configuration on page 278
The sections below describe the effect of each of these factors on messaging performance.
Hardware
For both the Message Queue broker and client applications, CPU processing speed and available memory are primary determinants of message service performance. Many software limitations can be eliminated by increasing processing power, while adding memory can increase both processing speed and capacity. However, it is generally expensive to overcome bottlenecks simply by upgrading your hardware.
Operating System
Because of the efficiencies of different operating systems, performance can vary, even assuming the same hardware platform. For example, the thread model employed by the operating system can have an important effect on the number of concurrent connections a broker can support. In general, all hardware being equal, Solaris is generally faster than Linux, which is generally faster than Windows.
Java Virtual Machine (JVM)

The broker is a Java process that runs in and is supported by the host JVM. As a result, JVM processing is an important determinant of how fast and efficiently a broker can route and deliver messages. In particular, the JVMs management of memory resources can be critical. Sufficient memory has to be allocated to the JVM to accommodate increasing memory loads. In addition, the JVM periodically reclaims unused memory, and this memory reclamation can delay message processing. The larger the JVM memory heap, the longer the potential delay that might be experienced during memory reclamation.
Connections
The number and speed of connections between client and broker can affect the number of messages that a message service can handle as well as the speed of message delivery.
Broker Connection Limits

All access to the broker is by way of connections. Any limit on the number of concurrent connections can affect the number of producing or consuming clients that can concurrently use the broker. The number of connections to a broker is generally limited by the number of threads available. Message Queue can be configured to support either a dedicated thread model or a shared thread model (see Thread Pool Management on page 98). The dedicated thread model is very fast because each connection has dedicated threads, however the number of connections is limited by the number of threads available (one input thread and one output thread for each connection). The shared thread model places no limit on the number of connections, however there is significant overhead and throughput delays in sharing threads among a number of connections, especially when those connections are busy.
Transport Protocols
Message Queue software allows clients to communicate with the broker using various low-level transport protocols. Message Queue supports the connection services (and corresponding protocols) described in Configuring Connection Services on page 95. The choice of protocols is based on application requirements (encrypted, accessible through a firewall), but the choice affects overall performance.
FIGURE 142
Transport Protocol Speeds
HTTPS
HTTP
SSL
TCP
SLOW
FAST
Our tests compared throughput for TCP and SSL for two cases: a high-reliability scenario (1k persistent messages sent to topic destinations with durable subscriptions and using AUTO_ACKNOWLEDGE acknowledgment mode) and a high-performance scenario (1k nonpersistent messages sent to topic destinations without durable subscriptions and using DUPS_OK_ACKNOWLEDGE acknowledgment mode). In general we found that protocol has less effect in the high-reliability case. This is probably because the persistence overhead required in the high-reliability case is a more important factor in limiting throughput than the protocol speed. Additionally:

TCP provides the fastest method to communicate with the broker. SSL is 50 to 70 percent slower than TCP when it comes to sending and receiving messages (50 percent for persistent messages, closer to 70 percent for nonpersistent messages). Additionally, establishing the initial connection is slower with SSL (it might take several seconds) because the client and broker (or Web Server in the case of HTTPS) need to establish a private key to be used when encrypting the data for transmission. The performance drop is caused by the additional processing required to encrypt and decrypt each low-level TCP packet. HTTP is slower than either the TCP or SSL. It uses a servlet that runs on a Web server as a proxy between the client and the broker. Performance overhead is involved in encapsulating packets in HTTP requests and in the requirement that messages go through two hops--client to servlet, servlet to broker--to reach the broker. HTTPS is slower than HTTP because of the additional overhead required to encrypt the packet between client and servlet and between servlet and broker.
276
Message Service Architecture

A Message Queue message service can be implemented as a single broker or as a cluster consisting of multiple interconnected broker instances. As the number of clients connected to a broker increases, and as the number of messages being delivered increases, a broker will eventually exceed resource limitations such as file descriptor, thread, and memory limits. One way to accommodate increasing loads is to add more broker instances to a Message Queue message service, distributing client connections and message routing and delivery across multiple brokers. In general, this scaling works best if clients are evenly distributed across the cluster, especially message producing clients. Because of the overhead involved in delivering messages between the brokers in a cluster, clusters with limited numbers of connections or limited message delivery rates, might exhibit lower performance than a single broker. You might also use a broker cluster to optimize network bandwidth. For example, you might want to use slower, long distance network links between a set of remote brokers within a cluster, while using higher speed links for connecting clients to their respective broker instances. For more information on clusters, see Chapter 10, Configuring and Managing Broker Clusters
Broker Limits and Behaviors

The message throughput that a broker might be required to handle is a function of the use patterns of the messaging applications the broker supports. However, the broker is limited in resources: memory, CPU cycles, and so forth. As a result, it would be possible for a broker to become overwhelmed to the point where it becomes unresponsive or unstable. The Message Queue message broker has mechanisms built in for managing memory resources and preventing the broker from running out of memory. These mechanisms include configurable limits on the number of messages or message bytes that can be held by a broker or its individual physical destinations, and a set of behaviors that can be instituted when physical destination limits are reached. With careful monitoring and tuning, these configurable mechanisms can be used to balance the inflow and outflow of messages so that system overload cannot occur. While these mechanisms consume overhead and can limit message throughput, they nevertheless maintain operational integrity.
Data Store Performance

Message Queue supports both file-based and JDBC-based persistence modules. File-based persistence uses individual files to store persistent data. JDBC-based persistence uses a Java Database Connectivity (JDBC) interface and requires a JDBC-compliant data store. File-based persistence is generally faster than JDBC-based; however, some users prefer the redundancy and administrative control provided by a JDBC-compliant store.
Adjusting Configuration To Improve Performance
In the case of file-based persistence, you can maximize reliability by specifying that persistence operations synchronize the in-memory state with the data store. This helps eliminate data loss due to system crashes, but at the expense of performance.
Client Runtime Configuration

The Message Queue client runtime provides client applications with an interface to the Message Queue message service. It supports all the operations needed for clients to send messages to physical destinations and to receive messages from such destinations. The client runtime is configurable (by setting connection factory attribute values), allowing you to control aspects of its behavior, such as connection flow metering, consumer flow limits, and connection flow limits, that can improve performance and message throughput. See Client Runtime Message Flow Adjustments on page 282 for more information on these features and the attributes used to configure them.

The following sections explain how configuration adjustments can affect performance.
System Adjustments
The following sections describe adjustments you can make to the operating system, JVM, communication protocols, and persistent data store.
Solaris Tuning: CPU Utilization, Paging/Swapping/Disk I/O

See your system documentation for tuning your operating system.
Java Virtual Machine Adjustments

By default, the broker uses a JVM heap size of 192MB. This is often too small for significant message loads and should be increased. When the broker gets close to exhausting the JVM heap space used by Java objects, it uses various techniques such as flow control and message swapping to free memory. Under extreme circumstances it even closes client connections in order to free the memory and reduce the message inflow. Hence it is desirable to set the maximum JVM heap space high enough to avoid such circumstances. However, if the maximum Java heap space is set too high, in relation to system physical memory, the broker can continue to grow the Java heap space until the entire system runs out of memory. This can result in diminished performance, unpredictable broker crashes, and/or affect the behavior of other applications and services running on the system. In general, you need to allow enough physical memory for the operating system and other applications to run on the machine.
In general it is a good idea to evaluate the normal and peak system memory footprints, and configure the Java heap size so that it is large enough to provide good performance, but not so large as to risk system memory problems. To change the minimum and maximum heap size for the broker, use the -vmargs command line option when starting the broker. For example:
/usr/bin/imqbrokerd -vmargs "-Xms256m -Xmx1024m"
This command will set the starting Java heap size to 256MB and the maximum Java heap size to 1GB.
On Solaris or Linux, if starting the broker via /etc/rc* (that is, /etc/init.d/imq), specify broker command line arguments in the file /etc/imq/imqbrokerd.conf (Solaris) or /etc/opt/sun/mq/imqbrokerd.conf (Linux). See the comments in that file for more information. On Windows, if starting the broker as a Windows service, specify JVM arguments using the -vmargs option to the imqsvcadmin install command. See Service Administrator Utility on page 334 in Chapter 16, Command Line Reference
In any case, verify settings by checking the brokers log file or using the imqcmd metrics bkr -m cxn command.
Tuning Transport Protocols

Once a protocol that meets application needs has been chosen, additional tuning (based on the selected protocol) might improve performance. A protocols performance can be modified using the following three broker properties:

imq.protocol.protocolType.nodelay imq.protocol.protocolType.inbufsz imq.protocol.protocolType.outbufsz
For TCP and SSL protocols, these properties affect the speed of message delivery between client and broker. For HTTP and HTTPS protocols, these properties affect the speed of message delivery between the Message Queue tunnel servlet (running on a Web server) and the broker. For HTTP/HTTPS protocols there are additional properties that can affect performance (see HTTP/HTTPS Tuning on page 280). The protocol tuning properties are described in the following sections.
nodelay
The nodelay property affects Nagles algorithm (the value of the TCP_NODELAY socket-level option on TCP/IP) for the given protocol. Nagles algorithm is used to improve TCP performance on systems using slow connections such as wide-area networks (WANs).
When the algorithm is used, TCP tries to prevent several small chunks of data from being sent to the remote system (by bundling the data in larger packets). If the data written to the socket does not fill the required buffer size, the protocol delays sending the packet until either the buffer is filled or a specific delay time has elapsed. Once the buffer is full or the timeout has occurred, the packet is sent. For most messaging applications, performance is best if there is no delay in the sending of packets (Nagles algorithm is not enabled). This is because most interactions between client and broker are request/response interactions: the client sends a packet of data to the broker and waits for a response. For example, typical interactions include:

Creating a connection Creating a producer or consumer Sending a persistent message (the broker confirms receipt of the message) Sending a client acknowledgment in an AUTO_ACKNOWLEDGE or CLIENT_ACKNOWLEDGE session (the broker confirms processing of the acknowledgment)
For these interactions, most packets are smaller than the buffer size. This means that if Nagles algorithm is used, the broker delays several milliseconds before sending a response to the consumer. However, Nagles algorithm may improve performance in situations where connections are slow and broker responses are not required. This would be the case where a client sends a nonpersistent message or where a client acknowledgment is not confirmed by the broker (DUPS_OK_ACKNOWLEDGE session).
inbufsz/outbufsz
The inbufsz property sets the size of the buffer on the input stream reading data coming in from a socket. Similarly, outbufsz sets the buffer size of the output stream used by the broker to write data to the socket. In general, both parameters should be set to values that are slightly larger than the average packet being received or sent. A good rule of thumb is to set these property values to the size of the average packet plus 1 kilobyte (rounded to the nearest kilobyte). For example, if the broker is receiving packets with a body size of 1 kilobyte, the overall size of the packet (message body plus header plus properties) is about 1200 bytes; an inbufsz of 2 kilobytes (2048 bytes) gives reasonable performance. Increasing inbufsz or outbufsz greater than that size may improve performance slightly, but increases the memory needed for each connection.
HTTP/HTTPS Tuning
In addition to the general properties discussed in the previous two sections, HTTP/HTTPS performance is limited by how fast a client can make HTTP requests to the Web server hosting the Message Queue tunnel servlet.
A Web server might need to be optimized to handle multiple requests on a single socket. With JDK version 1.4 and later, HTTP connections to a Web server are kept alive (the socket to the Web server remains open) to minimize resources used by the Web server when it processes multiple HTTP requests. If the performance of a client application using JDK version 1.4 is slower than the same application running with an earlier JDK release, you might need to tune the Web server keep-alive configuration parameters to improve performance. In addition to such Web server tuning, you can also adjust how often a client polls the Web server. HTTP is a request-based protocol. This means that clients using an HTTP-based protocol periodically need to check the Web server to see if messages are waiting. The imq.httpjms.http.pullPeriod broker property (and the corresponding imq.httpsjms.https.pullPeriod property) specifies how often the Message Queue client runtime polls the Web server. If the pullPeriod value is 1 (the default value), the client runtime polls the server as soon as the previous request returns, maximizing the performance of the individual client. As a result, each client connection monopolizes a request thread in the Web server, possibly straining Web server resources. If the pullPeriod value is a positive number, the client runtime periodically sends requests to the Web server to see if there is pending data. In this case, the client does not monopolize a request thread in the Web server. Hence, if large numbers of clients are using the Web server, you might conserve Web server resources by setting the pullPeriod to a positive value.
Tuning the File-based Persistent Store

For information on tuning the file-based persistent store, see Configuring a File-Based Data Store on page 129.
Broker Memory Management Adjustments

You can improve performance and increase broker stability under load by properly managing broker memory. Memory management can be configured on a destination-by-destination basis or on a system-wide level (for all destinations, collectively).
Using Physical Destination Limits

To configure physical destination limits, see the properties described in Physical Destination Properties on page 375.
Using System-Wide Limits

If message producers tend to overrun message consumers, messages can accumulate in the broker. The broker contains a mechanism for throttling back producers and swapping messages out of active memory under low memory conditions, but it is wise to set a hard limit on the total number of messages (and message bytes) that the broker can hold.
Control these limits by setting the imq.system.max_count and the imq.system.max_size broker properties. For example:
imq.system.max_count=5000
The defined value above means that the broker will only hold up to 5000 undelivered and/or unacknowledged messages. If additional messages are sent, they are rejected by the broker. If a message is persistent then the clinet runtime will throw an exception when the producer tries to send the message. If the message is non-persistent, the broker silently drops the message. When an exception is thrown in sending a message, the client should process the exception by pausing for a moment and retrying the send again. (Note that the exception will never be due to the brokers failure to receive a message; the exception is thrown by the client runtime before the message is sent to the broker.)
Client Runtime Message Flow Adjustments

This section discusses client runtimeflow control behaviors that affect performance. These behaviors are configured as attributes of connection factory administered objects. For information on setting connection factory attributes, see Chapter 11, Managing Administered Objects
Message Flow Metering

Messages sent and received by clients (payload messages), as well as Message Queue control messages, pass over the same client-broker connection. Delays in the delivery of control messages, such as broker acknowledgments, can result if control messages are held up by the delivery of payload messages. To prevent this type of congestion, Message Queue meters the flow of payload messages across a connection. Payload messages are batched (as specified with the connection factory attribute imqConnectionFlowCount) so that only a set number are delivered. After the batch has been delivered, delivery of payload messages is suspended and only pending control messages are delivered. This cycle repeats, as additional batches of payload messages are delivered followed by pending control messages. The value of imqConnectionFlowCount should be kept low if the client is doing operations that require many responses from the broker: for example, if the client is using CLIENT_ACKNOWLEDGE or AUTO_ACKNOWLEDGE mode, persistent messages, transactions, or queue browsers, or is adding or removing consumers. If, on the other hand, the client has only simple consumers on a connection using DUPS_OK_ACKNOWLEDGE mode, you can increase imqConnectionFlowCount without compromising performance.
Message Flow Limits

There is a limit to the number of payload messages that the Message Queue client runtime can handle before encountering local resource limitations, such as memory. When this limit is approached, performance suffers. Hence, Message Queue lets you limit the number of messages per consumer (or messages per connection) that can be delivered over a connection and buffered in the client runtime, waiting to be consumed.
Consumer Flow Limits

When the number of payload messages delivered to the client runtime exceeds the value of imqConsumerFlowLimit for any consumer, message delivery for that consumer stops. It is resumed only when the number of unconsumed messages for that consumer drops below the value set with imqConsumerFlowThreshold. The following example illustrates the use of these limits: consider the default settings for topic consumers:
imqConsumerFlowLimit=1000 imqConsumerFlowThreshold=50
When the consumer is created, the broker delivers an initial batch of 1000 messages (providing they exist) to this consumer without pausing. After sending 1000 messages, the broker stops delivery until the client runtime asks for more messages. The client runtime holds these messages until the application processes them. The client runtime then allows the application to consume at least 50% (imqConsumerFlowThreshold ) of the message buffer capacity (i.e. 500 messages) before asking the broker to send the next batch. In the same situation, if the threshold were 10%, the client runtime would wait for the application to consume at least 900 messages before asking for the next batch. The next batch size is calculated as follows:
imqConsumerFlowLimit - (current number of pending msgs in buffer)
So if imqConsumerFlowThreshold is 50%, the next batch size can fluctuate between 500 and 1000, depending on how fast the application can process the messages. If the imqConsumerFlowThreshold is set too high (close to 100%), the broker will tend to send smaller batches, which can lower message throughput. If the value is set too low (close to 0%), the client may be able to finish processing the remaining buffered messages before the broker delivers the next set, again degrading message throughput. Generally speaking, unless you have specific performance or reliability concerns, you will not need to change the default value of imqConsumerFlowThreshold attribute. The consumer-based flow controls (in particular, imqConsumerFlowLimit ) are the best way to manage memory in the client runtime. Generally, depending on the client application, you
know the number of consumers you need to support on any connection, the size of the messages, and the total amount of memory that is available to the client runtime.
Connection Flow Limits

In the case of some client applications, however, the number of consumers may be indeterminate, depending on choices made by end users. In those cases, you can still manage memory using connection-level flow limits. Connection-level flow controls limit the total number of messages buffered for all consumers on a connection. If this number exceeds the value of imqConnectionFlowLimit, delivery of messages through the connection stops until that total drops below the connection limit. (The imqConnectionFlowLimit attribute is enabled only if you set imqConnectionFlowLimitEnabled to true.) The number of messages queued up in a session is a function of the number of message consumers using the session and the message load for each consumer. If a client is exhibiting delays in producing or consuming messages, you can normally improve performance by redesigning the application to distribute message producers and consumers among a larger number of sessions or to distribute sessions among a larger number of connections.
Adjusting Multiple-Consumer Queue Delivery

The efficiency with which multiple queue consumers process messages in a queue destination depends on a number of factors. To achieve optimal message throughput there must be a sufficient number of consumers to keep up with the rate of message production for the queue, and the messages in the queue must be routed and then delivered to the active consumers in such a way as to maximize their rate of consumption. The message delivery mechanism for multiple-consumer queues is that messages are delivered to consumers in batches as each consumer is ready to receive a new batch. The readiness of a consumer to receive a batch of messages depends upon configurable client runtime properties, such as imqConsumerFlowLimit and imqConsumerFlowThreshold, as described in Message Flow Limits on page 283. As new consumers are added to a queue, they are sent a batch of messages to consume, and receive subsequent batches as they become ready.
Note The message delivery mechanism for multiple-consumer queues described above can result in messages being consumed in an order different from the order in which they are produced.
If messages are accumulating in the queue, it is possible that there is an insufficient number of consumers to handle the message load. It is also possible that messages are being delivered to consumers in batch sizes that cause messages to be backing up on the consumers. For example,
if the batch size (consumerFlowLimit) is too large, one consumer might receive all the messages in a queue while other consumers receive none. If consumers are very fast, this might not be a problem. However, if consumers are relatively slow, you want messages to be distributed to them evenly, and therefore you want the batch size to be small. Although smaller batch sizes require more overhead to deliver messages to consumers, for slow consumers there is generally a net performance gain in using small batch sizes. The value of consumerFlowLimit can be set on a destination as well as on the client runtime: the smaller value overrides the larger one.
285
286
15
C H A P T E R

1 5
Troubleshooting
This chapter explains how to understand and resolve the following problems: A Client Cannot Establish a Connection on page 287 Connection Throughput Is Too Slow on page 292 A Client Cannot Create a Message Producer on page 293 Message Production Is Delayed or Slowed on page 294 Messages Are Backlogged on page 297 Broker Throughput Is Sporadic on page 300 Messages Are Not Reaching Consumers on page 302 Dead Message Queue Contains Messages on page 303
When problems occur, it is useful to check the version number of the installed Message Queue software. Use the version number to ensure that you are using documentation whose version matches the software version. You also need the version number to report a problem to Sun. To check the version number, issue the following command: imqcmd -v
A Client Cannot Establish a Connection

Symptoms:

Client cannot make a new connection. Client cannot auto-reconnect on failed connection.
Possible causes:
Client applications are not closing connections, causing the number of connections to exceed resource limitations. Broker is not running or there is a network connectivity problem. Connection service is inactive or paused.
287
Too few threads available for the number of connections required. Too few file descriptors for the number of connections required on the Solaris or Linux operating system. TCP backlog limits the number of simultaneous new connection requests that can be established. Operating system limits the number of concurrent connections. Authentication or authorization of the user is failing.
Possible cause: Client applications are not closing connections, causing the number of connections to exceed resource limitations. To confirm this cause of the problem: List all connections to a broker:
imqcmd list cxn The output will list all connections and the host from which each connection has been made, revealing an unusual number of open connections for specific clients. To resolve the problem: Rewrite the offending clients to close unused connections.
Possible cause: Broker is not running or there is a network connectivity problem. To confirm this cause of the problem:
Telnet to the brokers primary port (for example, the default of 7676) and verify that the broker responds with Port Mapper output. Verify that the broker process is running on the host. Start up the broker. Fix the network connectivity problem.
To resolve the problem:

Possible cause: Connection service is inactive or paused. To confirm this cause of the problem: Check the status of all connection services: imqcmd list svc If the status of a connection service is shown as unknown or paused, clients will not be able to establish a connection using that service. To resolve the problem:
If the status of a connection service is shown as unknown , it is missing from the active service list (imq.service.active ). In the case of SSL-based services, the service might also be improperly configured, causing the broker to make the following entry in the broker log: ERROR [B3009]: Unable to start service ssljms: [B4001]: Unable to open protocol tls for ssljms service... followed by an explanation of the underlying cause of the exception. To properly configure SSL services, see Message Encryption on page 161.
288
If the status of a connection service is shown as paused, resume the service (see Pausing and Resuming a Connection Service on page 99).
Possible cause: Too few threads available for the number of connections required. To confirm this cause of the problem: Check for the following entry in the broker log:
WARNING [B3004]: No threads are available to process a new connection on service ... Closing the new connection. Also check the number of connections on the connection service and the number of threads currently in use, using one of the following formats: imqcmd query svc -n serviceName imqcmd metrics svc -n serviceName -m cxn Each connection requires two threads: one for incoming messages and one for outgoing messages (see Thread Pool Management on page 98). To resolve the problem:
If you are using a dedicated thread pool model (imq.serviceName.threadpool_model= dedicated), the maximum number of connections is half the maximum number of threads in the thread pool. Therefore, to increase the number of connections, increase the size of the thread pool (imq.serviceName.max_threads) or switch to the shared thread pool model. If you are using a shared thread pool model (imq.serviceName.threadpool_model=shared), the maximum number of connections is half the product of the connection monitor limit (imq.serviceName.connectionMonitor_limit) and the maximum number of threads (imq.serviceName.max_threads). Therefore, to increase the number of connections, increase the size of the thread pool or increase the connection monitor limit. Ultimately, the number of supportable connections (or the throughput on connections) will reach input/output limits. In such cases, use a multiple-broker cluster to distribute connections among the broker instances within the cluster.
Possible cause: Too few file descriptors for the number of connections required on the Solaris or Linux platform.
For more information about this issue, see Setting the File Descriptor Limit on page 70. To confirm this cause of the problem: Check for an entry in the broker log similar to the following: Too many open files To resolve the problem: Increase the file descriptor limit, as described in the man page for the ulimit command.
Chapter 15 Troubleshooting
289
Possible cause: TCP backlog limits the number of simultaneous new connection requests that can be established.
The TCP backlog places a limit on the number of simultaneous connection requests that can be stored in the system backlog (imq.portmapper.backlog) before the Port Mapper rejects additional requests. (On the Windows platform there is a hard-coded backlog limit of 5 for Windows desktops and 200 for Windows servers.) The rejection of requests because of backlog limits is usually a transient phenomenon, due to an unusually high number of simultaneous connection requests. To confirm this cause of the problem: Examine the broker log. First, check to see whether the broker is accepting some connections during the same time period that it is rejecting others. Next, check for messages that explain rejected connections. If you find such messages, the TCP backlog is probably not the problem, because the broker does not log connection rejections due to the TCP backlog. If some successful connections are logged, and no connection rejections are logged, the TCP backlog is probably the problem. To resolve the problem:
Program the client to retry the attempted connection after a short interval of time (this normally works because of the transient nature of this problem). Increase the value of imq.portmapper.backlog. Check that clients are not closing and then opening connections too often.
Possible cause: Operating system limits the number of concurrent connections.
The Windows operating system license places limits on the number of concurrent remote connections that are supported. To confirm this cause of the problem: Check that there are plenty of threads available for connections (using imqcmd query svc) and check the terms of your Windows license agreement. If you can make connections from a local client, but not from a remote client, operating system limitations might be the cause of the problem. To resolve the problem:

Upgrade the Windows license to allow more connections. Distribute connections among a number of broker instances by setting up a multiple-broker cluster.
Possible cause: Authentication or authorization of the user is failing.
The authentication may be failing for any of the following reasons:

Incorrect password No entry for user in user repository User does not have access permission for connection service
To confirm this cause of the problem: Check entries in the broker log for the Forbidden error message. This will indicate an authentication error, but will not indicate the reason for it.
If you are using a file-based user repository, enter the following command: imqusermgr list -i instanceName -u userName If the output shows a user, the wrong password was probably submitted. If the output shows the following error, there is no entry for the user in the user repository: Error [B3048]: User does not exist in the password file
If you are using an LDAP server user repository, use the appropriate tools to check whether there is an entry for the user. Check the access control file to see whether there are restrictions on access to the connection service. If the wrong password was used, provide the correct password. If there is no entry for the user in the user repository, add one (see Adding a User to the Repository on page 144). If the user does not have access permission for the connection service, edit the access control file to grant such permission (see Authorization Rules for Connection Services on page 159).

Possible cause: Authentication or authorization of the user is failing.
Authentication may be failing for any of the following reasons: No entry for user in user repository Incorrect password User does not have access permission for connection service To confirm this cause of the problem

1. Check entries in the broker log for the error message Forbidden. This will indicate an authentication error, but will not indicate the reason for it. 2. Check the user repository for an entry for this user:
If you are using a flat-file user repository, enter the command imqusermgr list -i instanceName -u userName If the output shows the error Error [B3048]: User does not exist in the password file then there is no entry for the user in the user repository:
If you are using an LDAP user repository, use the appropriate tools to check whether there is an entry for the user.
3. If the output from step 2 does show a user entry, the wrong password was probably provided.
Chapter 15 Troubleshooting 291
Connection Throughput Is Too Slow
4. Check the access control file to see whether there are restrictions on access to the connection service. To resolve the problem
If there is no entry for the user in the user repository, add one (see Adding a User to the Repository on page 144). If the wrong password was used, provide the correct password. If the user does not have access permission for the connection service, edit the access control file to grant such permission (see Authorization Rules for Connection Services on page 159).
Connection Throughput Is Too Slow

Symptoms:

Message throughput does not meet expectations. Message input/output rates are not limited by an insufficient number of supported connections (as described in A Client Cannot Establish a Connection on page 287).
Possible causes:

Network connection or WAN is too slow. Connection service protocol is inherently slow compared to TCP. Connection service protocol is not optimally tuned. Messages are so large that they consume too much bandwidth. What appears to be slow connection throughput is actually a bottleneck in some other step of the message delivery process.
Possible cause: Network connection or WAN is too slow. To confirm this cause of the problem:
Ping the network, to see how long it takes for the ping to return, and consult a network administrator.
Send and receive messages using local clients and compare the delivery time with that of remote clients (which use a network link). To resolve the problem: Upgrade the network link.
Possible cause: Connection service protocol is inherently slow compared to TCP.
For example, SSL-based or HTTP-based protocols are slower than TCP (see Transport Protocols on page 276). To confirm this cause of the problem: If you are using SSL-based or HTTP-based protocols, try using TCP and compare the delivery times.
A Client Cannot Create a Message Producer
To resolve the problem: Application requirements usually dictate the protocols being used, so there is little you can do other than attempt to tune the protocol as described in Tuning Transport Protocols on page 279.
Possible cause: Connection service protocol is not optimally tuned. To confirm this cause of the problem: Try tuning the protocol to see whether it makes a difference.
To resolve the problem: Try tuning the protocol, as described in Tuning Transport Protocols on page 279.
Possible cause: Messages are so large that they consume too much bandwidth. To confirm this cause of the problem: Try running your benchmark with smaller-sized messages.
Have application developers modify the application to use the message compression feature, which is described in the Message Queue Developers Guide for Java Clients. Use messages as notifications of data to be sent, but move the data using another protocol.
Possible cause: What appears to be slow connection throughput is actually a bottleneck in some other step of the message delivery process. To confirm this cause of the problem: If what appears to be slow connection throughput cannot be explained by any of the causes above, see Factors Affecting Performance on page 268 for other possible bottlenecks and check for symptoms associated with the following problems:

Message Production Is Delayed or Slowed on page 294 Messages Are Backlogged on page 297 Broker Throughput Is Sporadic on page 300
To resolve the problem: Follow the problem resolution guidelines provided in the troubleshooting sections listed above.
A Client Cannot Create a Message Producer

Symptom:
A message producer cannot be created for a physical destination; the client receives an exception.
Possible causes:

A physical destination has been configured to allow only a limited number of producers. The user is not authorized to create a message producer due to settings in the access control file.
293
Message Production Is Delayed or Slowed
Possible cause: A physical destination has been configured to allow only a limited number of producers.
One of the ways of avoiding the accumulation of messages on a physical destination is to limit the number of producers (maxNumProducers) that it supports. To confirm this cause of the problem: Check the physical destination: imqcmd query dst (see Viewing Physical Destination Information on page 114). The output will show the current number of producers and the value of maxNumProducers. If the two values are the same, the number of producers has reached its configured limit. When a new producer is rejected by the broker, the broker returns the exception ResourceAllocationException [C4088]: A JMS destination limit was reached and makes the following entry in the broker log: [B4183]: Producer can not be added to destination To resolve the problem: Increase the value of the maxNumProducers property (see Updating Physical Destination Properties on page 114).
Possible cause: The user is not authorized to create a message producer due to settings in the access control file. To confirm this cause of the problem: When a new producer is rejected by the broker, the broker
returns the exception JMSSecurityException [C4076]: Client does not have permission to create producer on destination and makes the following entries in the broker log: [B2041]: Producer on destination denied [B4051]: Forbidden guest. To resolve the problem: Change the access control properties to allow the user to produce messages (see Authorization Rules for Physical Destinations on page 160).

Symptoms:

When sending persistent messages, the send method does not return and the client blocks. When sending a persistent message, the client receives an exception. A producing client slows down.
Possible causes:

The broker is backlogged and has responded by slowing message producers. The broker cannot save a persistent message to the data store. Broker acknowledgment timeout is too short.
294
A producing client is encountering JVM limitations.
Possible cause: The broker is backlogged and has responded by slowing message producers.
A backlogged broker accumulates messages in broker memory. When the number of messages or message bytes in physical destination memory reaches configured limits, the broker attempts to conserve memory resources in accordance with the specified limit behavior. The following limit behaviors slow down message producers:
FLOW_CONTROL: The broker does not immediately acknowledge receipt of persistent messages (thereby blocking a producing client).
REJECT_NEWEST: The broker rejects new persistent messages. Similarly, when the number of messages or message bytes in brokerwide memory (for all physical destinations) reaches configured limits, the broker will attempt to conserve memory resources by rejecting the newest messages. Also, when system memory limits are reached because physical destination or brokerwide limits have not been set properly, the broker takes increasingly serious action to prevent memory overload. These actions include throttling back message producers. To confirm this cause of the problem: When a message is rejected by the broker because of configured message limits, the broker returns the exception JMSException [C4036]: A server error occurred and makes the following entry in the broker log: [B2011]: Storing of JMS message from IMQconn failed This message is followed by another indicating the limit that has been reached: [B4120]: Cannot store message on destination destName because capacity of maxNumMsgs would be exceeded. if the exceeded message limit is on a physical destination, or [B4024]: The maximum number of messages currrently in the system has been exceeded, rejecting message. if the limit is brokerwide. More generally, you can check for message limit conditions before the rejections occur as follows:

Query physical destinations and the broker and inspect their configured message limit settings.
Monitor the number of messages or message bytes currently in a physical destination or in the broker as a whole, using the appropriate imqcmd commands. See Chapter 21, Metrics Information Reference, for information about metrics you can monitor and the commands you use to obtain them. To resolve the problem:

Modify the message limits on a physical destination (or brokerwide), being careful not to exceed memory resources.
295
In general, you should manage memory at the individual destination level, so that brokerwide message limits are never reached. For more information, see Broker Memory Management Adjustments on page 281.
Change the limit behaviors on a destination so as not to slow message production when message limits are reached, but rather to discard messages in memory. For example, you can specify the REMOVE_OLDEST and REMOVE_LOW_PRIORITY limit behaviors, which delete messages that accumulate in memory (see Table 181).
Possible cause: The broker cannot save a persistent message to the data store.
If the broker cannot access a data store or write a persistent message to it, the producing client is blocked. This condition can also occur if destination or brokerwide message limits are reached, as described above. To confirm this cause of the problem: If the broker is unable to write to the data store, it makes one of the following entries in the broker log: [B2011]: Storing of JMS message from connectionID failed [B4004]: Failed to persist message messageID To resolve the problem:

In the case of file-based persistence, try increasing the disk space of the file-based data store. In the case of a JDBC-compliant data store, check that JDBC-based persistence is properly configured (seeConfiguring a JDBC-Based Data Store on page 133). If so, consult your database administrator to troubleshoot other database problems.
Possible cause: Broker acknowledgment timeout is too short.
Because of slow connections or a lethargic broker (caused by high CPU utilization or scarce memory resources), a broker may require more time to acknowledge receipt of a persistent message than allowed by the value of the connection factorys imqAckTimeout attribute. To confirm this cause of the problem: If the imqAckTimeout value is exceeded, the broker returns the exception JMSException [C4000]: Packet acknowledge failed To resolve the problem: Change the value of the imqAckTimeout connection factory attribute (see Reliability And Flow Control on page 203).
Possible cause: A producing client is encountering JVM limitations. To confirm this cause of the problem:

Find out whether the client application receives an out-of-memory error. Check the free memory available in the JVM heap, using runtime methods such as freeMemory, maxMemory, and totalMemory.
To resolve the problem: Adjust the JVM (see Java Virtual Machine Adjustments on page 278).
Messages Are Backlogged

Symptoms:

Message production is delayed or produced messages are rejected by the broker. Messages take an unusually long time to reach consumers. The number of messages or message bytes in the broker (or in specific destinations) increases steadily over time.
To see whether messages are accumulating, check how the number of messages or message bytes in the broker changes over time and compare to configured limits. First check the configured limits: imqcmd query bkr
Note The imqcmd metrics bkr subcommand does not display this information.
Then check for message accumulation in each destination: imqcmd list dst To see whether messages have exceeded configured destination or brokerwide limits, check the broker log for the entry [B2011]: Storing of JMS message from failed. This entry will be followed by another identifying the limit that has been exceeded. Possible causes:

There are inactive durable subscriptions on a topic destination. Too few consumers are available to consume messages in a queue. Message consumers are processing too slowly to keep up with message producers. Client acknowledgment processing is slowing down message consumption. The broker cannot keep up with produced messages. Client code defects; consumers are not acknowledging messages.
Possible cause: There are inactive durable subscriptions on a topic destination.
If a durable subscription is inactive, messages are stored in a destination until the corresponding consumer becomes active and can consume the messages. To confirm this cause of the problem: Check the state of durable subscriptions on each topic destination: imqcmd list dur -d destName To resolve the problem:
Purge all messages for the offending durable subscriptions (see Managing Durable Subscriptions on page 123). Specify message limit and limit behavior attributes for the topic (see Table 181). For example, you can specify the REMOVE_OLDEST and REMOVE_LOW_PRIORITY limit behaviors, which delete messages that accumulate in memory. Purge all messages from the corresponding destinations (see Purging a Physical Destination on page 113). Limit the time messages can remain in memory by rewriting the producing client to set a time-to-live value on each message. You can override any such settings for all producers sharing a connection by setting the imqOverrideJMSExpiration and imqJMSExpiration connection factory attributes (see Message Header Overrides on page 388).
Possible cause: Too few consumers are available to consume messages in a multiple-consumer queue.
If there are too few active consumers to which messages can be delivered, a queue destination can become backlogged as messages accumulate. This condition can occur for any of the following reasons: Too few active consumers exist for the destination. Consuming clients have failed to establish connections. No active consumers use a selector that matches messages in the queue. To confirm this cause of the problem: To help determine the reason for unavailable consumers, check the number of active consumers on a destination: imqcmd metrics dst -n destName -t q -m con To resolve the problem: Depending on the reason for unavailable consumers,

Create more active consumers for the queue by starting up additional consuming clients. Adjust the imq.consumerFlowLimit broker property to optimize queue delivery to multiple consumers (see Adjusting Multiple-Consumer Queue Delivery on page 284). Specify message limit and limit behavior attributes for the queue (see Table 181). For example, you can specify the REMOVE_OLDEST and REMOVE_LOW_PRIOROTY limit behaviors, which delete messages that accumulate in memory. Purge all messages from the corresponding destinations (see Purging a Physical Destination on page 113). Limit the time messages can remain in memory by rewriting the producing client to set a time-to-live value on each message. You can override any such setting for all producers sharing a connection by setting the imqOverrideJMSExpiration and imqJMSExpiration connection factory attributes (see Message Header Overrides on page 388).
Possible cause: Message consumers are processing too slowly to keep up with message producers.
In this case, topic subscribers or queue receivers are consuming messages more slowly than the producers are sending messages. One or more destinations are getting backlogged with messages because of this imbalance.
To confirm this cause of the problem: Check for the rate of flow of messages into and out of the broker: imqcmd metrics bkr -m rts Then check flow rates for each of the individual destinations: imqcmd metrics bkr -t destType -n destName -m rts To resolve the problem:

Optimize consuming client code. For queue destinations, increase the number of active consumers (see Adjusting Multiple-Consumer Queue Delivery on page 284).
Possible cause: Client acknowledgment processing is slowing down message consumption.
Two factors affect the processing of client acknowledgments:
Significant broker resources can be consumed in processing client acknowledgments. As a result, message consumption may be slowed in those acknowledgment modes in which consuming clients block until the broker confirms client acknowledgments.
JMS payload messages and Message Queue control messages (such as client acknowledgments) share the same connection. As a result, control messages can be held up by JMS payload messages, slowing message consumption. To confirm this cause of the problem: Check the flow of messages relative to the flow of packets. If the number of packets per second is out of proportion to the number of messages, client acknowledgments may be a problem. Check to see whether the client has received the following exception:
JMSException [C4000]: Packet acknowledge failed To resolve the problem:
Modify the acknowledgment mode used by clients: for example, switch to DUPS_OK_ACKNOWLEDGE or CLIENT_ACKNOWLEDGE. If using CLIENT_ACKNOWLEDGE or transacted sessions, group a larger number of messages into a single acknowledgment. Adjust consumer and connection flow control parameters (see Client Runtime Message Flow Adjustments on page 282 ).
Possible cause: The broker cannot keep up with produced messages.
In this case, messages are flowing into the broker faster than the broker can route and dispatch them to consumers. The sluggishness of the broker can be due to limitations in any or all of the following:

CPU Network socket read/write operations

299
Broker Throughput Is Sporadic
Disk read/write operations Memory paging Persistent store JVM memory limits
To confirm this cause of the problem: Check that none of the other possible causes of this problem are responsible. To resolve the problem:

Upgrade the speed of your computer or data store. Use a broker cluster to distribute the load among multiple broker instances.
Possible cause: Client code defects; consumers are not acknowledging messages.
Messages are held in a destination until they have been acknowledged by all consumers to which they have been sent. If a client is not acknowledging consumed messages, the messages accumulate in the destination without being deleted. For example, client code might have the following defects:
Consumers using the CLIENT_ACKNOWLEDGE acknowledgment mode or transacted session may not be calling Session.acknowledge or Session.commit regularly. Consumers using the AUTO_ACKNOWLEDGE acknowledgment mode may be hanging for some reason.
To confirm this cause of the problem: First check all other possible causes listed in this section. Next, list the destination with the following command: imqcmd list dst Notice whether the number of messages listed under the UnAcked header is the same as the number of messages in the destination. Messages under this header were sent to consumers but not acknowledged. If this number is the same as the total number of messages, then the broker has sent all the messages and is waiting for acknowledgment. To resolve the problem: Request the help of application developers in debugging this problem.

Symptom:
Message throughput sporadically drops and then resumes normal performance.
Possible causes:

The broker is very low on memory resources. JVM memory reclamation (garbage collection) is taking place. The JVM is using the just-in-time compiler to speed up performance.
300
Possible cause: The broker is very low on memory resources.
Because destination and broker limits were not properly set, the broker takes increasingly serious action to prevent memory overload; this can cause the broker to become sluggish until the message backlog is cleared. To confirm this cause of the problem: Check the broker log for a low memory condition [B1089]: In low memory condition, broker is attempting to free up resources followed by an entry describing the new memory state and the amount of total memory being used. Also check the free memory available in the JVM heap: imqcmd metrics bkr -m cxn Free memory is low when the value of total JVM memory is close to the maximum JVM memory value. To resolve the problem:

Adjust the JVM (see Java Virtual Machine Adjustments on page 278). Increase system swap space.
Possible cause: JVM memory reclamation (garbage collection) is taking place.
Memory reclamation periodically sweeps through the system to free up memory. When this occurs, all threads are blocked. The larger the amount of memory to be freed up and the larger the JVM heap size, the longer the delay due to memory reclamation. To confirm this cause of the problem: Monitor CPU usage on your computer. CPU usage drops when memory reclamation is taking place. Also start your broker using the following command line options: -vmargs -verbose:gc Standard output indicates the time when memory reclamation takes place. To resolve the problem: In computers with multiple CPUs, set the memory reclamation to take place in parallel: -XX:+UseParallelGC=true
Possible cause: The JVM is using the just-in-time compiler to speed up performance. To confirm this cause of the problem: Check that none of the other possible causes of this problem are responsible. To resolve the problem: Let the system run for awhile; performance should improve.
301
Messages Are Not Reaching Consumers
Messages Are Not Reaching Consumers

Symptom:
Messages sent by producers are not received by consumers.
Possible causes:

Limit behaviors are causing messages to be deleted on the broker. Message timeout value is expiring. Clocks are not synchronized. Consuming client failed to start message delivery on a connection.
Possible cause: Limit behaviors are causing messages to be deleted on the broker.
When the number of messages or message bytes in destination memory reach configured limits, the broker attempts to conserve memory resources. Three of the configurable behaviors adopted by the broker when these limits are reached will cause messages to be lost: REMOVE_OLDEST: Delete the oldest messages. REMOVE_LOW_PRIORITY: Delete the lowest-priority messages according to age. REJECT_NEWEST: Reject new persistent messages. To confirm this cause of the problem: Use the QBrowser demo application to inspect the contents of the dead message queue (see To Inspect the Dead Message Queue on page 308). Check whether the JMS_SUN_DMQ_UNDELIVERED_REASON property of messages in the queue has the value REMOVE_OLDEST or REMOVE_LOW_PRIORITY. To resolve the problem: Increase the destination limits. For example: imqcmd update dst -n MyDest -o maxNumMsgs=1000

Possible cause: Message timeout value is expiring.
The broker deletes messages whose timeout value has expired. If a destination gets sufficiently backlogged with messages, messages whose time-to-live value is too short might be deleted. To confirm this cause of the problem: Use the QBrowser demo application to inspect the contents of the dead message queue (see To Inspect the Dead Message Queue on page 308). Check whether the JMS_SUN_DMQ_UNDELIVERED_REASON property of messages in the queue has the value EXPIRED. To resolve the problem: Contact the application developers and have them increase the time-to-live value.
Possible cause: The broker clock and producer clock are not synchronized.
If clocks are not synchronized, broker calculations of message lifetimes can be wrong, causing messages to exceed their expiration times and be deleted. To confirm this cause of the problem: Use the QBrowser demo application to inspect the contents of the dead message queue (see To Inspect the Dead Message Queue on page 308).
Dead Message Queue Contains Messages
Check whether the JMS_SUN_DMQ_UNDELIVERED_REASON property of messages in the queue has the value EXPIRED. In the broker log file, look for any of the following messages: B2102, B2103, B2104. These messages all report that possible clock skew was detected. To resolve the problem: Check that you are running a time synchronization program, as described in Preparing System Resources on page 69.
Possible cause: Consuming client failed to start message delivery on a connection.
Messages cannot be delivered until client code establishes a connection and starts message delivery on the connection. To confirm this cause of the problem: Check that client code establishes a connection and starts message delivery. To resolve the problem: Rewrite the client code to establish a connection and start message delivery.

Symptom:
When you list destinations, you see that the dead message queue contains messages. For example, issue a command like the following: imqcmd list dst After you supply a user name and password, output like the following appears:
Listing all the destinations on the broker specified by: --------------------------------Host Primary Port --------------------------------localhost 7676 ---------------------------------------------------------------------Name Type State Producers Consumers Msgs Total Count UnAck Avg Size ------------------------------------------------- ---------------------MyDest Queue RUNNING 0 0 5 0 1177.0 mq.sys.dmq Queue RUNNING 0 0 35 0 1422.0 Successfully listed destinations.
In this example, the dead message queue, mq.sys.dmq, contains 35 messages. Possible causes:

The number of messages, or their sizes, exceed destination limits. The broker clock and producer clock are not synchronized.
303
An unexpected broker error has occurred. Consumers are not receiving messages before they time out. There are a number of possible reasons for messages to time out:

There are too many producers for the number of consumers. Producers are faster than consumers. A consumer is too slow. Clients are not committing messages. Consumers are failing to acknowledge messages. Durable consumers are inactive.
Possible cause: The number of messages, or their sizes, exceed destination limits. To confirm this cause of the problem: Use the QBrowser demo application to inspect the contents of the dead message queue (see To Inspect the Dead Message Queue on page 308). Check the values for the following message properties:
JMS_SUN_DMQ_UNDELIVERED_REASON JMS_SUN_DMQ_UNDELIVERED_COMMENT JMS_SUN_DMQ_UNDELIVERED_TIMESTAMP Under JMS Headers, scroll down to the value for JMSDestination to determine the destination whose messages are becoming dead. To resolve the problem: Increase the destination limits. For example: imqcmd update dst -n MyDest -o maxNumMsgs=1000
Possible cause: The broker clock and producer clock are not synchronized.
If clocks are not synchronized, broker calculations of message lifetimes can be wrong, causing messages to exceed their expiration times and be deleted. To confirm this cause of the problem: Use the QBrowser demo application to inspect the contents of the dead message queue (see To Inspect the Dead Message Queue on page 308). Check whether the JMS_SUN_DMQ_UNDELIVERED_REASON property of messages in the queue has the value EXPIRED. In the broker log file, look for any of the following messages: B2102, B2103, B2104. These messages all report that possible clock skew was detected. To resolve the problem: Check that you are running a time synchronization program, as described in Preparing System Resources on page 69.
Possible cause: An unexpected broker error has occurred. To confirm this cause of the problem: Use the QBrowser demo application to inspect the contents of the dead message queue (see To Inspect the Dead Message Queue on page 308). Check whether the JMS_SUN_DMQ_UNDELIVERED_REASON property of messages in the queue has the value ERROR. To resolve the problem:
Examine the broker log file to find the associated error. Contact Sun Technical Support to report the broker problem.
Possible cause: Consumers are not consuming messages before they time out. To confirm this cause of the problem: Use the QBrowser demo application to inspect the contents of the dead message queue (see To Inspect the Dead Message Queue on page 308).
Check whether the JMS_SUN_DMQ_UNDELIVERED_REASON property of messages in the queue has the value EXPIRED. Check to see if there any consumers on the destination and the value for the Current Number of Active Consumers. For example: imqcmd query dst -t q -n MyDest If there are active consumers, then there might be any number of possible reasons why messages are timing out before being consumed. One is that the message timeout is too short for the speed at which the consumer executes. In that case, request that application developers increase message time-to-live values. Otherwise, investigate the following possible causes for messages to time out before being consumed:
Possible cause: There are too many producers for the number of consumers. To confirm this cause of the problem: Use the QBrowser demo application to inspect the contents of the dead message queue (see To Inspect the Dead Message Queue on page 308).
Check whether the JMS_SUN_DMQ_UNDELIVERED_REASON property of messages in the queue has the value REMOVE_OLDEST or REMOVE_LOW_PRIORITY. If so, use the imqcmd query dst command to check the number of producers and consumers on the destination. If the number of producers exceeds the number of consumers, the production rate might be overwhelming the consumption rate. To resolve the problem: Add more consumer clients or set the destinations limit behavior to FLOW_CONTROL (which uses consumption rate to control production rate), using a command such as the following: imqcmd update dst -n myDst -t q -o limitBehavior=FLOW_CONTROL
Possible cause: Producers are faster than consumers. To confirm this cause of the problem: To determine whether slow consumers are causing producers to slow down, set the destinations limit behavior to FLOW_CONTROL (which uses consumption rate to control production rate), using a command such as the following:
imqcmd update dst -n myDst -t q -o limitBehavior=FLOW_CONTROL Use metrics to examine the destinations input and output, using a command such as the following: imqcmd metrics dst -n myDst -t q -m rts In the metrics output, examine the following values:
Msgs/sec Out: Shows how many messages per second the broker is removing. The broker removes messages when all consumers acknowledge receiving them, so the metric reflects consumption rate. Msgs/sec In: Shows how many messages per second the broker is receiving from producers. The metric reflects production rate.
Because flow control aligns production to consumption, note whether production slows or stops. If so, there is a discrepancy between the processing speeds of producers and consumers. You can also check the number of unacknowledged (UnAcked) messages sent, by using the imqcmd list dst command. If the number of unacknowledged messages is less than the size of the destination, the destination has additional capacity and is being held back by client flow control. To resolve the problem: If production rate is consistently faster than consumption rate, consider using flow control regularly, to keep the system aligned. In addition, consider and attempt to resolve each of the following possible causes, which are subsequently described in more detail:

A consumer is too slow. Clients are not committing messages. Consumers are failing to acknowledge messages. Durable consumers are inactive. An unexpected broker error has occurred.
Possible cause: A consumer is too slow. To confirm this cause of the problem: Use imqcmd metrics to determine the rate of production and consumption, as described above under Producers are faster than consumers.
Set the destinations limit behavior to FLOW_CONTROL, using a command such as the following: imqcmd update dst -n myDst -t q -o limitBehaviort=FLOW_CONTROL Use of flow control slows production to the rate of consumption and prevents the accumulation of messages in the destination. Producer applications hold messages until the destination can process them, with less risk of expiration.
Find out from application developers whether producers send messages at a steady rate or in periodic bursts. If an application sends bursts of messages, increase destination limits as described in the next item. Increase destination limits based on number of messages or bytes, or both. To change the number of messages on a destination, enter a command with the following format: imqcmd update dst -n destName -t {q|t} -o maxNumMsgs=number To change the size of a destination, enter a command with the following format: imqcmd update dst -n destName -t {q|t} -o maxTotalMsgBytes=number
306
Be aware that raising limits increases the amount of memory that the broker uses. If limits are too high, the broker could run out of memory and become unable to process messages.
Consider whether you can accept loss of messages during periods of high production load.
Possible cause: Clients are not committing transactions. To confirm this cause of the problem: Check with application developers to find out whether the application uses transactions. If so, list the active transactions as follows:
imqcmd list txn Here is an example of the command output:

---------------------------------------------------------------------Transaction ID State User name # Msgs/# Acks Creation time ---------------------------------------------------------------------6800151593984248832 STARTED guest 3/2 7/19/04 11:03:08 AM
Note the numbers of messages and number of acknowledgments. If the number of messages is high, producers may be sending individual messages but failing to commit transactions. Until the broker receives a commit, it cannot route and deliver the messages for that transaction. If the number of acknowledgments is high, consumers may be sending acknowledgments for individual messages but failing to commit transactions. Until the broker receives a commit, it cannot remove the acknowledgments for that transaction. To resolve the problem: Contact application developers to fix the coding error.
Possible cause: Consumers are failing to acknowledge messages. To confirm this cause of the problem: Contact application developers to determine whether the application uses system-based acknowledgment (AUTO_ACKNOWLEDGE or DUPES_ONLY) or client-based acknowledgment (CLIENT_ACKNOWLEDGE). If the application uses system-based acknowledgment , skip this section; if it uses client-based acknowledgment), first decrease the number of messages stored on the client, using a command like the following: imqcmd update dst -n myDst -t q -o consumerFlowLimit=1 Next, you will determine whether the broker is buffering messages because a consumer is slow, or whether the consumer processes messages quickly but does not acknowledge them. List the destination, using the following command: imqcmd list dst
After you supply a user name and password, output like the following appears:
Listing all the destinations on the broker specified by: --------------------------------Host Primary Port --------------------------------localhost 7676 ---------------------------------------------------------------------Name Type State Producers Consumers Msgs
Total Count UnAck Avg Size ------------------------------------------------ ----------------------MyDest Queue RUNNING 0 0 5 200 1177.0 mq.sys.dmq Queue RUNNING 0 0 35 0 1422.0 Successfully listed destinations.
The UnAck number represents messages that the broker has sent and for which it is waiting for acknowledgment. If this number is high or increasing, you know that the broker is sending messages, so it is not waiting for a slow consumer. You also know that the consumer is not acknowledging the messages. To resolve the problem: Contact application developers to fix the coding error.
Possible cause: Durable subscribers are inactive. To confirm this cause of the problem: Look at the topics durable subscribers, using the following
command format: imqcmd list dur -d topicName To resolve the problem:

Purge the durable subscribers using the imqcmd purge dur command. Restart the consumer applications.
To Inspect the Dead Message Queue

A number of troubleshooting procedures involve an inspection of the dead message queue (mq.sys.dmq). The following procedure explains how to carry out such an inspection by using the QBrowser demo application.
Locate the QBrowser demo application. See Appendix A, Distribution-Specific Locations of Message Queue Data, and look in the tables for Example Applications and Locations.
Run the QBrowser application. Here is an example invocation on the Windows platform: cd \MessageQueue3\demo\applications\qbrowser java QBrowser The QBrowser main window appears.
308
Select the queue name mq.sys.dmq and click Browse. A list like the following appears:
309
Double-click any message to display details about that message: The display should resemble the following:
You can inspect the Message Properties pane to determine the reason why the message was placed in the dead message queue.
310
P A R T
I I I
Reference

Chapter 16, Command Line Reference Chapter 17, Broker Properties Reference Chapter 18, Physical Destination Property Reference Chapter 19, Administered Object Attribute Reference Chapter 20, JMS Resource Adapter Property Reference Chapter 21, Metrics Information Reference Chapter 22, JES Monitoring Framework Reference
311
312
16
C H A P T E R

1 6
Command Line Reference
This chapter provides reference information on the use of the Message Queue command line administration utilities. It consists of the following sections: Command Line Syntax on page 313 Broker Utility on page 314 Command Utility on page 318 Object Manager Utility on page 327 Database Manager Utility on page 329 User Manager Utility on page 331 Bridge Manager Utility on page 332 Service Administrator Utility on page 334 Key Tool Utility on page 336
Command Line Syntax

Message Queue command line utilities are shell commands. The name of the utility is a command and its subcommands or options are arguments passed to that command. There is no need for separate commands to start or quit the utility. All the command line utilities share the following command syntax: utilityName [subcommand] [commandArgument] [ [-optionName [optionArgument] ] ... ] where utilityName is one of the following:

imqbrokerd (Broker utility) imqcmd (Command utility) imqobjmgr (Object Manager utility) imqdbmgr (Database Manager utility) imqusermgr (User Manager utility) imqbridgemgr (Bridge Manager utility)
313
Broker Utility
imqsvcadmin (Service Administrator utility) imqkeytool (Key Tool utility)
Subcommands and command-level arguments, if any, must precede all options and their arguments; the options themselves may appear in any order. All subcommands, command arguments, options, and option arguments are separated with spaces. If the value of an option argument contains a space, the entire value must be enclosed in quotation marks. (It is generally safest to enclose any attribute-value pair in quotation marks.) The following command, which starts the default broker, is an example of a command line with no subcommand clause: imqbrokerd Here is a fuller example: imqcmd destroy dst -t q -n myQueue -u admin -f -s This command destroys a queue destination (destination type q) named myQueue. Authentication is performed on the user name admin; the command will prompt for a password. The command will be performed without prompting for confirmation (-f option) and in silent mode, without displaying any output (-s option).
Broker Utility
The Broker utility (imqbrokerd) starts a broker. Command line options override values in the broker configuration files, but only for the current broker session. Table 161 shows the options to the imqbrokerd command and the configuration properties, if any, overridden by each option.
TABLE 161 Option
Broker Utility Options

Properties Overridden Description
-name instanceName
imq.instancename
Instance name of broker Multiple broker instances running on the same host must have different instance names. Default value: imqbroker
-port portNumber
imq.portmapper.port
Port number for brokers Port Mapper Message Queue clients use this port number to connect to the broker. Multiple broker instances running on the same host must have different Port Mapper port numbers. Default value: 7676
314
Broker Utility
TABLE 161 Option
(Continued)
-cluster broker1 [ [ ,broker2 ] ] imq.cluster.brokerlist
Connect brokers into cluster1 The specified brokers are merged with the list in the imq.cluster.brokerlist property. Each broker argument has one of the forms hostName:portNumber hostName :portNumber If hostName is omitted, the default value is localhost; if portNumber is omitted, the default value is 7676.
-Dproperty=value
Corresponding property in instance configuration file
Set configuration property See Chapter 17, Broker Properties Reference, for information about broker configuration properties. Caution: Be careful to check the spelling and formatting of properties set with this option. Incorrect values will be ignored without notification or warning.
-reset props
None
Reset configuration properties Replaces the brokers existing instance configuration file config.properties with an empty file; all properties assume their default values.
-reset store
None
Reset persistent data store Clears all persistent data from the data store (including persistent messages, durable subscriptions, and transaction information), allowing you to start the broker instance with a clean slate. To prevent the persistent store from being reset on subsequent restarts, restart the broker instance without the -reset option. To clear only persistent messages or durable subscriptions, use -reset messages or -reset durables instead.
-reset messages -reset durables

1
None None
Clear persistent messages from data store Clear durable subscriptions from data store
Applies only to broker clusters
Chapter 16 Command Line Reference
315
Broker Utility
TABLE 161 Option
(Continued)
-backup fileName
None
Back up configuration change record to file1 See Managing a Conventional Cluster's Configuration Change Record on page 186 for more information.
-restore fileName
None
Restore configuration change record from backup file1 The backup file must have been previously created using the -backup option. See Managing a Conventional Cluster's Configuration Change Record on page 186 for more information.
-remove instance
None
Remove broker instance2 Deletes the instance configuration file, log files, persistent store, and other files and directories associated with the instance.
-dbuser userName -passfile filePath
imq.persist.jdbc.user imq.passfile.enabled imq.passfile.dirpath imq.passfile.name
User name for JDBC-based persistent data store Location of password file Sets the brokers imq.passfile.enabled property to true, imq.passfile.dirpath to the path containing the password file, and imq.passfile.name to the file name itself. See Password Files on page 170 for more information.
-shared
imq.jms.threadpool_model
Use shared thread pool model to implement jms connection service Execution threads will be shared among connections to increase the number of connections supported. Sets the brokers imq.jms.threadpool_model property to shared.
-javahome path
None
Location of alternative Java runtime Default behavior: Use runtime installed on system or bundled with Message Queue.
1 2
Applies only to broker clusters Requires user confirmation unless -force is also specified
316
Broker Utility
TABLE 161 Option
(Continued)
-vmargs arg1 [ [ arg2 ] ]
None
Pass arguments to Java virtual machine Arguments are separated with spaces. To pass more than one argument, or an argument containing a space, enclose the argument list in quotation marks. VM arguments can be passed only from the command line; there is no associated configuration property in the instance configuration file.
-startRmiRegistry -useRmiRegistry -rmiRegistryPort -upgrade-store-nobackup
imq.jmx.rmiregistry.start imq.jmx.rmiregistry.use imq.jmx.rmiregistry.port None
Start RMI registry at broker startup Use external RMI registry Port number of RMI registry Automatically remove old data store on upgrade to Message Queue 3.5 or 3.5 SPx from an incompatible version2 See the Message Queue Installation Guide for more information.
-force
None
Perform action without user confirmation This option applies only to the -remove instance and -upgrade-store-nobackup options, which normally require confirmation.
-loglevel level
imq.broker.log.level
Logging level: NONE ERROR WARNING INFO Default value: INFO
-metrics interval -tty
imq.metrics.interval imq.log.console.output
Logging interval for broker metrics, in seconds Log all messages to console Sets the brokers imq.log.console.output property to ALL. If not specified, only error and warning messages will be logged.
Requires user confirmation unless -force is also specified
317
Command Utility
TABLE 161 Option
(Continued)
-s | -silent
imq.log.console.output
Silent mode (no logging to console) Sets the brokers imq.log.console.output property to NONE.
-version -h | -help
3
None None
Display version information3 Display usage help3
Command Utility
The Command utility (imqcmd) is used for managing brokers, connection services, connections, physical destinations, durable subscriptions, and transactions. All imqcmd commands must include a subcommand (except those using the -v or -h option to display product version information or usage help, respectively). The possible subcommands are listed in Table 162 and described in detail in the corresponding sections below. In addition, each imqcmd subcommand supports the general options shown in General Command Utility Options on page 320.
Note The -u userName option (and corresponding password) is required except when using the -v or -h option. Also if a subcommand accepts a broker address (-b option) and no host name or port number is specified, the values localhost and 7676 are assumed by default.
TABLE 162
Command Utility Subcommands
Broker Management on page 321 shutdown bkr restart bkr pause bkr quiesce bkr unquiesce bkr resume bkr takeover bkr update bkr reload cls Shut down broker Restart broker Pause broker Quiesce broker Unquiesce broker Resume broker Initiate broker takeover Set broker properties Reload cluster configuration
318
Command Utility
TABLE 162

List brokers in cluster Display broker metrics
(Continued)
query bkr list bkr metrics bkr
List broker property values
Connection Service Management on page 323 pause svc resume svc update svc list svc query svc metrics svc Pause connection service Resume connection service Set connection service properties List connection services available on broker List connection service property values Display connection service metrics
Connection Management on page 324 list cxn query cxn destroy cxn List connections on broker Display connection information Destroy connection
Physical Destination Management on page 324 create dst destroy dst pause dst resume dst purge dst compact dst update dst list dst query dst metrics dst Create physical destination Destroy physical destination Pause message delivery for physical destination Resume message delivery for physical destination Purge all messages from physical destination Compact physical destination Set physical destination properties List physical destinations List physical destination property values Display physical destination metrics
Durable Subscription Management on page 326 destroy dur purge dur list dur Destroy durable subscription Purge all messages for durable subscription List durable subscriptions for topics
319
Command Utility
TABLE 162

Commit transaction Roll back transaction
(Continued)
Transaction Management on page commit txn rollback txn list txn query txn list dur
List transactions being tracked by broker Display transaction information List durable subscriptions for topic
JMX Management on page 327 list jmx List JMX service URLs of JMX connectors
General Command Utility Options

The additional options listed in Table 163 can be applied to any subcommand of the imqcmd command.
TABLE 163 Option

Description
-secure -u userName
Use secure connection to broker with ssladmin connection service User name for authentication If this option is omitted, the Command utility will prompt for it interactively.
-passfile path
Location of password file See Password Files on page 170 for more information.
-D
Set connection-related system property that affects how imqcomd creates a connection to the broker. Not used to set broker configuration properties. Usually overrides connection factory attributes for imqcmd client runtime. For example, the option in the following command changes the default value of imqSSLIsTrusted: imqcmd list svc -secure -DimqSSLIsTrusted=true
-rtm timeoutInterval
Initial timeout interval, in seconds This is the initial length of time that the Command utility will wait for a reply from the broker before retrying a request. Each subsequent retry will use a timeout interval that is a multiple of this initial interval. Default value: 10.
320
Command Utility
TABLE 163 Option

Description
(Continued)
-rtr numRetries
Number of retries to attempt after a broker request times out Default value: 5.
-javahome path
-f -s -v -h -H
1 2
Perform action without user confirmation Silent mode (no output displayed) Display version information1,2 Display usage help1,2 Display expanded usage help, including attribute list and examples1,2
Any other options specified on the command line are ignored. User name and password not needed
Broker Management
The Command utility cannot be used to start a broker; use the Broker utility (imqbrokerd) instead. Once the broker is started, you can use the imqcmd subcommands listed in Table 164 to manage and control it.
TABLE 164 Syntax
Command Utility Subcommands for Broker Management

Description
shutdown bkr [-b hostName:portNumber] [-time nSeconds] [-nofailover]
Shut down broker The -time option specifies the interval, in seconds, to wait before shutting down the broker. (The broker will not block, but will return immediately from the delayed shutdown request.) During the shutdown interval, the broker will not accept any new jms connections; admin connections will be accepted, and existing jms connections will continue to operate. A broker belonging to an enhanced cluster will not attempt to take over for any other broker during the shutdown interval. The -nofailover option indicates that no other broker is to take over the persistent data of the one being shut down. 1
321
Command Utility
TABLE 164 Syntax

Description
(Continued)
restart bkr [-b hostName:portNumber]
Restart broker Shuts down the broker and then restarts it using the same options specified when it was originally started.
pause bkr [-b hostName:portNumber]
Pause broker See Pausing and Resuming a Broker on page 91 for more information.
quiesce bkr [-b hostName:portNumber]
Quiesce broker The broker will stop accepting new connections; existing connections will continue to operate.
unquiesce bkr [-b hostName:portNumber]
Unquiesce broker The broker will resume accepting new connections, returning to normal operation.
resume bkr [-b hostName:portNumber] takeover bkr -n brokerID [-f]
Resume broker Initiate broker takeover 1 Before taking over a broker, you should first shut it down manually using the shutdown bkr subcommand with the -nofailover option. If the specified broker appears to be still running, takeover bkr will display a confirmation message (Do you want to take over for this broker?). The -f option suppresses this message and initiates the takeover unconditionally.
Note The takeover bkr subcommand is intended only for use in failed-takeover situations. You should use it only as a last resort, and not as a general way of forcibly taking over a running broker.
update bkr [-b hostName:portNumber] -o property1=value1 [ [-o property2=value2] ] reload cls
Set broker properties See Chapter 17, Broker Properties Reference, for information on broker properties. Reload cluster configuration1 Forces all persistent information to be brought up to date.
query bkr -b hostName:portNumber
List broker property values For brokers belonging to a cluster, also lists cluster properties such as broker list, master broker (for conventional clusters), and cluster identifier (for enhanced clusters).
322
Command Utility
TABLE 164 Syntax

Description
(Continued)
list bkr metrics bkr [-b hostName:portNumber] [-m metricType] [-int interval] [-msp numSamples]
List brokers in cluster Display broker metrics The -m option specifies the type of metrics to display: ttl: Messages and packets flowing into and out of the broker rts: Rate of flow of messages and packets into and out of the broker per second cxn: Connections, virtual memory heap, and threads Default value: ttl. The -int option specifies the interval, in seconds, at which to display metrics. Default value: 5. The -msp option specifies the number of samples to display. Default value: Unlimited (infinite).
Connection Service Management

Table 165 lists the imqcmd subcommands for managing connection services.
TABLE 165 Syntax
Command Utility Subcommands for Connection Service Management

Description
pause svc -n serviceName [-b hostName:portNumber] resume svc -n serviceName [-b hostName:portNumber] update svc -n serviceName [-b hostName:portNumber] -o property1=value1 [ [-o property2=value2] ] list svc [-b hostName:portNumber] query svc -n serviceName [-b hostName:portNumber]
Pause connection service The admin connection service cannot be paused. Resume connection service
Set connection service properties See Connection Properties on page 337 for information on connection service properties. List connection services available on broker List connection service property values
323
Command Utility
TABLE 165 Syntax

Description
(Continued)
metrics svc -n serviceName [-b hostName:portNumber] [-m metricType] [-int interval] [-msp numSamples]
Display connection service metrics The -m option specifies the type of metrics to display: ttl: Messages and packets flowing into and out of the broker by way of the specified connection service rts: Rate of flow of messages and packets into and out of the broker per second by way of the specified connection service cxn: Connections, virtual memory heap, and threads Default value: ttl. The -int option specifies the interval, in seconds, at which to display metrics. Default value: 5. The -msp option specifies the number of samples to display. Default value: Unlimited (infinite).
Connection Management
Table 166 lists the imqcmd subcommands for managing connections.
TABLE 166 Syntax

Description
list cxn [-svn serviceName] [-b hostName:portNumber]
List connections on broker Lists all connections on the broker to the specified connection service. If no connection service is specified, all connections are listed. Display connection information
query cxn -n connectionID [-b hostName:portNumber] destroy cxn -n connectionID [-b hostName:portNumber]
Destroy connection
Physical Destination Management

Table 167 lists the imqcmd subcommands for managing physical destinations. In all cases, the -t (destination type) option can take either of two values: q: Queue destination t: Topic destination
Command Utility
TABLE 167 Syntax

Description
create dst -t destType -n destName [ [-o property=value] ]
Create physical destination1 The destination name destName may contain only alphanumeric characters (no spaces) and must begin with an alphabetic character or the underscore (_) or dollar sign ($) character. It may not begin with the characters mq. Destroy physical destination1 This operation cannot be applied to a system-created destination, such as a dead message queue.
destroy dst -tdestType -n destName
pause dst [-t destType -n destName] [-pst pauseType]
Pause message delivery for physical destination Pauses message delivery for the physical destination specified by the -t and -n options. If these options are not specified, all destinations are paused. The -pst option specifies the type of message delivery to be paused: PRODUCERS: Pause delivery from message producers CONSUMERS: Pause delivery to message consumers ALL: Pause all message delivery Default value: ALL
resume dst [-t destType -n destName]
Resume message delivery for physical destination Resumes message delivery for the physical destination specified by the -t and -n options. If these options are not specified, all destinations are resumed.
purge dst -t destType -n destName compact dst [-t destType -n destName]
Purge all messages from physical destination Compact physical destination Compacts the file-based persistent data store for the physical destination specified by the -t and -n options. If these options are not specified, all destinations are compacted. A destination must be paused before it can be compacted.
update dst -t destType -n destName -o property1=value1 [ [ -o property2=value2] ]

1
Set physical destination properties See Chapter 18, Physical Destination Property Reference, for information on physical destination properties.
Cannot be performed in a broker cluster whose master broker is temporarily unavailable
325
Command Utility
TABLE 167 Syntax

Description
(Continued)
list dst [-t destType] [-tmp]
List physical destinations Lists all physical destinations of the type specified by the -t option. If no destination type is specified, both queue and topic destinations are listed. If the -tmp option is specified, temporary destinations are listed as well. List physical destination property values Display physical destination metrics The -m option specifies the type of metrics to display: ttl: Messages and packets flowing into and out of the destination and residing in memory rts: Rate of flow of messages and packets into and out of the destination per second, along with other rate information con: Metrics related to message consumers dsk: Disk usage Default value: ttl. The -int option specifies the interval, in seconds, at which to display metrics. Default value: 5. The -msp option specifies the number of samples to display. Default value: Unlimited (infinite).
query dst -t destType -n destName metrics dst -t destType -n destName [-m metricType] [-int interval] [-msp numSamples]
Durable Subscription Management

Table 168 lists the imqcmd subcommands for managing durable subscriptions.
TABLE 168 Syntax
Command Utility Subcommands for Durable Subscription Management

Description
destroy dur -n subscriberName -c clientID purge dur -n subscriberName -c clientID list dur -[d topicName]
Destroy durable subscription1 Purge all messages for durable subscription List durable subscriptions for the specified topic. If -d option is omitted then the command lists all durable subscriptions for all topics.
Cannot be performed in a conventional broker cluster whose master broker is temporarily unavailable
326
Object Manager Utility
Transaction Management
Table 169 lists the imqcmd subcommands for managing local (non-distributed) Message Queue transactions. Distributed transactions are managed by a distributed transaction manager rather than imqcmd.
TABLE 169 Syntax
Command Utility Subcommands for Transaction Management

Description
commit txn -n transactionID rollback txn -n transactionID list txn query txn -n transactionID
Commit transaction Roll back transaction List transactions being tracked by broker Display transaction information
JMX Management
The imqcmd subcommand shown in Table 1610 is used for administrative support of Java applications using the Java Management Extensions (JMX) application programming interface to configure and monitor Message Queue resources. See Appendix D, JMX Support, for further information on the broker's JMX support.
TABLE 1610 Syntax
Command Utility Subcommand for JMX Management

Description
list jmx
List JMX service URLs of JMX connectors

The Object Manager utility (imqobjmgr) creates and manages Message Queue administered objects. Table 1611 lists the available subcommands.
TABLE 1611 Subcommand
Object Manager Subcommands

Description
add delete list query
Add administered object to object store Delete administered object from object store List administered objects in object store Display administered object information
327
Object Manager Subcommands

Description
(Continued)
update
Modify administered object
Table 1612 lists the options to the imqobjmgr command.

TABLE 1612 Option
Object Manager Options

Description
-l lookupName -j attribute=value -t objectType
JNDI lookup name of administered object Attributes of JNDI object store (see Object Stores on page 195) Type of administered object: q: Queue destination t: Topic destination cf: Connection factory qf: Queue connection factory tf: Topic connection factory xcf: Connection factory for distributed transactions xqf: Queue connection factory for distributed transactions xtf: Topic connection factory for distributed transactions Attributes of administered object (see Administered Object Attributes on page 198 and Chapter 19, Administered Object Attribute Reference) Is administered object read-only? If true, client cannot modify objects attributes. Default value: false.
-o attribute=value -r readOnlyState
-i fileName -pre
Name of command file containing all or part of subcommand clause Preview results without performing command This option is useful for checking the values of default attributes.
-javahome path
-f -s -v -h
1
328
Database Manager Utility
TABLE 1612 Option
Object Manager Options

Description
(Continued)
-H
1
Display expanded usage help, including attribute list and examples1

The Database Manager utility (imqdbmgr) sets up the database schema for a JDBC-based data store. You can also use it to delete Message Queue database tables that have become corrupted, change the database, display information about the database, convert a standalone database for use in an enhanced broker cluster, or back up and restore a highly-available database. Table 1613 lists the imqdbmgr subcommands.
Database Manager Subcommands

Description
create all
Create new database and persistent data store schema Used on embedded database systems. The broker property imq.persist.jdbc.vendorName.createdburl must be specified.
create tbl
Create persistent data store schema for existing database Used on external database systems. For brokers belonging to an enhanced broker cluster (imq.cluster.ha = true), the schema created is for the clusters shared data store, in accordance with the database vendor identified by the brokers imq.persist.jdbc.dbVendor property. If imq.cluster.ha = false, the schema is for the individual brokers standalone data store. Since the two types of data store can coexist in the same database, they are distinguished by appending a suffix to all table names: C clusterID: Shared data store S brokerID: Standalone data store
delete tbl delete oldtbl
Delete Message Queue database tables from current data store Delete Message Queue database tables from earlier-version data store Used after the data store has been automatically migrated to the current version of Message Queue.
recreate tbl
Re-create persistent store schema Deletes all existing Message Queue database tables from the current persistent store and then re-creates the schema.
query
Display information about the data store
329
Database Manager Subcommands

Description
(Continued)
upgrade hastore backup restore remove bkr
Upgrade standalone data store to shared data store Back up JDBC-based data store to backup files Restore JDBC-based data store from backup files Remove broker from shared data store The broker must not be running.
remove jmsbridge
Remove JMS bridge from the shared data store The broker hosting the JMS bridge must not be running.
reset lck
Reset data store lock Resets the lock so that the database can be used by other processes.
Table 1614 lists the options to the imqdbmgr command.

TABLE 1614 Option
Database Manager Options

Description
-b instanceName -Dproperty=value
Instance name of broker Set broker configuration property See Persistence Properties on page 346 for information about persistence-related broker configuration properties. Caution: Be careful to check the spelling and formatting of properties set with this option. Incorrect values will be ignored without notification or warning.
-u userName -passfile filePath
User name for authentication against the database Location of password file See Password Files on page 170 for more information.
-n brokerID -n bridgeName -dir dirPath -v

1
(Used with the remove bkr subcommand) Broker identifier of broker to be removed from shared data store (Used with the remove jmsbridge subcommand) Bridge name of the JMS bridge to be removed from shared data store Backup directory for backing up or restoring JDBC-based data store Display version information1
330
User Manager Utility
TABLE 1614 Option
Database Manager Options

Description
(Continued)
-h
1
Display usage help1
User Manager Utility

The User Manager utility (imqusermgr) is used for populating or editing a flat-file user repository. The utility must be run on the same host where the broker is installed; if a broker-specific user repository does not yet exist, you must first start up the corresponding broker instance in order to create it. You will also need the appropriate permissions to write to the repository: on the Solaris or Linux platforms, this means you must be either the root user or the user who originally created the broker instance. Table 1615 lists the subcommands available with the imqusermgr command. In all cases, the -i option specifies the instance name of the broker to whose user repository the command applies; if not specified, the default name imqbroker is assumed.
TABLE 1615 Syntax
User Manager Subcommands

Description
add [-i instanceName] -u userName -p password [-g group]
Add user and password to repository The optional -g option specifies a group to which to assign this user: admin user anonymous Delete user from repository
delete [-i instanceName] -u userName update [-i instanceName] -u userName -p password update [-i instanceName] -u userName -a activeStatus update [-i instanceName] -u userName -p password -a activeStatus list [-i instanceName] [-u userName]
Set users password or active status (or both) The -a option takes a boolean value specifying whether to make the user active (true) or inactive (false). An inactive status means that the user entry remains in the user repository, but the user will not be authenticated, even if using the correct password. Default value: true. Display user information If no user name is specified, all users in the repository are listed.
331
In addition, the options listed in Table 1616 can be applied to any subcommand of the imqusermgr command.
TABLE 1616 Option
General User Manager Options

Description
-f -s -v -h
1

The Bridge Manager utility (imqbridgemgr) is used to manage the bridges configured for a broker, including the links within bridge types that support links. The basic syntax of imqbridgemgr is:
imqbridgemgr imqbridgemgr imqbridgemgr imqbridgemgr subcommand commandArgument [ options ] -h | -help -H | -Help -v | -version
Table 1617 lists the imqbridgemgr subcommands for general bridge management, Table 1618 lists the imqbridgemgr subcommands for link management, which are applicable only to bridge types that support links, and Table 1619 lists the imqbridgemgr options.
Bridge Manager Subcommands for Bridge Management

Description
list bridge
Lists the bridges specified by the command options provided. For each bridge, the bridge name, type and state are displayed. Pauses the bridges specified by the command options provided if the bridge type supports this subcommand. Attempting to pause a bridge that is stopped generates an error, and attempting to pause a bridge that is already paused has no effect.
pause bridge
resume bridge
Resumes the bridges specified by the command options provided if the bridge type supports this subcommand. Attempting to resume a bridge that is stopped generates an error, and attempting to resume a bridge that is already started has no effect.
332
Bridge Manager Subcommands for Bridge Management

Description
(Continued)
start bridge
Starts the bridges specified by the command options provided. Attempting to start a bridge that is paused causes the bridge to resume, and attempting to start a bridge that is already started has no effect.
stop bridge
Stops the bridges specified by the command options provided. Attempting to stop a bridge that is paused causes the bridge to stop, and attempting to stop a bridge that is already stopped has no effect.
Bridge Manager Subcommands for Link Management

Description
list link
Lists the links specified by the command options provided. For each link, the link name, state, source, target, and transaction status are displayed. Pauses the link specified by the command options provided. Attempting to pause a link that is stopped, in the process of stopping, or has never been started generates an error. Attempting to pause a link that is already paused or in the process of pausing has no effect.
pause link
resume link
Resumes the link specified by the command options provided. Attempting to resume a link that is stopped, in the process of stopping, or has never been started generates an error. Attempting to resume a link that is already started or in the process of starting has no effect.
start link
Starts the link specified by the command options provided. Attempting to start a link that is paused causes the link to resume. Attempting to start a link that is in the process of pausing causes the link to complete pausing and then to resume. Attempting to start a link that is already started or in the process of starting has no effect.
stop link
Stops the link specified by the command options provided. Attempting to stop a link that has never been started generates an error. Attempting to stop a link that is in the process of starting causes the link to complete starting and then to stop. Attempting to stop a link that is paused causes the link to stop. Attempting to stop a link that is in the process of pausing causes the link to complete pausing and then to stop. Attempting to stop a link that is already stopped or in the process of stopping has no effect.
Table 1619 lists the options to the imqbridgemgr command.
333
Service Administrator Utility
TABLE 1619 Option
Bridge Manager Options

Description
-b hostName:portNumber
The broker housing the bridge. Default value: localhost:7676
-bn bridgeName -f -javahome path
The name of the bridge. Perform the action without user confirmation Location of an alternative Java runtime. Default behavior: Use the runtime installed with Message Queue.
-ln linkName -passfile path -rtm timeoutInterval
The name of the link. Location of password file Initial timeout interval, in seconds This is the initial length of time that the Command utility will wait for a reply from the broker before retrying a request. Each subsequent retry will use a timeout interval that is a multiple of this initial interval. Default value: 10
-rtr numRetries
Number of retries to attempt after a broker request times out Default value: 5
-s -secure -t bridgeType -u userName
Silent mode (no output displayed) Use secure connection to broker with ssladmin connection service The type of the bridge: JMS or STOMP User name for authentication

The Service Administrator utility (imqsvcadmin) installs a broker as a Windows service. Table 1620 lists the available subcommands.
Service Administrator Subcommands

Description
install remove
Install service Remove service
334
Service Administrator Subcommands

Description
(Continued)
query
Display startup options Startup options can include whether the service is started manually or automatically, its location, the location of the Java runtime, and the values of arguments passed to the broker on startup (see Table 1621).
Table 1621 lists the options to the imqsvcadmin command.

TABLE 1621 Option
Service Administrator Options

Description
-javahome path
-jrehome path -vmargs arg1 [ [arg2] ]
Location of alternative Java Runtime Environment (JRE) Additional arguments to pass to Java Virtual Machine (JVM) running broker service1 Example: imqsvcadmin install -vmargs "-Xms16m -Xmx128m"
-args arg1 [ [arg2] ]
Additional command line arguments to pass to broker service1 Example: imqsvcadmin install -args "-passfile d:\\imqpassfile" See Broker Utility on page 314 for information about broker command line arguments.
-h
1
Display usage help2
These arguments can also be specified in the Start Parameters field under the General tab in the services Properties window (reached by way of the Services tool in the Windows Administrative Tools control panel). Any other options specified on the command line are ignored.
Any information you specify using the -javahome, -vmargs, and -args options is stored in the Windows registry under the keys JREHome, JVMArgs, and ServiceArgs in the path HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\iMQ_Broker\Parameters
335
Key Tool Utility
Key Tool Utility

The Key Tool utility (imqkeytool) generates a self-signed certificate for the broker, which can be used for the ssljms, ssladmin, or cluster connection service. The syntax is imqkeytool -broker On UNIX systems, you might need to run the utility from the root user account.
336
17
C H A P T E R

1 7
Broker Properties Reference
This chapter provides reference information about configuration properties for a message broker. It consists of the following sections: Connection Properties on page 337 Routing and Delivery Properties on page 340 Persistence Properties on page 346 Security Properties on page 351 Monitoring Properties on page 357 Cluster Configuration Properties on page 361 Bridge Properties on page 363 JMX Properties on page 366 Alphabetical List of Broker Properties on page 368
Connection Properties
Table 171 lists the broker properties related to connection services.
337
TABLE 171 Property
Broker Connection Properties

imq.brokerid
String
None
Broker identifier For brokers using a shared JDBC-based data store, this string is appended to the names of all database tables to identify each table with a particular broker. Must be a unique alphanumeric string of no more than n 13 characters, where n is the maximum table name length allowed by the database. This property is unnecessary for an embedded database or a standalone database which stores data for only one broker instance.
Note For enhanced broker clusters (imq.cluster.ha = true), database table names also use the imq.cluster.clusterid property (see Table 1712).
imq.service.activelist1
String
jms,admin
List of connection services to be activated at broker startup, separated by commas See Table 61 under Configuring Connection Services on page 95 for the names of the available connection services.
imq.hostname
String String
All available IP Default host name or IP address for all connection addresses services None Host name or IP address of Port Mapper If specified, overrides imq.hostname. This might be necessary, for instance, if the brokers host computer has more than one network interface card installed.
imq.portmapper.hostname
imq.portmapper.port2
Integer
7676
Port number of Port Mapper

Note If multiple broker instances are running on the same host, each must be assigned a unique Port Mapper port.
imq.serviceName.protocolType.hostname3
String
None
Host name or IP address for connection service If specified, overrides imq.hostname for the designated connection service. This might be necessary, for instance, if the brokers host computer has more than one network interface card installed.
1 2 3
Must have the same value for all brokers in an enhanced cluster. Can be used with imqcmd update bkr command jms, ssljms, admin, and ssladmin services only; see Appendix C, HTTP/HTTPS Support, for information on configuring the httpjms and httpsjms services
338
TABLE 171 Property

3
(Continued)
imq.serviceName.protocolType.port
Integer
Port number for connection service A value of 0 specifies that the port number should be allocated dynamically by the Port Mapper. You might need to set a different value, for instance, to specify a static port number for connecting to the broker through a firewall.
imq.portmapper.backlog imq.serviceName.threadpool_model4
Integer String
50
Maximum number of pending Port Mapper requests in operating system backlog Threading model for thread pool management: dedicated: Two dedicated threads per connection, one for incoming and one for outgoing messages shared: Connections processed by shared thread when sending or receiving messages The dedicated model limits the number of connections that can be supported, but provides higher performance; the shared model increases the number of possible connections, but at the cost of lower performance because of the additional overhead needed for thread management.
dedicated
imq.serviceName.min_threads
Integer
jms: 10 ssljms: 10 httpjms: 10 httpsjms: 10 admin: 4 ssladmin: 4
Minimum number of threads maintained in connection services thread pool When the number of available threads exceeds this threshold, threads will be shut down as they become free until the minimum is reached. The default value varies by connection service, as shown.
imq.serviceName.max_threads
Integer
jms: 1000 ssljms: 500 httpjms: 500 httpsjms : 500 admin: 10 ssladmin: 10
Number of threads beyond which no new threads are added to the thread pool for use by the named connection service Must be greater than 0 and greater than the value of imq.serviceName.min_threads. The default value varies by connection service, as shown.
3 4
jms, ssljms, admin, and ssladmin services only; see Appendix C, HTTP/HTTPS Support, for information on configuring the httpjms and httpsjms services jms and admin services only
Chapter 17 Broker Properties Reference
339
Routing and Delivery Properties
TABLE 171 Property

5
(Continued)
imq.shared.connectionMonitor_limit
Integer
Solaris: 512 Linux: 512 Windows: 64
Maximum number of connections monitored by a distributor thread The system allocates enough distributor threads to monitor all connections. The smaller the value of this property, the faster threads can be assigned to active connections. A value of 1 denotes an unlimited number of connections per thread. The default value varies by operating-system platform, as shown.
imq.ping.interval
Integer
120
Interval, in seconds, at which to test connection between client and broker A value of 0 or 1 disables periodic testing of the connection.
Shared threading model only

Table 172 lists the broker properties related to routing and delivery services. Properties that configure the automatic creation of destinations are listed in Table 173.
TABLE 172 Property
Broker Routing and Delivery Properties

imq.system.max_count1
Integer
Maximum number of messages held by broker A value of 1 denotes an unlimited message count.
imq.system.max_size
String
Maximum total size of messages held by broker The value may be expressed in bytes, kilobytes, or megabytes, using the following suffixes: b: Bytes k: Kilobytes (1024 bytes) m: Megabytes (1024 1024 = 1,048,576 bytes) An unsuffixed value is expressed in bytes; a value of 1 denotes an unlimited message capacity.
Can be used with imqcmd update bkr command
340
TABLE 172 Property
Broker Routing and Delivery Properties

Type
(Continued)
Examples: 1600: 1600 bytes 1600b: 1600 bytes 16k: 16 kilobytes (= 16,384 bytes) 16m: 16 megabytes (= 16,777,216 bytes) 1: No limit imq.message.max_size1 String 70m Maximum size of a single message body The syntax is the same as for imq.system.max_size (see above). imq.message.expiration.interval imq.resourceState.threshold Integer Integer 60 green: 0 yellow: 80 orange: 90 red: 98 green: 5000 yellow: 500 orange: 50 red: 0 Interval, in seconds, at which expired messages are reclaimed Percent utilization at which memory resource state is triggered (where resourceState is green, yellow, orange, or red) Maximum number of incoming messages allowed in a batch before checking whether memory resource state threshold has been reached (where resourceState is green, yellow, orange , or red) This limit throttles back message producers as system memory becomes increasingly scarce. imq.destination.DMQ.truncateBody1 Boolean false Remove message body before storing in dead message queue? If true, only the message header and property data will be saved. imq.transaction.autorollback Boolean false Automatically roll back distributed transactions left in prepared state at broker startup? If false, transactions must be manually committed or rolled back using the Command utility (imqcmd). imq.transaction.producer.maxNumMsgs Integer 1000 The maximum number of messages that a producer can process in a single transaction. It is recommended that the value be less than 5000 to prevent the exhausting of resources. The maximum number of messages that a consumer can process in a single transaction. It is recommended that the value be less than 1000 to prevent the exhausting of resources.
imq.resourceState.count
Integer
imq.transaction.consumer.maxNumMsgs
Integer
100
341
TABLE 173 Property
Broker Properties for Auto-Created Destinations

imq.autocreate.queue1,2 imq.autocreate.topic3 imq.autocreate.reaptime
Boolean Boolean Integer
true true 120 seconds
Allow auto-creation of queue destinations? Allow auto-creation of topic destinations? The delay, in seconds. before which auto-created destinations are removed from the system when they no longer have consumers nor contain messages, . A smaller value means that memory reclamation takes place more often. Maximum number of unconsumed messages A value of 1 denotes an unlimited number of messages.
Note When flow control is in effect (imq.autocreate.destination.limitBehavior = FLOW_CONTROL), it is possible for the specified message limit to be exceeded because the broker cannot react quickly enough to stop the flow of incoming messages. In such cases, the value specified for imq.autocreate.destination.maxNumMsgs serves as merely a hint for the broker rather than a strictly enforced limit. However, if the number of unconsumed messages would exceed imq.system.max_count, the broker generates a ResourceAllocationException indicating that the destination is full and rejecting new messages.
imq.autocreate.destination.maxNumMsgs
Integer
100000
imq.autocreate.destination.maxBytesPerMsg
String
10k
Maximum size, in bytes, of any single message The value may be expressed in bytes, kilobytes, or megabytes, using the following suffixes: b: Bytes k: Kilobytes (1024 bytes) m: Megabytes (1024 1024 = 1,048,576 bytes) An unsuffixed value is expressed in bytes; a value of 1 denotes an unlimited message size.
1 2 3
Can be used with imqcmd update bkr command Queue destinations only Topic destinations only
342
TABLE 173 Property

Type
(Continued)
Examples: 1600: 1600 bytes 1600b: 1600 bytes 16k: 16 kilobytes (= 16,384 bytes) 16m: 16 megabytes (= 16,777,216 bytes) 1: No limit imq.autocreate.destination.maxTotalMsgBytes String 10m Maximum total memory, in bytes, for unconsumed messages The syntax is the same as for imq.autocreate.destination.maxBytesPerMsg (see above). imq.autocreate.destination.limitBehavior String REJECT_NEWEST Broker behavior when memory-limit threshold reached: FLOW_CONTROL: Slow down producers REMOVE_OLDEST: Throw out oldest messages REMOVE_LOW_PRIORITY: Throw out lowest-priority messages according to age; no notification to producing client REJECT_NEWEST: Reject newest messages; notify producing client with an exception only if message is persistent When FLOW_CONTROL is specified, it is still possible for the number of messages to exceed imq.system.max_count. In this situation, the broker generates a ResourceAllocationException indicating that the destination is full and rejecting new messages. If the value is REMOVE_OLDEST or REMOVE_LOW_PRIORITY and the imq.autocreate.destination.useDMQ property is true, excess messages are moved to the dead message queue. imq.autocreate.destination.maxNumProducers Integer 100 Maximum number of message producers for destination When this limit is reached, no new producers can be created. A value of 1 denotes an unlimited number of producers.
343
TABLE 173 Property

Type
2
(Continued)
imq.autocreate.queue.maxNumActiveConsumers
Integer
Maximum number of active message consumers in load-balanced delivery from queue destination A value of 1 denotes an unlimited number of consumers.
imq.autocreate.queue.maxNumBackupConsumers2
Integer
Maximum number of backup message consumers in load-balanced delivery from queue destination A value of 1 denotes an unlimited number of consumers.
imq.autocreate.queue.consumerFlowLimit2
Integer
1000
Maximum number of messages delivered to queue consumer in a single batch In load-balanced queue delivery, this is the initial number of queued messages routed to active consumers before load balancing begins. A destination consumer can override this limit by specifying a lower value on a connection. A value of 1 denotes an unlimited number of messages.
imq.autocreate.topic.consumerFlowLimit3
Integer
1000
Maximum number of messages delivered to topic consumer in a single batch A value of 1 denotes an unlimited number of consumers.
imq.autocreate.destination.isLocalOnly
Boolean
false
Local delivery only? This property applies only to destinations in broker clusters, and cannot be changed once the destination has been created. If true, the destination is not replicated on other brokers and is limited to delivering messages only to local consumers (those connected to the broker on which the destination is created).
2 3
Queue destinations only Topic destinations only
344
TABLE 173 Property

Type
2
(Continued)
imq.autocreate.queue.localDeliveryPreferred
Boolean
false
Local delivery preferred? This property applies only to load-balanced queue delivery in broker clusters. If true, messages will be delivered to remote consumers only if there are no consumers on the local broker; the destination must not be restricted to local-only delivery (imq.autocreate.destination.isLocalOnly must be false).
imq.autocreate.destination.useDMQ
Boolean
true
Send dead messages to dead message queue? If false, dead messages will simply be discarded.
validateXMLSchemaEnabled
Boolean
false
XML schema validation is enabled? If set to false or not set, then XML schema validation is not enabled for the destination.
XMLSchemaURIList
String
null
Space separated list of XML schema document (XSD) URI strings The URIs point to the location of one or more XSDs to use for XML schema validation, if enabled. Use double quotes around this value if multiple URIs are specified. Example: http://foo/flap.xsd http://test.com/test.xsd If this property is not set or null and XML validation is enabled, XML validation is performed using a DTD specified in the XML document.
reloadXMLSchemaOnFailure
Boolean
false
Reload XML schema on failure enabled? If set to false or not set, then the schema is not reloaded if validation fails.
Queue destinations only
345
Persistence Properties
Message Queue supports both file-based and JDBC-based persistence modules. The broker property imq.persist.store (Table 174) specifies which module to use. The following sections describe the broker configuration properties for the two modules.
TABLE 174 Property
Global Broker Persistence Property

imq.persist.store
String
file
Module used for persistent data storage: file: File-based persistence jdbc: JDBC-based persistence Must be set to jdbc for enhanced broker clusters (imq.cluster.ha = true).
File-Based Persistence Properties

Table 175 lists the broker properties related to file-based persistence.
TABLE 175
Broker Properties for File-Based Persistence

Property
imq.persist.file.message.max_record_size
String
1m
Maximum-size message to add to message storage file Any message exceeding this size will be stored in a separate file of its own. The value may be expressed in bytes, kilobytes, or megabytes, using the following suffixes: b: Bytes k: Kilobytes (1024 bytes) m: Megabytes (1024 1024 = 1,048,576 bytes) An unsuffixed value is expressed in bytes. Examples: 1600: 1600 bytes 1600b: 1600 bytes 16k: 16 kilobytes (= 16,384 bytes) 16m: 16 megabytes (= 16,777,216 bytes)
346
TABLE 175 Property
Broker Properties for File-Based Persistence
(Continued)
imq.persist.file.destination.message.filepool.limit
Integer
100
Maximum number of free files available for reuse in destination file pool Free files in excess of this limit will be deleted. The broker will create and delete additional files in excess of the limit as needed. The higher the limit, the faster the broker can process persistent data.
imq.persist.file.message.filepool.cleanratio
Integer
Percentage of files in free file pools to be maintained in a clean (empty) state The higher this value, the less disk space is required for the file pool, but the more overhead is needed to clean files during operation.
imq.persist.file.message.cleanup
Boolean
false
Clean up files in free file pools on shutdown? Setting this property to true saves disk space for the file store, but slows broker shutdown.
imq.persist.file.sync.enabled
Boolean
false
Synchronize in-memory state with physical storage device? Setting this property to true eliminates data loss due to system crashes, but at a cost in performance.
Note If running Sun Cluster and the Sun
Cluster Data Service for Message Queue, set this property to true for brokers on all cluster nodes. imq.persist.file.transaction.memorymappedfile.enabled Boolean true Use memory-mapped file to store transaction data? Setting this property to true improves performance at the cost of increased memory usage. Set to false for file systems that do not support memory-mapped files.
File-Based Persistence Properties for Transaction Logging

Table 176 lists the file-based persistence properties for the transaction logging mechanism introduced in Message Queue 4.4 Update 1.
Chapter 17 Broker Properties Reference 347
TABLE 176
Broker Properties for File-Based Persistence Using the Transaction Logging Mechanism
Property
imq.persist.file.newTxnLog.enabled
Boolean
false
Enables the transaction logging mechanism introduced in Message Queue 4.4 Update 1. For information about this mechanism, see Optimizing File-Based Transaction Persistence on page 130. This property is applicable only if imq.persist.file.newTxnLog.enabled is true. Can improve performance if imq.persist.file.sync.enabled is true and the number of concurrent transactions being processed is high: If true, write operations to the transaction log are not handled by individual connection threads; instead, writes from connection threads are added to a transaction queue. The connection threads then wait until they are notified that the transactions have been logged. A separate thread periodically drains the transaction queue and writes it to the transaction log. When possible, this thread groups together multiple active transactions and writes them to the transaction log in a single operation. After the write completes, waiting client threads are notified.
imq.persist.file.txnLog.groupCommit
Boolean
false
If false, write operations to the transaction log are handled by individual connection threads. Only one thread at a time is able to write to the log.
348
TABLE 176 Property
Broker Properties for File-Based Persistence Using the Transaction Logging Mechanism
(Continued)
imq.persist.file.txnLog.logNonTransactedMsgSend
Boolean
false
This property is applicable only if imq.persist.file.newTxnLog.enabled is true. Overrides the behavior for persisting non-transacted messages (as defined by the imq.persist.file.sync.enabled property): If true, non-transacted messages are written to the transaction log before they are written to the persistent store.
If false, non-transacted messages are written directly to the persistent store.
imq.persist.file.txnLog.logNonTransactedMsgAck
Boolean
false
This property is applicable only if imq.persist.file.newTxnLog.enabled is true. Overrides the behavior for persisting non-transacted message acknowledgements (as defined by the imq.persist.file.sync.enabled property): If true, acknowledgements of non-transacted messages are written to the transaction log before they are written to the persistent store.
If false, acknowledgements of non-transacted messages are written directly to the persistent store.
JDBC-Based Persistence Properties

Table 177 lists the broker properties related to JDBC-based persistence. The first of these properties, imq.persist.jdbc.dbVendor, identifies the database vendor being used for the brokers persistent data store; all of the remaining properties are qualified by this vendor name.
349
TABLE 177
Broker Properties for JDBC-Based Persistence

Property
imq.persist.jdbc.dbVendor
String
None
Name of database vendor for persistent data store: hadb: HADB (Sun Microsystems, Inc.) derby: Java DB (Sun Microsystems, Inc.) oracle: Oracle (Oracle Corporation) mysql: MySQL (Sun Microsystems, Inc.) postgresql: postgreSQL The maximum number of connections that can be opened to the database. Java class name of JDBC driver, if needed, for connecting to database from vendor vendorName URL for connecting to existing database from vendor vendorName Applicable when driver is used to connect to database.
imq.persist.jdbc.connection.limit imq.persist.jdbc.vendorName.driver imq.persist.jdbc.vendorName.opendburl
Integer String String
5 per vendor None
imq.persist.jdbc.vendorName.createdburl1
String
None
URL for creating new database from vendor vendorName Applies for embedded database, such as Java DB.
imq.persist.jdbc.vendorName.closedburl1
String
None
URL for closing connection to database from vendor vendorName Applies for some embedded databases, such as Java DB.
imq.persist.jdbc.vendorName.user1
String
None
User name, if required, for connecting to database from vendor vendorName For security reasons, the value can instead be specified using command line options imqbrokerd -dbuser and imqdbmgr -u.
imq.persist.jdbc.vendorName.needpassword1
Boolean
false
Does database from vendor vendorName require a password for broker access? If true, the imqbrokerd and imqdbmgr commands will prompt for a password, unless you use the -passfile option to specify a password file containing it.
imq.persist.jdbc.vendorName.password1,2
1 2
String
None
Password, if required, for connecting to database from vendor vendorName
Optional Should be used only in password files
350
Security Properties
TABLE 177 Property
Broker Properties for JDBC-Based Persistence

Type
1
(Continued)
imq.persist.jdbc.vendorName.property.propName imq.persist.jdbc.vendorName.tableoption1
1
String String
None None
Vendor-specific property propName for database from vendor vendorName Vendor-specific options passed to the database when creating the table schema.
Optional
Security Properties
Table 178 lists broker properties related to security services: authentication, authorization, and encryption. Table 179 lists broker properties related specifically to LDAP-based authentication, and Table 1710 lists broker properties related specifically to JAAS-based authentication.
TABLE 178 Property
Broker Security Properties

imq.authentication.basic.user_repository
String
file
Type of user authentication: file: File-based ldap: Lightweight Directory Access Protocol jaas: Java Authentication and Authorization Service Password encoding method: digest: MD5 (for file-based authentication) basic: Base-64 (for LDAP or JAAS authentication) Password encoding method for connection service serviceName: digest: MD5 (for file-based authentication) basic: Base-64 (for LDAP or JAAS authentication) If specified, overrides imq.authentication.type for the designated connection service.
imq.authentication.type
String
digest
imq.serviceName.authentication.type
String
None
351
Security Properties
TABLE 178 Property
(Continued)
imq.authentication.client.response.timeout
Integer
180
Interval, in seconds, to wait for client response to authentication requests Use access control? If true, the system will check the access control file to verify that an authenticated user is authorized to use a connection service or to perform specific operations with respect to specific destinations.
imq.accesscontrol.enabled
Boolean
true
imq.accesscontrol.type imq.serviceName.accesscontrol.enabled
String Boolean
file None
Specifies the access control type Use access control for connection service? If specified, overrides imq.accesscontrol.enabled for the designated connection service. If true, the system will check the access control file to verify that an authenticated user is authorized to use the designated connection service or to perform specific operations with respect to specific destinations.
imq.accesscontrol.file.filename
String
accesscontrol.properties Name of access control file The file name specifies a path relative to the access control directory (see Appendix A, Distribution-Specific Locations of Message Queue Data).
352
Security Properties
TABLE 178 Property
(Continued)
imq.serviceName.accesscontrol.file.filename
String
None
Name of access control file for connection service If specified, overrides imq.accesscontrol.file.filename for the designated connection service. The file name specifies a path relative to the access control directory (see Appendix A, Distribution-Specific Locations of Message Queue Data).
imq.accesscontrol.file.url imq.serviceName.accesscontrol.file.url
String String
Not set None
The location, as a URL, of the access control file. The location, as a URL, of the access control file for connection service If specified, overrides imq.accesscontrol.file.url for the designated connection service.
imq.keystore.file.dirpath
String
Path to directory containing key See Appendix A, Distribution-Specific store file Locations of Message Queue Data keystore None false Name of key store file Password for key store file Obtain passwords from password file?
imq.keystore.file.name imq.keystore.password1 imq.passfile.enabled
String String Boolean String
imq.passfile.dirpath
See Appendix A, Path to directory containing Distribution-Specific password file Locations of Message Queue Data passfile None Name of password file Password for administrative user The Command utility (imqcmd) uses this password to authenticate the user before executing a command.
imq.passfile.name imq.imqcmd.password1
String String
To be used only in password files
353
Security Properties
TABLE 178 Property
(Continued)
imq.audit.enabled
Boolean Boolean
false
Is audit logging to broker log file enabled? Is audit logging to the Solaris BSM audit log disabled?
imq.audit.bsm.disabled
true
Table 179 lists broker properties related to LDAP-based user authentication.

TABLE 179 Property
Broker Security Properties for LDAP Authentication

imq.user_repository.ldap.server
String
None
Host name and port number for LDAP server The value is of the form hostName:port where hostName is the fully qualified DNS name of the host running the LDAP server and port is the port number used by the server. To specify a list of failover servers, use the following syntax: host1:port1 ldap://host2: port2 ldap://host3 :port3 Entries in the list are separated by spaces. Note that each failover server address is prefixed with ldap://. Use this format even if you use SSL and have set the property imq.user_repository.ldap.ssl.enabled to true. You need not specify ldaps in the address.
imq.user_repository.ldap.principal
String
None
Distinguished name for binding to LDAP user repository Not needed if the LDAP server allows anonymous searches.
354
Security Properties
TABLE 179 Property

Type
1
(Continued)
imq.user_repository.ldap.password
String
None
Password for binding to LDAP user repository Not needed if the LDAP server allows anonymous searches.
imq.user_repository.ldap.propertyName imq.user_repository.ldap.base String String String None None None Directory base for LDAP user entries Provider-specific attribute identifier for LDAP user name When set to a value of dn, specifies that DN username format is used for authentication (for example: uid=mquser,ou=People,dc=red, dc=sun,dc=com). Also, the broker extracts the value of the imq.user.repository.lpdap.uidatr attribute from the DN username, and uses this value as the user name in access control operations. If not set, then normal username format is used. imq.user_repository.ldap.usrfilter2 imq.user_repository.ldap.grpsearch String Boolean None false JNDI filter for LDAP user searches Enable LDAP group searches?
Note Message Queue does not support nested groups.
imq.user_repository.ldap.uidattr
imq.user_repository.ldap.usrformat
imq.user_repository.ldap.grpbase
String String String
None None None
Directory base for LDAP group entries Provider-specific attribute identifier for LDAP group name Provider-specific attribute identifier for user names in LDAP group JNDI filter for LDAP group searches
imq.user_repository.ldap.gidattr
imq.user_repository.ldap.memattr
imq.user_repository.ldap.grpfilter2
1 2
String
None
Should be used only in password files Optional
355
Security Properties
TABLE 179 Property

Type
(Continued)
imq.user_repository.ldap.timeout
Integer Boolean
280
Time limit for LDAP searches, in seconds Use SSL when communicating with LDAP server?
imq.user_repository.ldap.ssl.enabled
false
Table 1710 lists broker properties related to JAAS-based user authentication.

TABLE 1710 Property
Broker Security Properties for JAAS Authentication

imq.user_repository.jaas.name
String
None
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 service. This is the name you noted in Step 3. 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. 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 user name passed from the Message Queue client when a connection was requested is used instead.
imq.user_repository.jaas.userPrincipalClass
String
None
imq.user_repository.jaas.groupPrincipalClass
String
None
356
Monitoring Properties
Table 1711 lists the broker properties related to monitoring services.
TABLE 1711 Property
Broker Monitoring Properties

imq.log.level1
String
INFO
Logging level Specifies the categories of logging information that can be written to an output channel. Possible values, from high to low: ERROR WARNING INFO Each level includes those above it (for example, WARNING includes ERROR).
imq.destination.logDeadMsgs1
Boolean
false
Log information about dead messages? If true, the following events will be logged: A destination is full, having reached its maximum size or message count.
The broker discards a message for a reason other than an administrative command or delivery acknowledgment. The broker moves a message to the dead message queue.
imq.log.console.stream
String
ERR
Destination for console output: OUT: stdout ERR: stderr
357
TABLE 1711 Property
(Continued)
imq.log.console.output
String
ERROR|WARNING
Categories of logging information to write to console: NONE ERROR WARNING INFO ALL The ERROR, WARNING, and INFO categories do not include those above them, so each must be specified explicitly if desired. Any combination of categories can be specified, separated by vertical bars (|).
imq.log.file.dirpath
String
See Appendix A, Distribution-Specific Locations of Message Queue Data log.txt ALL
Path to directory containing log file
imq.log.file.filename imq.log.file.output
String String
Name of log file Categories of logging information to write to log file: NONE ERROR WARNING INFO ALL The ERROR, WARNING, and INFO categories do not include those above them, so each must be specified explicitly if desired. Any combination of categories can be specified, separated by vertical bars (|).
imq.log.file.rolloverbytes1
Integer
File length, in bytes, at which output rolls over to a new log file A value of 1 denotes an unlimited number of bytes (no rollover based on file length).
358
TABLE 1711 Property

1
(Continued)
imq.log.file.rolloversecs
Integer
604800 (one week)
Age of file, in seconds, at which output rolls over to a new log file A value of 1 denotes an unlimited number of seconds (no rollover based on file age).
imq.log.syslog.output2
String
ERROR
Categories of logging information to write to syslogd(1M): NONE ERROR WARNING INFO ALL The ERROR, WARNING, and INFO categories do not include those above them, so each must be specified explicitly if desired. Any combination of categories can be specified, separated by vertical bars (|).
imq.log.syslog.facility2
String
LOG_DAEMON
syslog facility for logging messages Possible values mirror those listed on the syslog(3C) man page. Appropriate values for use with Message Queue include: LOG_USER LOG_DAEMON LOG_LOCAL0 LOG_LOCAL1 LOG_LOCAL2 LOG_LOCAL3 LOG_LOCAL4 LOG_LOCAL5 LOG_LOCAL6 LOG_LOCAL7
imq.log.syslog.identity2 imq.log.syslog.logpid2
1 2
String Boolean
imqbrokerd_${imq.instanceName} true
Identity string to be prefixed to all messages logged to syslog Log broker process ID with message?
Can be used with imqcmd update bkr command Solaris platform only
359
TABLE 1711 Property

2
(Continued)
imq.log.syslog.logconsole
Boolean String
false Local time zone
Write messages to system console if they cannot be sent to syslog? Time zone for log time stamps Possible values are the same as those used by the method java.util.TimeZone.getTimeZone. Examples: GMT GMT8:00 America/LosAngeles Europe/Rome Asia/Tokyo
imq.log.timezone
imq.metrics.enabled
Boolean
true
Enable writing of metrics information to Logger? Does not affect the production of metrics messages (controlled by imq.metrics.topic.enabled).
imq.metrics.interval
Integer
Time interval, in seconds, at which to write metrics information to Logger Does not affect the time interval for production of metrics messages (controlled by imq.metrics.topic.interval). A value of 1 denotes an indefinite interval (never write metrics information to Logger).
imq.metrics.topic.enabled
Boolean
true
Enable production of metrics messages to metric topic destinations? If false, an attempt to subscribe to a metric topic destination will throw a client-side exception.
imq.metrics.topic.interval
Integer
60
Time interval, in seconds, at which to produce metrics messages to metric topic destinations Are metrics messages sent to metric topic destinations persistent?
imq.metrics.topic.persist
2
Boolean
false
Solaris platform only
360
TABLE 1711 Property
(Continued)
imq.metrics.topic.timetolive
Integer
300
Lifetime, in seconds, of metrics messages sent to metric topic destinations Name of primary system owner Contact information for primary system owner Number of defined roles Name of defined role N (where N ranges from 0 to .count-1) Example: ...name0=Stocks JMS Server ...name1=JMS provider for appserver
imq.primaryowner.name3 imq.primaryowner.contact3 imq.broker.adminDefinedRoles.count3 imq.broker.adminDefinedRoles.nameN3
String String Integer String
System property user.name (user who started the broker) System property user.name (user who started the broker) None Broker instance name
Used by JES Monitoring Framework

Table 1712 lists the configuration properties related to broker clusters.
TABLE 1712
Broker Properties for Cluster Configuration

Property
imq.cluster.url1,2
String
None
URL of cluster configuration file, if any Examples: http://webserver/imq/cluster.properties (for a file on a Web server)
file:/net/mfsserver/imq/cluster.properties (for a file on a shared drive)

1 2
imq.cluster.ha
Must have the same value for all brokers in a cluster Can be used with imqcmd update bkr command
Boolean
false
Is broker part of a high-availability cluster?
361
TABLE 1712 Property

Type
1,3
(Continued)
Description
Default Value
imq.cluster.brokerlist
String
None
List of broker addresses belonging to cluster The list consists of one or more addresses, separated by commas. Each address specifies the host name and Port Mapper port number of a broker in the cluster, in the form hostName:portNumber. Example: host1:3000,host2:8000,ctrlhost
Note If set, this property is ignored (and a warning logged) for high-availability clusters; all brokers configured to use the clusters shared persistent store are automatically recognized as members of the cluster.
imq.cluster.hostname4
String
None
Host name or IP address for cluster connection service If specified, overrides imq.hostname (see Table 171) for the cluster connection service. This might be necessary, for instance, if the brokers host computer has more than one interface card installed.
imq.cluster.port4
Integer
Port number for cluster connection service A value of 0 specifies that the port number should be allocated dynamically by the Port Mapper. You might need to set a different value, for instance, to specify a static port number for connecting to the broker through a firewall.
imq.cluster.transport1
String
tcp
Network transport protocol for cluster connection service For secure, encrypted message delivery between brokers, set this property to ssl.
imq.cluster.masterbroker3,1
String
None
Host name and Port Mapper port number of host on which clusters master broker (if any) is running The value has the form hostName:portNumber, where hostName is the host name of the master brokers host and portNumber is its Port Mapper port number. Example: ctrlhost:7676
Note enhanced clusters cannot have a master broker. If this property is set for a broker belonging to an enhanced cluster, the broker will log a warning message and ignore the property.
1 3 4
Must have the same value for all brokers in a cluster Conventional clusters only Can be specified independently for each broker in a cluster
362
Bridge Properties
TABLE 1712 Property

Type
5,1
(Continued)
Description
Default Value
imq.cluster.clusterid
String
None
Cluster identifier Must be a unique alphanumeric string of no more than n13 characters, where n is the maximum table name length allowed by the database. No two running clusters may have the same cluster identifier. This string is appended to the names of all database tables in the clusters shared persistent store.
Note For brokers belonging to a high-availability cluster, this property is used in database table names in place of imq.brokerid (see Table 171).
imq.cluster.heartbeat.hostname5
String
None
Host name or IP address for heartbeat service If specified, overrides imq.hostname (see Table 171) for the heartbeat service.
imq.cluster.heartbeat.port5
Integer
7676
Port number for heartbeat service A value of 0 specifies that the port number should be allocated dynamically by the Port Mapper.
imq.cluster.heartbeat.interval5 imq.cluster.heartbeat.threshold imq.cluster.monitor.interval5

5
Integer Integer Integer
2 3 30
Interval between heartbeats, in seconds Number of missed heartbeat intervals after which to invoke monitor service Interval, in seconds, at which to update monitor time stamp
Note Larger values for this property will reduce the frequency of
database access and thus improve overall system performance, but at the cost of slower detection and takeover in the event of broker failure. imq.cluster.monitor.threshold5
5 1
Integer
Number of missed monitor intervals after which to initiate broker takeover
enhanced clusters only Must have the same value for all brokers in a cluster
Bridge Properties
Table 1713 lists broker properties related to the bridge service manager. Table 1714 lists broker properties related specifically to the JMS bridge service, and Table 1715 lists broker properties related specifically to the STOMP bridge service.
363
Bridge Properties
TABLE 1713
Broker Properties for the Bridge Service Manager

Property
imq.bridge.enabled imq.bridge.activelist
Boolean String
false None
Is the bridge service enabled on this broker? List of bridges that will be loaded on broker startup. The list consists of one or more bridge names, separated by commas. All bridge names for a broker must be unique.
imq.bridge.admin.user
String
None
The Message Queue broker administrative user to be used by the bridge service manager and individual bridges to create ADMIN connections to the broker. For JMS bridges, this user is also used to access the JMS bridge's built-in DMQ destination. The password for the imq.bridge.admin.user user.
imq.bridge.admin.password
TABLE 1714
String
None
Broker Properties for a JMS Bridge Service

Property
imq.bridge.name.type imq.bridge.name.xmlurl
String String
None None
The bridge type of the bridge named name. For JMS bridges, specify a value of JMS or jms. The URL where the XML configuration file for the JMS bridge name is stored. Examples: http://webserver/imq/jmsbridge1.config.xml (for a file on a Web server)
file:/net/fileserver/imq/jmsbridge1.config.xml (for a file on a shared drive) imq.bridge.name.autostart imq.bridge.name.logfile.limit Boolean Integer true Should the JMS bridge name be automatically started when the broker is started? The approximate maximum number of bytes the JMS bridge name writes to any one log file. A value of 0 (zero) indicates that there is no maximum limit. imq.bridge.name.logfile.count Integer 1 The number of log files the JMS bridge name cycles through.
364
Bridge Properties
TABLE 1714 Property
Broker Properties for a JMS Bridge Service

Type
(Continued)
imq.bridge.tm.props imq.bridge.name.tm.props
String
None
Each of these properties specifies a list of key-value pairs for the built-in transaction coordinator for the JMS bridge name. The list consists of one or more key=value pairs separated by commas. When the imq.persist.store is file, the built-in transaction coordinator supports these keys: txlogSize, txlogSync, and txlogMmap. If the same key appears in both properties, the value specified in imq.bridge.name.tm.props takes precedence.
TABLE 1715

Property
imq.bridge.stomp.tcp.enabled imq.bridge.stomp.tcp.port
Boolean Integer
true 7672
Does the STOMP bridge accept TCP connections? The port on which the STOMP bridge listens for TCP connections, provided that imq.bridge.stomp.tcp.enabled is true. Does the STOMP bridge accept SSL/TLS connections? If true, a keystore must be created using the imqkeytool utility before starting the broker.
imq.bridge.stomp.tls.enabled
Boolean
false
imq.bridge.stomp.tls.port
Integer
7673
The port on which the STOMP bridge listens for SSL/TLS connections, provided that imq.bridge.stomp.tls.enabled is true. Do SSL/TLS connections require client authentication? The maximum number of unacknowledged messages that the STOMP bridge will deliver on a transacted STOMP subscription. The STOMP client must then acknowledge the messages and commit the transaction. The fully qualified class name of a class that extends the Message Queue bridge MessageTransformer abstract class by implementing the transform() method. Place this class under the IMQ_HOME/lib/ext. directory The approximate maximum number of bytes the STOMP bridge writes to any one log file. A value of 0 (zero) indicates that there is no maximum limit.
imq.bridge.stomp.tls.requireClientAuth Boolean imq.bridge.stomp.consumerFlowLimit Integer
false 1000
imq.bridge.stomp.messageTransformer
String
None
imq.bridge.stomp.logfile.limit
Integer
imq.bridge.stomp.logfile.count
Integer
The number of log files the STOMP bridge cycles through.
365
JMX Properties
JMX Properties
The broker properties listed in Table 1716 support the use of the Java Management Extensions (JMX) application programming interface by Java applications. The JMX API is used to configure and monitor broker resources. These JMX-related 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, some of these properties (imq.jmx.rmiregistry.start, imq.jmx.rmiregistry.use, imq.jmx.rmiregistry.port) can be set with corresponding Broker utilityimqbrokerd options described in Table 161. See Appendix D, JMX Support, for further information on administrative support of JMX clients.
TABLE 1716 Property
Broker Properties for JMX Support

imq.jmx.connector.activelist
String
jmxrmi Shown in next column
Names of JMX connectors to be activated at broker startup, separated by commas urlpath component of JMX service URL for connector connectorName Useful in cases where an RMI registry is being used and the JMX service URL path must be set explicitly (such as when a shared external RMI registry is used). See The JMX Service URL on page 448. Default: /jndi/rmi://brokerHost:rmiPort /brokerHost/brokerPort/connectorName
imq.jmx.connector.RMIconnectorName.urlpath String
imq.jmx.connector.RMIconnectorName.port
Integer
None: the port is dynamically allocated
Port number of JMX connector Used to specify a static/known JMX connector port, typically in cases where a JMX client is accessing the broker's MBean server through a firewall. See JMX Connections Through a Firewall on page 455.
366
JMX Properties
TABLE 1716 Property
(Continued)
imq.jmx.connector.RMIconnectorName.useSSL
Boolean
false
Use Secure Socket Layer (SSL) for connector connectorName? This property is set to true for the ssljmxrmi connector.
imq.jmx.connector.RMIconnectorName.brokerHostTrusted Boolean false
Trust any certificate presented by broker for connector connectorName? Applies only when imq.jmx.connector.connectorName.useSSL is true. If false, the JMX client runtime will validate all certificates presented to it. Validation will fail if the signer of the certificate is not in the client's trust store. If true, validation of certificates is skipped. This can be useful, for instance, during software testing when a self-signed certificate is used.
imq.jmx.rmiregistry.start
Boolean
false
Start RMI registry at broker startup? If true, the broker will start an RMI registry at the port specified by imq.jmx.rmiregistry.port and use the regsitry to store the JMX connector stub. (The value of imq.jmx.rmiregistry.use is ignored in this case.) For convenience, this property can also be set at broker startup with the -startRmiRegistry option ofimqbrokerd.
imq.jmx.rmiregistry.use
Boolean
false
Use an existing RMI registry? Applies only if imq.jmx.rmiregistry.start is false. If true, the broker will use an existing RMI registry on the local host at the port specified by imq.jmx.rmiregistry.port to store the JMX connector stub. The existing RMI registry must already be running at broker startup. For convenience, this property can also be set at broker startup with the -useRmiRegistry option ofimqbrokerd.
367
Alphabetical List of Broker Properties
TABLE 1716 Property
(Continued)
imq.jmx.rmiregistry.port
Integer
1099
Port number of RMI registry Applies only if imq.jmx.rmiregistry.start is true or imq.jmx.rmiregistry.use is true. This port number will be included in the URL path of the JMX service URL. For convenience, this property can also be set at broker startup with the -rmiRegistryPort option of imqbrokerd.

Alphabetical List of Broker Properties on page 368 is an alphabetical list of broker configuration properties, with cross-references to the relevant tables in this chapter.
TABLE 1717 Property

Table
imq.accesscontrol.enabled imq.accesscontrol.type imq.accesscontrol.file.filename imq.audit.bsm.disabled imq.audit.enabled imq.authentication.basic.user_repository imq.authentication.client.response.timeout imq.authentication.type imq.autocreate.destination.isLocalOnly imq.autocreate.destination.limitBehavior imq.autocreate.destination.maxBytesPerMsg imq.autocreate.destination.maxNumMsgs imq.autocreate.destination.maxNumProducers imq.autocreate.destination.maxTotalMsgBytes imq.autocreate.destination.useDMQ
Table 178 Table 178 Table 178 Table 178 Table 178 Table 178 Table 178 Table 178 Table 173 Table 173 Table 173 Table 173 Table 173 Table 173 Table 173
368
TABLE 1717 Property
(Continued)
Table
imq.autocreate.queue imq.autocreate.queue.consumerFlowLimit imq.autocreate.queue.localDeliveryPreferred imq.autocreate.queue.maxNumActiveConsumers imq.autocreate.queue.maxNumBackupConsumers imq.autocreate.reaptime imq.autocreate.topic imq.autocreate.topic.consumerFlowLimit imq.broker.adminDefinedRoles.count imq.broker.adminDefinedRoles.namen imq.brokerid imq.bridge.activelist imq.bridge.admin.password imq.bridge.admin.user imq.bridge.enabled imq.bridge.name.autostart imq.bridge.name.logfile.count imq.bridge.name.logfile.limit imq.bridge.name.tm.props imq.bridge.name.type imq.bridge.name.xmlurl imq.bridge.stomp.consumerFlowLimit imq.bridge.stomp.logfile.count imq.bridge.stomp.logfile.limit imq.bridge.stomp.messageTransformer imq.bridge.stomp.tcp.enabled imq.bridge.stomp.tcp.port imq.bridge.stomp.tls.enabled
Table 173 Table 173 Table 173 Table 173 Table 173 Table 173 Table 173 Table 173 Table 1711 Table 1711 Table 171 Table 1713 Table 1713 Table 1713 Table 1713 Table 1714 Table 1714 Table 1714 Table 1714 Table 1714 Table 1714 Table 1715 Table 1715 Table 1715 Table 1715 Table 1715 Table 1715 Table 1715
369
TABLE 1717 Property
(Continued)
Table
imq.bridge.stomp.tls.port imq.bridge.stomp.tls.requireClientAuth imq.bridge.tm.props imq.cluster.brokerlist imq.cluster.clusterid imq.cluster.ha imq.cluster.heartbeat.hostname imq.cluster.heartbeat.interval imq.cluster.heartbeat.port imq.cluster.heartbeat.threshold imq.cluster.hostname imq.cluster.masterbroker imq.cluster.monitor.interval imq.cluster.monitor.threshold imq.cluster.port imq.cluster.transport imq.cluster.url imq.destination.DMQ.truncateBody imq.destination.logDeadMsgs imq.hostname imq.imqcmd.password imq.jmx.connector.activelist imq.jmx.connector.RMIconnectorName.brokerHostTrusted imq.jmx.connector.RMIconnectorName.port imq.jmx.connector.RMIconnectorName.urlpath imq.jmx.connector.RMIconnectorName.useSSL imq.jmx.rmiregistry.port imq.jmx.rmiregistry.start
370
TABLE 1717 Property
(Continued)
Table
imq.jmx.rmiregistry.use imq.keystore.file.dirpath imq.keystore.file.name imq.keystore.password imq.keystore.propertyName imq.log.console.output imq.log.console.stream imq.log.file.dirpath imq.log.file.filename imq.log.file.output imq.log.file.rolloverbytes imq.log.file.rolloversecs imq.log.level imq.log.syslog.facility imq.log.syslog.identity imq.log.syslog.logconsole imq.log.syslog.logpid imq.log.syslog.output imq.log.timezone imq.message.expiration.interval imq.message.max_size imq.metrics.enabled imq.metrics.interval imq.metrics.topic.enabled imq.metrics.topic.interval imq.metrics.topic.persist imq.metrics.topic.timetolive imq.passfile.dirpath
371
TABLE 1717 Property
(Continued)
Table
imq.passfile.enabled imq.passfile.name imq.persist.file.destination.message.filepool.limit imq.persist.file.message.cleanup imq.persist.file.message.filepool.cleanratio imq.persist.file.message.max_record_size imq.persist.file.sync.enabled imq.persist.file.transaction.memorymappedfile.enabled imq.persist.jdbc.dbVendor imq.persist.jdbc.vendorName.closedburl imq.persist.jdbc.vendorName.createdburl imq.persist.jdbc.vendorName.driver imq.persist.jdbc.vendorName.needpassword imq.persist.jdbc.vendorName.opendburl imq.persist.jdbc.vendorName.password imq.persist.jdbc.vendorName.property.propName imq.persist.jdbc.vendorName.user imq.persist.store imq.ping.interval imq.portmapper.backlog imq.portmapper.hostname imq.portmapper.port imq.primaryowner.contact imq.primaryowner.name imq.resourceState.count imq.resourceState.threshold imq.service.activelist imq.serviceName.accesscontrol.enabled
372
TABLE 1717 Property
(Continued)
Table
imq.serviceName.accesscontrol.file.filename imq.serviceName.authentication.type imq.serviceName.max_threads imq.serviceName.min_threads imq.serviceName.protocolType.hostname imq.serviceName.protocolType.port imq.serviceName.threadpool_model imq.shared.connectionMonitor_limit imq.system.max_count imq.system.max_size imq.transaction.autorollback imq.user_repository.ldap.base imq.user_repository.ldap.gidattr imq.user_repository.ldap.grpbase imq.user_repository.ldap.grpfilter imq.user_repository.ldap.grpsearch imq.user_repository.ldap.memattr imq.user_repository.ldap.password imq.user_repository.ldap.principal imq.user_repository.ldap.propertyName imq.user_repository.ldap.server imq.user_repository.ldap.ssl.enabled imq.user_repository.ldap.timeout imq.user_repository.ldap.uidattr imq.user_repository.ldap.usrfilter imq.user_repository.jaas.name imq.user_repository.jaas.userPrincipalClass imq.user_repository.jaas.groupPrincipalClass
373
374
18
C H A P T E R
1 8
Physical Destination Property Reference
This chapter provides reference information about configuration properties for physical destinations.
Physical Destination Properties

Table 181 lists the configuration properties for physical destinations. These properties can be set when creating or updating a physical destination. For auto-created destinations, you set default values in the brokers instance configuration file (see Table 173).
TABLE 181 Property

maxNumMsgs1
Integer
Maximum number of unconsumed messages A value of 1 denotes an unlimited number of messages. For the dead message queue, the default value is 1000.
Note When flow control is in effect (limitBehavior = FLOW_CONTROL), it is possible for the specified message limit to be exceeded because the broker cannot react quickly enough to stop the flow of incoming messages. In such cases, the value specified for maxNumMsgs serves as merely a hint for the broker rather than a strictly enforced limit. However, if the number of unconsumed messages would exceed imq.system.max_count, the broker generates a ResourceAllocationException indicating that the destination is full and rejecting new messages.
In a cluster environment, applies to each individual instance of a destination rather than collectively to all instances in the cluster
375
TABLE 181 Property

Type
(Continued)
maxBytesPerMsg
String
Maximum size, in bytes, of any single message Rejection of a persistent message is reported to the producing client with an exception; no notification is sent for nonpersistent messages. The value may be expressed in bytes, kilobytes, or megabytes, using the following suffixes: b: Bytes k: Kilobytes (1024 bytes) m: Megabytes (1024 1024 = 1,048,576 bytes) An unsuffixed value is expressed in bytes; a value of 1 denotes an unlimited message size. Examples: 1600: 1600 bytes 1600b: 1600 bytes 16k: 16 kilobytes (= 16,384 bytes) 16m: 16 megabytes (= 16,777,216 bytes) 1: No limit
maxTotalMsgBytes1
String
Maximum total memory, in bytes, for unconsumed messages The syntax is the same as for maxBytesPerMsg (see above). For the dead message queue, the default value is 10m.
limitBehavior
String
REJECT_NEWEST
Broker behavior when memory-limit threshold reached: FLOW_CONTROL: Slow down producers REMOVE_OLDEST: Throw out oldest messages REMOVE_LOW_PRIORITY: Throw out lowest-priority messages according to age; no notification to producing client REJECT_NEWEST: Reject newest messages; notify producing client with an exception only if message is persistent When FLOW_CONTROL is specified, it is still possible for the number of messages to exceed imq.system.max_count. In this situation, the broker generates a ResourceAllocationException indicating that the destination is full and rejecting new messages.
In a cluster environment, applies to each individual instance of a destination rather than collectively to all instances in the cluster
376
TABLE 181 Property

Type
(Continued)
If the value is REMOVE_OLDEST or REMOVE_LOW_PRIORITY and the useDMQ property is true, excess messages are moved to the dead message queue. For the dead message queue itself, the default limit behavior is REMOVE_OLDEST and cannot be set to FLOW_CONTROL. maxNumProducers2 Integer 100 Maximum number of message producers for destination When this limit is reached, no new producers can be created. A value of 1 denotes an unlimited number of producers. maxNumActiveConsumers3 Integer -1 Maximum number of active message consumers in load-balanced delivery from queue destination A value of 1 denotes an unlimited number of consumers. This property used mostly in cases where message order is important and you want to provide backup consumers in case the principal consumer of a queue fails. If message order is not important, then you would simply use multiple consumers to provide for scalability and availability. maxNumBackupConsumers3 Integer 0 Maximum number of backup message consumers in load-balanced delivery from queue destination A value of 1 denotes an unlimited number of consumers. consumerFlowLimit Integer 1000 Maximum number of messages delivered to consumer(s) in a single batch In load-balanced queue delivery, this is the initial number of queued messages routed to active consumers before load balancing begins. The client runtime can override this limit by specifying a lower value on the connection factory object.. A value of 1 denotes an unlimited number of messages. isLocalOnly2 Boolean false Local delivery only? This property applies only to destinations in broker clusters, and cannot be changed once the destination has been created. If true, the destination is not replicated on other brokers and is limited to delivering messages only to local consumers (those connected to the broker on which the destination is created).
2 3
Does not apply to dead message queue Queue destinations only
Chapter 18 Physical Destination Property Reference
377
TABLE 181 Property

Type
2 ,3
(Continued)
localDeliveryPreferred
Boolean
false
Local delivery preferred? This property applies only to load-balanced queue delivery in broker clusters. If true, messages will be delivered to remote consumers only if there are no consumers on the local broker; the destination must not be restricted to local-only delivery (isLocalOnly must be false).
useDMQ2
Boolean
true
Send dead messages to dead message queue? If false, dead messages will simply be discarded.
validateXMLSchemaEnabled
4
Boolean
false
XML schema validation is enabled? When XML validation is enabled, the Message Queue client runtime will attempt to validate an XML message against the specified XSDs (or against the DTD, if no XSD is specified) before sending it to the broker. If the specified schema cannot be located or the message cannot be validated, the message is not sent, and an exception is thrown. Client applications using this feature should use JRE 1.5 or above. If set to false or not set, then XML schema validation is not enabled for the destination.
XMLSchemaURIList4
String
null
Space separated list of XML schema document (XSD) URI strings The URIs point to the location of one or more XSDs to use for XML schema validation, if enabled. Use double quotes around this value if multiple URIs are specified. Example: http://foo/flap.xsd http://test.com/test.xsd If this property is not set or null and XML validation is enabled, XML validation is performed using a DTD specified in the XML document. if an XSD is changed, as a result of changing application requirements, all client applications producing XML messages based on the changed XSD must reconnect to the broker.
2 3 4
Does not apply to dead message queue Queue destinations only This property should be set when a destination is inactive: when it has no consumers or producers and when there are no messages in the destination. Otherwise the producer must reconnect.
378
TABLE 181 Property

Type
4
(Continued)
reloadXMLSchemaOnFailure
Boolean
false
Reload XML schema on failure enabled? If set to true and XML validation fails, then the Message Queue client runtime will attempt to reload the XSD before attempting again to validate a message. The client runtime will throw an exception if the validation fails using the reloaded SXD. If set to false or not set, then the schema is not reloaded if validation fails.
This property should be set when a destination is inactive: when it has no consumers or producers and when there are no messages in the destination. Otherwise the producer must reconnect.
Chapter 18 Physical Destination Property Reference
379
380
19
C H A P T E R

1 9
Administered Object Attribute Reference
This chapter provides reference information about the attributes of administered objects. It consists of the following sections: Connection Factory Attributes on page 381 Destination Attributes on page 389

The attributes of a connection factory object are grouped into categories described in the following sections below:

Connection Handling on page 381 Client Identification on page 385 Reliability and Flow Control on page 385 Queue Browser and Server Sessions on page 387 Standard Message Properties on page 388 Message Header Overrides on page 388
Connection Handling
Table 191 lists the connection factory attributes for connection handling.
381
TABLE 191 Attribute
Connection Factory Attributes for Connection Handling

imqAddressList
String
An existing Message Queue 3.0 address, if any; if none, the first entry in Table 192
List of broker addresses The list consists of one or more addresses, separated by commas. Each address specifies (or implies) the host name, port number, and connection service for a broker instance to which the client can connect. Address syntax varies depending on the connection service and port assignment method; see below for details.
Note In an enhanced broker cluster, the value of this attribute is updated dynamically as brokers enter and leave the cluster, so that it always reflects the clusters current membership.
imqAddressListBehavior
String
PRIORITY
Order in which to attempt connection to broker addresses: PRIORITY: Order specified in address list RANDOM: Random order
Note If many clients share the same connection factory, specify random connection order to prevent them from all attempting to connect to the same address.
imqAddressListIterations
Integer
Number of times to iterate through address list attempting to establish or reestablish a connection A value of 1 denotes an unlimited number of iterations.
Note In the event of broker failure in an enhanced broker
cluster, this attribute is ignored and the Message Queue client runtime iterates through the address list indefinitely until it succeeds in reconnecting to a takeover broker. The effect is equivalent to an imqAddressListIterations value of 1, overriding any other explicit or default setting of this attribute. The only way for a client application to avoid this behavior is to close the connection explicitly on broker failure. imqPingInterval Integer 30 Interval, in seconds, at which to test connection between client and broker A value of 0 or 1 disables periodic testing of the connection. imqReconnectEnabled Boolean false Attempt to reestablish a lost connection?
Note In the event of broker failure in an enhanced broker
cluster, this attribute is ignored and automatic reconnection is always attempted. The effect is equivalent to an imqReconnectEnabled value of true, overriding any other explicit or default setting of this attribute. The only way for a client application to avoid this behavior is to close the connection explicitly on broker failure.
382
TABLE 191 Attribute
Connection Factory Attributes for Connection Handling

Type Default Value
(Continued)
Description
imqReconnectAttempts
Integer
Number of times to attempt connection (or reconnection) to each address in address list before moving on to next A value of 1 denotes an unlimited number of connection attempts: attempt repeatedly to connect to first address until successful. For example, in an enhanced broker cluster, this value will allow for connection to the failover broker.
imqReconnectInterval
Long integer 3000
Interval, in milliseconds, between reconnection attempts This value applies both for successive attempts on a given address and for successive addresses in the list.
Note Too small a value may give the broker insufficient recovery time; too large a value may cause unacceptable connection delays.
imqSSLIsHostTrusted
Boolean
false
Trust any certificate presented by broker? If false, the Message Queue client runtime will validate all certificates presented to it. Validation will fail if the signer of the certificate is not in the client's trust store. If true, validation of certificates is skipped. This can be useful, for instance, during software testing when a self-signed certificate is used. NOTE: To use signed certificates from a certification authority, set this attribute to false.
The value of the imqAddressList attribute is a comma-separated string specifying one or more broker addresses to which to connect. The general syntax for each address is as follows: scheme://address where scheme identifies one of the addressing schemes shown in the first column of Table 192 and address denotes the broker address itself. The exact syntax for specifying the address depends on the addressing scheme, as shown in the last column of the table.
Chapter 19 Administered Object Attribute Reference
383
TABLE 192 Scheme
Message Broker Addressing Schemes

Service Syntax Description
mq
jms or ssljms
[hostName][:portNumber][/serviceName]
Assign port dynamically for jms or ssljms connection service The address list entry specifies the host name and port number for the Message Queue Port Mapper. The Port Mapper itself dynamically assigns a port to be used for the connection. Default values: hostName = localhost portNumber = 7676 serviceName = jms For the ssljms connection service, all variables must be specified explicitly.
mqtcp
jms
hostName:portNumber/jms
Connect to specified port using jms connection service Bypasses the Port Mapper and makes a TCP connection directly to the specified host name and port number.
mqssl
ssljms
hostName:portNumber/ssljms
Connect to specified port using ssljms connection service Bypasses the Port Mapper and makes a secure SSL connection directly to the specified host name and port number.
http
httpjms
http://hostName:portNumber/contextRoot/tunnel
If multiple broker instances use the same tunnel servlet, the following syntax connects to a specific broker instance Makes an HTTP connection to a Message rather than a randomly selected one: Queue tunnel servlet at the specified URL. The broker must be configured to access the HTTP http://hostName:portNumber/contextRoot/tunnel? tunnel servlet. ServerName=hostName:instanceName https httpsjms https://hostName:portNumber/contextRoot/tunnel Connect to specified port using httpsjms connection service
Connect to specified port using httpjms connection service
If multiple broker instances use the same tunnel servlet, the following syntax connects to a specific broker instance Makes a secure HTTPS connection to a Message Queue tunnel servlet at the specified rather than a randomly selected one: URL. The broker must be configured to access https://hostName:portNumber/contextRoot/tunnel? the HTTPS tunnel servlet. ServerName=hostName:instanceName
384
TABLE 193 Service
Message Broker Address Examples

Broker Host Port Example Address
Not specified Not specified Not specified ssljms ssljms ssljms jms ssljms httpjms httpsjms
Not specified Specified host Not specified Local host Specified host Specified host Local host Specified host Not applicable Not applicable
Not specified Not specified Specified Port Mapper port Standard Port Mapper port Standard Port Mapper port Specified Port Mapper port Specified service port Specified service port Not applicable Not applicable
No address (mq://localHost:7676/jms) myBkrHost (mq://myBkrHost:7676/jms) 1012 (mq://localHost:1012/jms) mq://localHost:7676/ssljms mq://myBkrHost:7676/ssljms mq://myBkrHost:1012/ssljms mqtcp://localhost:1032/jms mqssl://myBkrHost:1034/ssljms http://websrvr1:8085/imq/tunnel https://websrvr2:8090/imq/tunnel
Client Identification
Table 194 lists the connection factory attributes for client identification.
TABLE 194 Attribute
Connection Factory Attributes for Client Identification

imqDefaultUsername imqDefaultPassword imqConfiguredClientID imqDisableSetClientID
String String String Boolean
guest guest null false
Default user name for authenticating with broker Default password for authenticating with broker Administratively configured client identifier Prevent client from changing client identifier using setClientID method?
Reliability and Flow Control

Table 195 lists the connection factory attributes for reliability and flow control.
385
TABLE 195 Attribute
Connection Factory Attributes for Reliability and Flow Control

imqAckTimeout
String
Maximum time, in milliseconds, to wait for broker acknowledgment before throwing an exception A value of 0 denotes no timeout (wait indefinitely).
Note In some situations, too low a value can cause premature
timeout: for example, initial authentication of a user against an LDAP user repository using a secure (SSL) connection can take more than 30 seconds. imqConnectionFlowCount Integer 100 Number of payload messages in a metered batch Delivery of payload messages to the client is temporarily suspended after this number of messages, allowing any accumulated control messages to be delivered. Payload message delivery is resumed on notification by the client runtime, and continues until the count is again reached. A value of 0 disables metering of message delivery and may cause Message Queue control messages to be blocked by heavy payload message traffic. imqConnectionFlowLimitEnabled imqConnectionFlowLimit Boolean Integer false 1000 Limit message flow at connection level? Maximum number of messages per connection to deliver and buffer for consumption Message delivery on a connection stops when the number of unconsumed payload messages pending (subject to flow metering governed by imqConnectionFlowCount) exceeds this limit. Delivery resumes only when the number of pending messages falls below the limit. This prevents the client from being overwhelmed with pending messages that might cause it to run out of memory. This attribute is ignored if imqConnectionFlowLimitEnabled is false.
386
TABLE 195 Attribute
Connection Factory Attributes for Reliability and Flow Control

(Continued)
imqConsumerFlowLimit
Integer
1000
Maximum number of messages per consumer to deliver and buffer for consumption Message delivery to a given consumer stops when the number of unconsumed payload messages pending for that consumer exceeds this limit. Delivery resumes only when the number of pending messages for the consumer falls below the percentage specified by imqConsumerFlowThreshold. This can be used to improve load balancing among multiple consumers and prevent any single consumer from starving others on the same connection. This limit can be overridden by a lower value set for a queues own consumerFlowLimit attribute (see Chapter 18, Physical Destination Property Reference). Note also that message delivery to all consumers on a connection is subject to the overall limit specified by imqConnectionFlowLimit.
imqConsumerFlowThreshold
Integer
50
Number of messages per consumer buffered in the client runtime, as a percentage of imqConsumerFlowLimit, below which to resume message delivery
Queue Browser and Server Sessions

Table 196 lists the connection factory attributes for queue browsing and server sessions.
TABLE 196
Connection Factory Attributes for Queue Browser and Server Sessions

Attribute
imqQueueBrowserMaxMessagesPerRetrieve Integer
1000
Maximum number of messages to retrieve at one time when browsing contents of a queue destination
Note This attribute does not affect the total number of messages browsed, only the way they are chunked for delivery to the client runtime (fewer but larger chunks or more but smaller ones). The client application will always receive all messages in the queue. Changing the attribute's value may affect performance, but will not affect the total amount of data retrieved.
imqQueueBrowserRetrieveTimeout
Long integer
60000
Maximum time, in milliseconds, to wait to retrieve messages, when browsing contents of a queue destination, before throwing an exception
387
TABLE 196 Attribute
Connection Factory Attributes for Queue Browser and Server Sessions

(Continued)
imqLoadMaxToServerSession
Boolean
true
Load up to maximum number of messages into a server session? If false, the client will load only a single message at a time. This attribute applies only to JMS application server facilities.
Standard Message Properties

The connection factory attributes listed in Table 197 control whether the Message Queue client runtime sets certain standard message properties defined in the Java Message Service Specification.
TABLE 197 Property
Connection Factory Attributes for Standard Message Properties

imqSetJMSXUserID
Boolean Boolean Boolean
false
Set JMSXUserID property (identity of user sending message) for produced messages? Set JMSXAppID property (identity of application sending message) for produced messages? Set JMSXProducerTXID property (transaction identifier of transaction within which message was produced) for produced messages? Set JMSXConsumerTXID property (transaction identifier of transaction within which message was consumed) for consumed messages? Set JMSXRcvTimestamp property (time message delivered to consumer) for consumed messages?
imqSetJMSXAppID
false
imqSetJMSXProducerTXID
false
imqSetJMSXConsumerTXID
Boolean
false
imqSetJMSXRcvTimestamp
Boolean
false
Message Header Overrides

Table 198 lists the connection factory attributes for overriding JMS message header fields.
388
TABLE 198 Attribute
Connection Factory Attributes for Message Header Overrides

imqOverrideJMSDeliveryMode
Boolean Integer
false
Allow client-set delivery mode to be overridden? Overriding value of delivery mode: 1 Nonpersistent 2 Persistent
imqJMSDeliveryMode
imqOverrideJMSExpiration
Boolean
false
Allow client-set expiration time to be overridden? Overriding value of expiration time, in milliseconds A value of 0 denotes an unlimited expiration time (message never expires).
imqJMSExpiration
Long integer 0
imqOverrideJMSPriority imqJMSPriority imqOverrideJMSHeadersToTemporaryDestinations
Boolean Integer Boolean
false 4 (normal) false
Allow client-set priority level to be overridden? Overriding value of priority level (0 to 9) Apply overrides to temporary destinations?
Table 199 lists the attributes that can be set for a destination administered object.
TABLE 199 Attribute
imqDestinationName
String
Untitled_Destination_Object
Name of physical destination The destination name may contain only alphanumeric characters (no spaces) and must begin with an alphabetic character or the underscore (_) or dollar sign ($) character. It may not begin with the characters mq.
imqDestinationDescription
String
None
Descriptive string for destination
389
390
C H A P T E R
JMS Resource Adapter Property Reference
20
2 0
This chapter describes the configuration properties of the Message Queue JMS Resource Adapter (JMS RA), which enables you to integrate Sun GlassFish Message Queue with any J2EE 1.4 application server by means of the standard J2EE connector architecture (JCA). When plugged into an application server, the Resource Adapter allows applications deployed in that application server to use Message Queue to send and receive JMS messages. The Message Queue JMS Resource Adapter exposes its configuration properties through three JavaBean components:
The ResourceAdapter JavaBean (ResourceAdapter JavaBean on page 392) affects the behavior of the Resource Adapter as a whole. The ManagedConnectionFactory JavaBean (ManagedConnectionFactory JavaBean on page 394) affects connections created by the Resource Adapter for use by message-driven beans (MDBs). The ActivationSpec JavaBean (ActivationSpec JavaBean on page 397) affects message endpoints that represent MDBs in their interactions with the messaging system.
To set property values for these entities, you use the tools provided by your application server for configuration and deployment of the Resource Adapter and for deployment of MDBs. This chapter lists and describes the configuration properties of the Message Queue JMS Resource Adapter. It contains the following sections:

About Shared Topic Subscriptions for Clustered Containers on page 392 ResourceAdapter JavaBean on page 392 ManagedConnectionFactory JavaBean on page 394 ActivationSpec JavaBean on page 397
391
About Shared Topic Subscriptions for Clustered Containers
About Shared Topic Subscriptions for Clustered Containers

The Message Queue JMS Resource Adapter provides a special feature called shared subscriptions for containers that support clustering, such as Sun Java System GlassFish Enterprise Server. This feature enables clustered containers to share the load of processing messages for topic subscriptions across the instances of a cluster. When this feature is enabled, the following behaviors apply:
A client id must be set when creating any subscription, even a nondurable subscription (which does not normally require a client id). Attempting to create a subscription without a client id throws an exception. Attempts by multiple connections to use the same client id do not result in an exception, provided that the connections are from different instances in the cluster. Two or more subscriptions on the same topic with the same client id and the same durable subscription name (if the subscription is durable) are considered shared; that is, they are treated as a single subscription, with each message being sent to only one of the participating subscriptions.
By default, the shared subscriptions feature is enabled. In some applications that use nondurable subscriptions, however, the shared behavior is not desired. In such cases, the useSharedSubscriptionInClusteredContainer property can be set to false to disable the feature.
ResourceAdapter JavaBean
The ResourceAdapter configuration configures the default JMS Resource Adapter behavior. Table 201 lists and describes the properties with which you can configure this JavaBean.
TABLE 201 Property
Resource Adapter Properties

addressList1
String
mq://localhost:7676/jmsMessage service address for connecting to Message Queue service Equivalent to connectionURL (below).
connectionURL1
String
mq://localhost:7676/jmsMessage service address for connecting to the Message Queue service Equivalent to addressList(above).
brokerInstanceName brokerPort
String Integer
imqbroker 7676
Name of broker instance Port number for connecting to broker
Exactly one of these properties must be specified
392
ResourceAdapter JavaBean
TABLE 201 Property
(Continued)
brokerBindAddress
String
Null
Address to which broker binds on host machine If null, the broker will bind to all addresses on the host machine.
userName2 password2
String String String
guest
Default user name for connecting to Message Queue service Default password for connecting to Message Queue service Order in which to attempt connection to Message Queue service: PRIORITY: Order specified in address list RANDOM: Random order
Note Reconnection attempts after a connection failure start with the broker whose connection failed and proceed sequentially through the address list, regardless of the value set for this property.
guest
addressListBehavior
PRIORITY
addressListIterations
Integer
Number of times to iterate through address list attempting to establish or reestablish a connection Attempt to reestablish a lost connection? Number of times to attempt reconnection to each address in address list before moving on to next Interval, in milliseconds, between reconnection attempts Enable high availability?
reconnectEnabled
Boolean Integer
false
reconnectAttempts
reconnectInterval
Long integer 30000 Boolean false
brokerEnableHA
2
Required
Chapter 20 JMS Resource Adapter Property Reference
393
ManagedConnectionFactory JavaBean
TABLE 201 Property
(Continued)
clusterID
String
None
Cluster identifier If specified, only brokers with the same cluster identifier can be clustered together. In the event of broker failure, client connections will fail over only to brokers with the same cluster identifier as the original broker. If not specified, client connections can fail over to any other broker with an unspecified cluster identifier. For standalone brokers (those not belonging to a cluster), this property is ignored. The identifier may contain only alphabetic letters (AZ, az), numeric digits (09), and the underscore character (_).
brokerID
String
None
Broker identifier For brokers using a JDBC-based persistent data store, this string is appended to the names of all database tables to make them unique in the case where more than one broker instance is using the same database. For brokers using a file-based data store, this property is ignored. In an enhanced cluster, each broker must have a unique broker identifier. The identifier may contain only alphabetic letters (AZ, az), numeric digits (09), and the underscore character (_).
A managed connection factory defines the connections that the Resource Adapter provides to a message-driven bean. Table 202 shows the properties of the ManagedConnectionFactory JavaBean; if set, these properties override the corresponding properties of the ResourceAdapter JavaBean.
TABLE 202 Property
Managed Connection Factory Properties

addressList
String
Inherited from ResourceAdapter JavaBean (see Table 201) guest
List of message service addresses for connecting to Message Queue service
userName1 password1
String String String String
User name for connecting to Message Queue service Password for connecting to Message Queue service Client identifier for connections to Message Queue service Order in which to attempt connection to Message Queue service: PRIORITY: Order specified in address list RANDOM: Random order
Note Reconnection attempts after a connection failure start with the broker whose connection failed and proceed sequentially through the address list, regardless of the value set for this property.
guest None PRIORITY
clientID
addressListBehavior
addressListIterations
Integer
Number of times to iterate through address list attempting to establish or reestablish a connection Attempt to reestablish a lost connection? Number of times to attempt reconnection to each address in address list before moving on to next Interval, in milliseconds, between reconnection attempts
reconnectEnabled
Boolean Integer
false
reconnectAttempts
reconnectInterval
1
Long integer 30000
Optional
395
TABLE 202 Property

Type
(Continued)
options
String
None
A list of additional connection factory properties to be used when creating connections to a Message Queue broker. When specified, the value of options must be a comma-separated list of connection factory properties and their values, in the form: propertyName=value If value contains a comma or an equals sign, precede the symbol with a backslash (\) or enclose the entire value in quotes; for example: prop1=comma\,val,prop2="equals=val" The options property cannot specify properties that are configured internally or that have their own setter methods, specifically: imqReconnectEnabled, imqReconnectAttempts, imqReconnectInterval, imqDefaultUsername, imqDefaultPassword, imqAddressList, imqAddressListIterations. Any values specified in options for these properties are ignored.
Optional
396
ActivationSpec JavaBean
TABLE 202 Property

Type
(Continued)
useSharedSubscriptionInClusteredContainer
Boolean
true
Controls whether topic subscriptions created using this ManagedConnectionFactory will be shared when running in a clustered container, as described in About Shared Topic Subscriptions for Clustered Containers on page 392. Set to true (the default) to share subscriptions. The clientID property must also be set, even if the subscription is nondurable. Set to false to not share subscriptions. This setting should only be used for nondurable subscriptions. The clientID property does not need to be set.
Table 203 shows the configurable properties of the ActivationSpec JavaBean. These properties are used by the application server when instructing the Resource Adapter to activate a message endpoint and associate it with a message-driven bean.
TABLE 203 Property
ActivationSpec Properties
Type
1,2
Default Value
Description
addressList
String
Inherited from ResourceAdapter JavaBean None
Message service address for connecting to Message Queue service Name of destination from which to consume messages The value must be that of the destinationName property for a Message Queue destination administered object.
destination3
String
1 2 3
Optional Property specific to Message Queue JMS Resource Adapter Standard Enterprise JavaBean (EJB) and J2EE Connector Architecture (CA) property
397
TABLE 203 Property
3
(Continued)
destinationType
String
None
Type of destination specified by destination property: javax.jms.Queue: Queue destination javax.jms.Topic: Topic destination Message selector for filtering messages delivered to consumer Name for durable subscriptions This property must be set if subscriptionDurability is set to Durable.
messageSelector1,3 subscriptionName3
String String
None None
subscriptionDurability3
String
NonDurable
Durability of consumer for topic destination: Durable: Durable consumer NonDurable: Nondurable consumer This property is valid only if destinationType is set to javax.jms.Topic, and is optional for nondurable subscriptions and required for durable ones. If set to Durable, the clientID and subscriptionName properties must also be set.
clientId3
String
None
Client ID for connections to Message Queue service This property must be set if subscriptionDurability is set to Durable.
acknowledgeMode1,3
String
Auto-acknowledge
Acknowledgment mode: Auto-acknowledge: Auto-acknowledge mode Dups-ok-acknowledge: Dups-OK-acknowledge mode
3 1
Standard Enterprise JavaBean (EJB) and J2EE Connector Architecture (CA) property Optional
398
TABLE 203 Property
(Continued)
customAcknowledgeMode
String
None
Acknowledgment mode for MDB message consumption Valid values are No_acknowledge or null. You can use no-acknowledge mode only for a nontransacted, nondurable topic subscription; if you use this setting with a transacted subscription or a durable subscription, subscription activation will fail.
endpointExceptionRedeliveryAttempts
Integer
Number of times to redeliver a message when MDB throws an exception during message delivery Place message in dead message queue when MDB throws a runtime exception and number of redelivery attempts exceeds the value of endpointExceptionRedeliveryAttempts? If false, the Message Queue broker will attempt redelivery of the message to any valid consumer, including the same MDB.
sendUndeliverableMsgsToDMQ
Boolean
true
399
TABLE 203 Property
(Continued)
options
String
None
A list of additional connection factory properties to be used when creating connections to a Message Queue broker. When specified, the value of options must be a comma-separated list of connection factory properties and their values, in the form: propertyName=value If value contains a comma or an equals sign, precede the symbol with a backslash (\) or enclose the entire value in quotes; for example: prop1=comma\,val,prop2="equals=val" The options property cannot be used to specify properties that are configured internally or that have their own setter methods, specifically: imqReconnectEnabled, imqReconnectAttempts, imqReconnectInterval, imqDefaultUsername, imqDefaultPassword, imqAddressList, imqAddressListIterations. Any values specified in options for these properties are ignored.
Optional
400
TABLE 203 Property
(Continued)
useSharedSubscriptionInClusteredContainer
Boolean
true
Controls whether topic subscriptions created using this ActivationSpec will be shared when running in a clustered container, as described in About Shared Topic Subscriptions for Clustered Containers on page 392. Set to true (the default) to share subscriptions. The clientID property must also be set, even if the subscription is nondurable. Set to false to not share subscriptions. This setting should only be used for nondurable subscriptions. The clientID property does not need to be set.
401
402
C H A P T E R
Metrics Information Reference
21
2 1
This chapter describes the metrics information that a Message Queue broker can provide for monitoring, tuning, and diagnostic purposes. This information can be made available in a variety of ways:

In a log file (see Sending Metrics Data to Log Files on page 253) Interactively with the Command utilitys imqcmd metrics subcommand (see Using the Command Utility on page 86) In metrics messages sent to a metrics topic destination (see Using the Message-Based Monitoring API on page 260) Through JMX MBeans that can be accessed programmatically by Java applications using the JMX Administration API.
The tables in this chapter list the kinds of metrics information available and the forms in which it can be provided. For metrics provided through the Command utilitys imqcmd metrics subcommand, the tables list the metric type with which they can be requested; for those provided in metrics messages, the tables list the metrics topic destination to which they are delivered. All the metrics information in this chapter can be accessed progamatically using the JMX Administration API as described in the Message Queue Developers Guide for JMX Clients The chapter consists of the following sections:

JVM Metrics on page 404 Brokerwide Metrics on page 404 Connection Service Metrics on page 406 Physical Destination Metrics on page 407
403
JVM Metrics
JVM Metrics
Table 211 shows the metrics information that the broker reports for the broker process JVM (Java Virtual Machine) heap.
TABLE 211
JVM Metrics
Description Log File? metrics bkr Metric Type Metrics Topic
Metrics Quantity
JVM heap: total memory JVM heap: free memory JVM heap: max memory
Current total memory, in bytes Amount of memory currently available for use, in bytes Maximum allowable heap size, in bytes
Yes Yes Yes
cxn cxn None
mq.metrics.jvm mq.metrics.jvm
mq.metrics.jvm
Brokerwide Metrics
Table 212 shows the brokerwide metrics information that the broker reports.
TABLE 212
Brokerwide Metrics
Metrics Quantity
Connections Num connections Num threads Min threads Max threads Stored Messages Num messages Total message bytes Message Flow Use query bkr command instead Current number of payload messages stored in memory and persistent store Total size in bytes of payload messages currently stored in memory and persistent store No No None1 None1 mq.metrics.broker Total current number of connections for all connection services Total current number of threads for all connection services Yes Yes cxn mq.metrics.broker None None None
cxn
Total minimum number of threads for all connection Yes services Total maximum number of threads for all connection Yes services
cxn
cxn
mq.metrics.broker
404
Brokerwide Metrics
TABLE 212
Brokerwide Metrics
(Continued)
Metrics Quantity
Num messages in Num messages out Rate messages in Rate messages out Message bytes in Message bytes out Rate message bytes in Rate message bytes out Num packets in Num packets out Rate packets in Rate packets out Packet bytes in Packet bytes out Rate packet bytes in Rate packet bytes out Destinations Num destinations
Cumulative number of payload messages received since broker started Cumulative number of payload messages sent since broker started Current rate of flow of payload messages into broker Current rate of flow of payload messages out of broker Cumulative size in bytes of payload messages received since broker started Cumulative size in bytes of payload messages sent since broker started Current rate of flow of payload message bytes into broker Current rate of flow of payload message bytes out of broker Cumulative number of payload and control packets received since broker started Cumulative number of payload and control packets sent since broker started Current rate of flow of payload and control packets into broker Current rate of flow of payload and control packets out of broker Cumulative size in bytes of payload and control packets received since broker started Cumulative size in bytes of payload and control packets sent since broker started Current rate of flow of payload and control packet bytes into broker Current rate of flow of payload and control packet bytes out of broker
Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
ttl
mq.metrics.broker
ttl
mq.metrics.broker None None mq.metrics.broker
rts rts
ttl
ttl
rts
rts
ttl
ttl
rts
rts
ttl
ttl
mq.metrics.broker None None
rts
rts
Current number of physical destinations
No
None
mq.metrics.broker
Chapter 21 Metrics Information Reference
405

Table 213 shows the metrics information that the broker reports for individual connection services.
TABLE 213

Description Log File? metrics svc Metric Type Metrics Topic
Metrics Quantity
Connections Num connections Num threads Min threads Max threads Message Flow Num messages in Num messages out Rate messages in Rate messages out Message bytes in Cumulative number of payload messages received through connection service since broker started Cumulative number of payload messages sent through connection service since broker started Current rate of flow of payload messages into broker through connection service Current rate of flow of payload messages out of broker through connection service Cumulative size in bytes of payload messages received through connection service since broker started Cumulative size in bytes of payload messages sent through connection service since broker started Current rate of flow of payload message bytes into broker through connection service Current rate of flow of payload message bytes out of broker through connection service Cumulative number of payload and control packets received through connection service since broker started Cumulative number of payload and control packets sent through connection service since broker started No No No No No ttl None None None None None Current number of connections Current number of threads Minimum number of threads assigned to service Maximum number of threads assigned to service No No No No cxn1 cxn cxn cxn
1
None None None None
ttl
rts
rts
ttl
Message bytes out Rate message bytes in Rate message bytes out Num packets in
No No No No
ttl
None None None None
rts
rts
ttl
Num packets out

1
No
ttl
None
Also available with query svc command
406
TABLE 213

Description
(Continued)
Log File? metrics svc Metric Type Metrics Topic
Metrics Quantity
Rate packets in Rate packets out Packet bytes in
Current rate of flow of payload and control packets into broker through connection service Current rate of flow of payload and control packets out of broker through connection service Cumulative size in bytes of payload and control packets received through connection service since broker started Cumulative size in bytes of payload and control packets sent through connection service since broker started Current rate of flow of payload and control packet bytes into broker through connection service Current rate of flow of payload and control packet bytes out of broker through connection service
No No No
rts
None None None
rts
ttl
Packet bytes out
No
ttl
None
Rate packet bytes in Rate packet bytes out
No No
rts
None None
rts

Table 214 shows the metrics information that the broker reports for individual destinations.
TABLE 214

Description Log File? metrics dst Metric Type Metrics Topic
Metrics Quantity
Message Consumers Num consumers Current number of associated message consumers For queue destinations, this attribute includes both active and backup consumers. For topic destinations, it includes both nondurable and (active and inactive) durable subscribers and is equivalent to Num active consumers. No con mq.metrics.destination.queue.queueName mq.metrics.destination.topic.topicName
407
TABLE 214

Description
(Continued)
Log File? metrics dst Metric Type Metrics Topic
Metrics Quantity
Peak num consumers
Peak number of No associated message consumers since broker started For queue destinations, this attribute includes both active and backup consumers. For topic destinations, it includes both nondurable and (active and inactive) durable subscribers and is equivalent to Peak num active consumers.
con
mq.metrics.destination.queue.queueName mq.metrics.destination.topic.topicName
Avg num consumers
Average number of No associated message consumers since broker started For queue destinations, this attribute includes both active and backup consumers. For topic destinations, it includes both nondurable and (active and inactive) durable subscribers and is equivalent to Avg num active consumers.
con
Num active consumers
Current number of associated active message consumers For topic destinations, this attribute includes both nondurable and (active and inactive) durable subscribers and is equivalent to Num consumers.
No
con
408
TABLE 214

Description
(Continued)
Metrics Quantity
Peak num active consumers
Peak number of associated active message consumers since broker started For topic destinations, this attribute includes both nondurable and (active and inactive) durable subscribers and is equivalent to Peak num consumers.
No
con
Avg num active consumers
Average number of associated active message consumers since broker started For topic destinations, this attribute includes both nondurable and (active and inactive) durable subscribers and is equivalent to Avg num consumers.
No
con
Num backup consumers1
Current number of associated backup message consumers
No
con
mq.metrics.destination.queue.queueName mq.metrics.destination.topic.topicName mq.metrics.destination.queue.queueName mq.metrics.destination.topic.topicName
Peak num backup consumers1 Peak number of associated backup message consumers since broker started Avg num backup consumers1 Average number of associated backup message consumers since broker started
No
con
No
con
Stored Messages Num messages Current number of messages stored in memory and persistent store No con ttl rts2 mq.metrics.destination.queue.queueName mq.metrics.destination.topic.topicName
1 2
Queue destinations only Also available with query dst command
409
TABLE 214

Description
(Continued)
Metrics Quantity
Num messages remote
Current number of No messages stored in memory and persistent store that were sent from a remote broker in a cluster. This number does not include messages included in transactions. Peak number of messages stored in memory and persistent store since broker started Average number of messages stored in memory and persistent store since broker started No
Not Available
3
Not Available
Peak num messages
con ttl rts
Avg num messages
No
con ttl rts
Total message bytes
No Current total size in bytes of messages stored in memory and persistent store Current total size in No bytes of messages stored in memory and persistent store that were sent from a remote broker in a cluster. This value does not include messages included in transactions. Peak total size in bytes of messages stored in memory and persistent store since broker started No
ttl rts2
Total message bytes remote
Not Available
3
Not Available
Peak total message bytes
ttl rts
3 2
Available only with imqcmd query dst command Also available with query dst command
410
TABLE 214

Description
(Continued)
Metrics Quantity
Avg total message bytes
Average total size in No bytes of messages stored in memory and persistent store since broker started
ttl rts
Message Flow Num messages in Cumulative number of messages received since broker started Cumulative number of messages sent since broker started No ttl mq.metrics.destination.queue.queueName mq.metrics.destination.topic.topicName mq.metrics.destination.queue.queueName mq.metrics.destination.topic.topicName mq.metrics.destination.queue.queueName mq.metrics.destination.topic.topicName mq.metrics.destination.queue.queueName mq.metrics.destination.topic.topicName mq.metrics.destination.queue.queueName mq.metrics.destination.topic.topicName None None None None
Num messages out
No
ttl
Msg bytes in
Cumulative size in bytes No of messages received since broker started Cumulative size in bytes No of messages sent since broker started Size in bytes of largest single message received since broker started Current rate of flow of messages received Current rate of flow of messages sent Current rate of flow of message bytes received Current rate of flow of message bytes sent No
ttl
Msg bytes out
ttl
Peak message bytes
ttl rts
Rate num messages in Rate num messages out Rate msg bytes in Rate msg bytes out Disk Utilization Disk reserved4
No No No No
rts
rts
rts
rts
Amount of disk space, in bytes, reserved for destination
No
dsk
mq.metrics.destination.queue.queueName mq.metrics.destination.topic.topicName mq.metrics.destination.queue.queueName mq.metrics.destination.topic.topicName
Disk used4
Amount of disk space, No in bytes, currently in use by destination
dsk
File-based persistence only
411
TABLE 214

Description
4
(Continued)
Metrics Quantity
Disk utilization ratio
Ratio of disk space in No use to disk space reserved for destination
dsk
File-based persistence only
412
C H A P T E R
JES Monitoring Framework Reference
22
2 2
This chapter describes the monitoring information items that Message Queue exposes through the Sun Java Enterprise System Monitoring Framework (JESMF), using the Monitoring Frameworks Common Monitoring Model (CMM). It contains the following sections:

Common Attributes on page 413 Message Queue Product Information on page 414 Broker Information on page 414 Port Mapper Information on page 415 Connection Service Information on page 415 Destination Information on page 416 Persistent Store Information on page 417 User Repository Information on page 418
Common Attributes
The attributes listed in Table 221 are common to all (or almost all) CMM objects.
TABLE 221 Attribute
JESMF Common Object Attributes

Description
Name Caption Description LastUpdateTime OperationalStatus StatusDescriptions
Object name Short description Full description Time last updated Current status (for example, OK or DORMANT) Description of status
OperationalStatusLastChange Time of last change in operational status
413
Message Queue Product Information
Message Queue Product Information

Table 222 shows attributes of the Message Queue product itself that can be accessed with JESMF.
TABLE 222 Attribute
JESMF-Accessible Message Queue Product Attributes

Description
ProductName ProductIdentifyingNumber
Product name Identifying number of product, in the form urn:uuid:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Value changes for every version.
ProductVendor ProductVersion RevisionNumber BuildNumber PatchID CollectionID
Vendor name Version number Revision number Build number Patch identifier (if any) Identification key for installed product object Differentiates among product installations; usually identifies the installation location.
InstallDate
Installation date
Broker Information
Table 223 shows the JESMF-accessible attributes pertaining to each broker instance.
TABLE 223 Attribute
JESMF-Accessible Message Queue Broker Attributes

Description
PrimaryOwnerName
Name of primary system owner (broker property imq.primaryowner.name; see Table 1711) Contact information for primary system owner (broker property imq.primaryowner.contact; see Table 1711) Array of strings denoting brokers roles (taken from broker properties imq.broker.adminDefinedRoles.namen; see Table 1711) Time of last startup (date and time in milliseconds)
PrimaryOwnerContact
Roles
StartupTime
414
Connection Service Information
TABLE 223 Attribute
JESMF-Accessible Message Queue Broker Attributes

Description
(Continued)
URL ConfigurationDirectory DirectoryName
URL of Port Mapper Broker instance directory (for example, /var/imq/instances/mybroker) Distinguished name of directory (for example, LDAP) entry where static information about application is stored An empty string indicates that no information about the application is available in the directory.
Port Mapper Information

The attributes shown in Table 224 provide information about a brokers Port Mapper.
TABLE 224 Attribute
JESMF-Accessible Message Queue Port Mapper Attributes

Description
LabeledURI
URI for accessing Port Mapper, in the form mq://hostName:portNumber Is Port Mapper access secure (SSL/TLS)?
Secured
Connection Service Information

Table 225 shows the JESMF-accessible attributes pertaining to each connection service.
TABLE 225 Attribute
JESMF-Accessible Message Queue Connection Service Attributes

Description
LabeledURI
URI for accessing connection service, in the form mq://hostName:portNumber/serviceName if dynamically allocated, or mqtcp://hostName:servicePort/serviceName or mqssl://hostName:servicePort/serviceName if statically assigned
Secured ConnectionsCount NumConnectionsCreated
Is connection service access secure (SSL/TLS)? Current number of connections Cumulative number of connections created since broker started
Chapter 22 JES Monitoring Framework Reference
415
Destination Information
TABLE 225 Attribute
JESMF-Accessible Message Queue Connection Service Attributes

Description
(Continued)
FailedConnectionsCount CurrentNumberOfThreads MinThreadPoolSize
Cumulative number of connections rejected since broker started Current number of threads actively handling connections Minimum number of threads maintained in connection services thread pool (broker property imq.serviceName.min_threads; see Table 171) Number of threads beyond which no new threads are added to thread pool for use by connection service (broker property imq.serviceName.max_threads; see Table 171) Current number of message producers Current number of message consumers Cumulative number of messages received since broker started Cumulative number of messages sent since broker started Cumulative size in bytes of messages received since broker started Cumulative size in bytes of messages sent since broker started Cumulative number of packets received since broker started Cumulative number of packets sent since broker started Cumulative size in bytes of packets received since broker started Cumulative size in bytes of packets sent since broker started
MaxThreadPoolSize
NumProducers NumConsumers NumMsgsIn NumMsgsOut InBytesCount OutBytesCount NumPktsIn NumPktsOut PktBytesIn PktBytesOut
Destination Information
Table 226 shows the JESMF-accessible attributes pertaining to each destination. Each of these attributes corresponds to a Message Queue physical destination property; see Table 181 for further information.
TABLE 226 Attribute
JESMF-Accessible Message Queue Destination Attributes

Corresponding Property Description
Type MaxNumMsgs maxNumMsgs
Destination type (q = queue, t = topic) Maximum number of unconsumed messages Maximum size, in bytes, of any single message
MaxBytesPerMsg
maxBytesPerMsg
416
Persistent Store Information
TABLE 226 Attribute
JESMF-Accessible Message Queue Destination Attributes

Corresponding Property Description
(Continued)
MaxTotalMsgBytes
maxTotalMsgBytes
Maximum total memory, in bytes, for unconsumed messages Broker behavior when memory-limit threshold reached Maximum number of associated message producers Maximum number of associated active message consumers in load-balanced delivery Maximum number of associated backup message consumers in load-balanced delivery Maximum number of messages delivered to consumer in a single batch Local delivery only? Local delivery preferred? Send dead messages to dead message queue?
LimitBehavior MaxNumProducers1 MaxNumActiveConsumers2
limitBehavior
maxNumProducers
maxNumActiveConsumers
MaxNumBackupConsumers2
maxNumBackupConsumers
ConsumerFlowLimit LocalOnly1 LocalDeliveryPreferred UseDMQ1

1 2
consumerFlowLimit
isLocalOnly
1 ,2
localDeliveryPreferred useDMQ
Does not apply to dead message queue Queue destinations only
Persistent Store Information

The attributes shown in Table 227 pertain to the persistent data store.
TABLE 227 Attribute
JESMF-Accessible Message Queue Persistent Store Attributes

Description
AccessInfo InfoFormat JDBCDriver UserName
URL for accessing JDBC database Format of AccessInfo attribute (URL) JDBC driver User name for authentication
Chapter 22 JES Monitoring Framework Reference
417
User Repository Information
User Repository Information

The attributes shown in Table 228 pertain to the LDAP user repository.
TABLE 228 Attribute
JESMF-Accessible Message Queue User Repository Attributes

Description
AccessInfo InfoFormat Base GroupBase UserName
URL for accessing LDAP server Format of AccessInfo attribute (URL) Root or base node for user lookup Root or base node for group lookup User name for authentication
418
P A R T
I V
Appendixes

Appendix A, Distribution-Specific Locations of Message Queue Data Appendix B, Stability of Message Queue Interfaces Appendix C, HTTP/HTTPS Support Appendix D, JMX Support Appendix E, Frequently Used Command Utility Commands
419
420
A P P E N D I X
Distribution-Specific Locations of Message Queue Data
Sun GlassFish Message Queue data is stored in different locations based on the distribution used to install Message Queue. The tables that follow show the location of various types of Message Queue data for the following types of installations:

Installations from an IPS image on page 421 Installations from Solaris SVR4 Packages on page 423 Installations from Linux RPMs on page 424
In the tables, instanceName denotes the name of the broker instance with which the data is associated.
Installations from an IPS image

Table A1 shows the location of Message Queue data when Message Queue is installed from an IPS image, such as when the Message Queue installer is used. Locations denote the IMQ_HOME and IMQ_VARHOME directory variables defined in Directory Variable Conventions on page 27.
TABLE A1
Message Queue Data Locations for Installations from an IPS Image

Location
Data Category
Command line executable files Broker instance configuration properties Broker configuration file templates
IMQ_HOME/bin IMQ_VARHOME/instances/instanceName/props/config.properties IMQ_HOME/lib/props/broker/
421
Installations from an IPS image
TABLE A1
Message Queue Data Locations for Installations from an IPS Image

Location
(Continued)
Data Category
Persistent data store (messages, destinations, durable subscriptions, transactions, acknowledgements)
IMQ_VARHOME/instances/instanceName/fs370/ or a JDBC-accessible data store
Broker instance log file IMQ_VARHOME/instances/instanceName/log/ directory (default location) Administered objects (object store) Security: user repository Local directory of your choice or an LDAP server IMQ_VARHOME/instances/instanceName/etc/passwd or an LDAP server
Security: access control file IMQ_VARHOME/instances/instanceName/etc/accesscontrol.properties (default location) Security: password file IMQ_HOME/etc/ directory (default location) Security: example password file IMQ_HOME/etc/passfile.sample
Security: brokers key store IMQ_HOME/etc/ file location JavaDoc API documentation Example applications and configurations Java archive (.jar), Web archive (.war), and Resource Adapter archive (.rar) files External resource (.jar) files such as JDBC drivers, JAAS login modules, and so forth JMS Bridge DTD file IMQ_HOME/javadoc/index.html
IMQ_HOME/examples/
IMQ_HOME/lib/
IMQ_HOME/lib/ext
IMQ_HOME/lib/dtd
422
Installations from Solaris SVR4 Packages
Installations from Solaris SVR4 Packages

Table A2 shows the location of Message Queue data when Message Queue is installed from Solaris SVR4 packages.
TABLE A2
Message Queue Data Locations for Installations from Solaris SVR4 Packages
Location
Data Category
Command line executable files Broker instance configuration properties Broker configuration file templates Persistent data store (messages, destinations, durable subscriptions, transactions, acknowledgements)
/usr/bin /var/imq/instances/instanceName/props/config.properties /usr/share/lib/imq/props/broker/ /var/imq/instances/instanceName/fs370 or a JDBC-accessible data store
Broker instance log file /var/imq/instances/instanceName/log/ directory (default location) Administered objects (object store) Security: user repository Local directory of your choice or an LDAP server /var/imq/instances/instanceName/etc/passwd or an LDAP server
Security: access control file /var/imq/instances/instanceName/etc/accesscontrol.properties (default location) Security: password file /var/imq/instances/instanceName/etc/ directory (default location) Security: example password file /etc/imq/passfile.sample
Security: brokers key store /etc/imq/ file location JavaDoc API documentation Example applications and configurations /usr/share/javadoc/imq/index.html
/usr/demo/imq/
Appendix A Distribution-Specific Locations of Message Queue Data
423
Installations from Linux RPMs
TABLE A2
Message Queue Data Locations for Installations from Solaris SVR4 Packages
Location
(Continued)
Data Category
Java archive (.jar), Web archive (.war), and Resource Adapter archive (.rar) files External resource (.jar) files such as JDBC drivers, JAAS login modules, and so forth JMS Bridge DTD file
/usr/share/lib/imq
/usr/share/lib/imq/ext
/usr/share/lib/imq/dtd

Table A3 shows the location of Message Queue data when Message Queue is installed from Linux RPMs.
TABLE A3
Message Queue Data Locations for Installations from Linux RPMs

Location
Data Category
Command line executable files Broker instance configuration properties Broker configuration file templates Persistent data store (messages, destinations, durable subscriptions, transactions, acknowledgements)
/opt/sun/mq/bin /var/opt/sun/mq/instances/instanceName/props/config.properties /opt/sun/mq/private/share/lib/props/ /var/opt/sun/mq/instances/instanceName/fs370/ or a JDBC-accessible data store
Broker instance log file /var/opt/sun/mq/instances/instanceName/log/ directory (default location) Administered objects (object store) Security: user repository Local directory of your choice or an LDAP server /var/opt/sun/mq/instances/instanceName/etc/passwd or an LDAP server
Security: access control file /var/opt/sun/mq/instances/instanceName/etc/accesscontrol.properties (default location)
424
TABLE A3
Message Queue Data Locations for Installations from Linux RPMs

Location
(Continued)
Data Category
Security: password file /var/opt/sun/mq/instances/instanceName/etc/ directory (default location) Security: example password file /etc/opt/sun/mq/passfile.sample
Security: brokers key store /etc/opt/sun/mq/ file location JavaDoc API documentation Example applications and configurations Java archive (.jar), Web archive (.war), and Resource Adapter archive (.rar) files External resource (.jar) files such as JDBC drivers, JAAS login modules, and so forth Shared library (.so) files JMS Bridge DTD file /opt/sun/mq/javadoc/index.html
/opt/sun/mq/examples/
/opt/sun/mq/share/lib/
/opt/sun/mq/share/lib/ext
/opt/sun/mq/lib/ /opt/sun/mq/share/lib/dtd
Appendix A Distribution-Specific Locations of Message Queue Data
425
426
A P P E N D I X
Stability of Message Queue Interfaces
Sun GlassFish 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.
Classification Scheme
Appendix B, Stability of Message Queue Interfaces, describes the stability classification scheme.
TABLE B1
Interface Stability Classification Scheme

Description
Classification
Private Evolving
Not for direct use by customers. May change or be removed in any release. 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. For use by customers. Subject to incompatible change at a major (for example, 3.0 or 4.0) release only. 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. 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.
Stable Standard
Unstable
427
Interface Stability
Interface Stability
Appendix B, Stability of Message Queue Interfaces, lists the interfaces and their classifications.
TABLE B2 Interface

Classification
Command Line Interfaces imqbrokerd command line interface imqadmin command line interface imqcmd command line interface imqdbmgr command line interface imqkeytool command line interface imqobjmgr command line interface imqusermgr command line interface imqbridgemgr command line interface Output from imqbrokerd, imqadmin, imqcmd, imqdbmgr, imqkeytool, imqobjmgr, imqusermgr Commands imqobjmgr command file imqbrokerd command imqadmin command imqcmd command imqdbmgr command imqkeytool command imqobjmgr command imqusermgr command imqbridgemgr command APIs JMS API (javax.jms) JAXM API (javax.xml) C-API Standard Standard Evolving Evolving Stable Unstable Stable Unstable Stable Stable Unstable Evolving Evolving Unstable Evolving Unstable Evolving Evolving Unstable Evolving Unstable
428
Interface Stability
TABLE B2 Interface
(Continued)
Classification
C-API environment variables Message-based monitoring API Administered Object API (com.sun.messaging) .jar and .war Files imq.jar location and name jms.jar location and name imqbroker.jar location and name imqutil.jar location and name imqadmin.jar location and name imqservlet.jar location and name imqhttp.war location and name imqhttps.war location and name imqjmsra.rar location and name imqxm.jar location and name jaxm-api.jar location and name saaj-api.jar location and name saaj-impl.jar location and name activation.jar location and name mail.jar location and name dom4j.jar location and name fscontext.jar location and name Files Broker log file location and content format password file accesscontrol.properties file System Destinations mq.sys.dmq destination mq.metrics.* destinations
Unstable Evolving Evolving
Stable Evolving Private Private Private Evolving Evolving Evolving Evolving Evolving Evolving Evolving Evolving Evolving Evolving Private Unstable
Unstable Unstable Unstable
Stable Evolving
Appendix B Stability of Message Queue Interfaces
429
Interface Stability
TABLE B2 Interface
(Continued)
Classification
Configuration Properties Message Queue JMS Resource Adapter configuration properties Message Queue JMS Resource Adapter JavaBean and ActivationSpec configuration properties Message Properties and Formats Dead message queue message property, JMSXDeliveryCount Dead message queue message properties, JMS_SUN_* Message Queue client message properties: JMS_SUN_* JMS message format for metrics or monitoring messages Miscellaneous Message Queue JMS Resource Adapter package, com.sun.messaging.jms.ra JDBC schema for storage of persistent messages Evolving Evolving Standard Evolving Evolving Evolving Evolving Evolving
430
A P P E N D I X
HTTP/HTTPS Support
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:

HTTP/HTTPS Support Architecture on page 431 Enabling HTTP/HTTPS Support on page 432 Troubleshooting on page 446
HTTP/HTTPS Support Architecture

Message Queues support architecture is very similar for both HTTP and HTTPS support, as shown in Figure C1:
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 proxys address is specified using command line options when starting the client; seeUsing an HTTP Proxy on page 446 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 clients HTTP requests. A single tunnel servlet can be used to access multiple brokers.
431
Enabling HTTP/HTTPS Support
On the broker side, the httpjms or httpsjms connection service unwraps and demultiplexes incoming messages from the corresponding tunnel servlet.
FIGURE C1
HTTP/HTTPS Support Architecture
Broker
httpjms/httpsjms Connection Services JMS Client Message Queue Client Runtime HTTP HTTP Tunnel Servlet HTTPS Tunnel Servlet Web Server or Application Server
TLS
TCP
Firewall
HTTPS
HTTP Proxy
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 Queues 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.) 1. (HTTPS only) Generate a self-signed certificate for the HTTPS tunnel servlet.
2. (HTTPS only) Modify the deployment descriptor in the tunnel servlets .war file to specify the location and password of the certificate key store. 3. (HTTPS only) Validate the Web or application servers self-signed certificate and install it in the client applications trust store. 4. (HTTP and HTTPS) Deploy the HTTP or HTTPS tunnel servlet. 5. (HTTP and HTTPS) Configure the brokers httpjms or httpsjms connection service and start the broker. 6. (HTTP and HTTPS) Configure an HTTP or HTTPS connection. The following subsections describe each of these steps in greater detail, using Sun GlassFish Application Server as an example for purposes of illustration. If you are using a different application server or Web server (such as Sun GlassFish Web Server), the procedures will be substantially similar but may differ in detail; see your server products own documentation for specifics.
Step 1 (HTTPS Only): Generating a Self-Signed Certificate for the Tunnel Servlet
Message Queues 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 Queues 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 C1 shows the prompts and the values to be provided for each prompt. Values are case-insensitive and can include spaces.
Appendix C HTTP/HTTPS Support
433
TABLE C1 Prompt
Distinguished Name Information Required for a Self-Signed Certificate

X.500 Attribute Description Example
What is your first and last name? What is the name of your organizational unit? What is the name of your organization? What is the name of your city or locality?
commonName (CN) organizationalUnit (OU) organizationName (ON) localityName (L)
Fully qualified name of server running mqserver.sun.com the broker Name of department or division Name of larger organization, such as a company or government entity Name of city or locality Full (unabbreviated) name of state or province Standard two-letter country code purchasing
Acme Widgets, Inc.
San Francisco
What is the name of your state stateName (ST) or province? What is the two-letter country code for this unit? country (C)
California
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.
Caution 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 Queues key store file at the location you specified for the keyStoreLocation argument.
Caution 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 on page 440).
434
Step 2 (HTTPS Only): Specifying the Key Store Location and Password
The tunnel servlets 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.)
To Specify the Location and Password of the Certificate Key Store

1
Copy the .war file to a temporary directory: The location of the HTTPS tunnel servlets .war file varies, depending on how Message Queue was installed (see Appendix A, Distribution-Specific Locations of Message Queue Data): IPS packages: cp IMQ_HOME/lib/imqhttps.war /tmp Solaris SVR4 packages: cp /usr/share/lib/imq/imqhttps.war /tmp Linux RPM packages: cp /opt/sun/mq/share/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 files 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>
Appendix C HTTP/HTTPS Support 435
</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>

Note 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.) 6
Reassemble the contents of the .war file. jar uvf imqhttps.war WEB-INF/web.xml
Step 3 (HTTPS Only): Validating and Installing the Servers Self-Signed Certificate
In order for a client application to communicate with the Web or application server, you must validate the servers self-signed certificate and install it in the applications trust store. The following procedure shows how:
To Validate and Install the Servers Self-Signed Certificate

1
Validate the servers certificate. By default, the Sun GlassFish 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.
Note 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
436
a. Make the directory containing the key store file your current directory. For example, to use the Application Servers 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. b. List the contents of the key store file. The Key Tool utilitys -list option lists the contents of a specified key store file. For example, the following command lists the Application Servers 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. c. Enter the key store password. The Key Tool utility prompts you for the key store files password: Enter keystore password: By default, the key store password is set to changeit; you can use the Key Tool utilitys -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:
437
Keystore type: JKS Keystore provider: SUN Your keystore contains 1 entry Alias name: slas Creation date: Nov 13, 2007 Entry type: PrivateKeyEntry Certificate chain length: 1 Certificate[1]: Owner: CN=helios, OU=Sun Java System Application Server, O=Sun Microsystems, L=Santa Clara, ST=California, C=US Issuer: CN=helios, OU=Sun Java System Application Server, O=Sun Microsystems, L=Santa Clara, ST=California, C=US Serial number: 45f74784 Valid from: Tue Nov 13 13:18:39 PST 2007 until: Fri Nov 10 13:18:39 PST 2017 Certificate fingerprints: MD5: 67:04:CC:39:83:37:2F:D4:11:1E:81:20:05:98:0E:D9 SHA1: A5:DE:D8:03:96:69:C5:55:DD:E1:C4:13:C1:3D:1D:D0:4C:81:7E:CB Signature algorithm name: MD5withRSA Version: 1
d. Verify the certificates fingerprints. Obtain the correct fingerprints for the Application Servers 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 applications trust store unless the fingerprints match.
2
Export the Application Servers certificate to a certificate file. Use the Key Tool utilitys -export option to export the certificate from the Application Servers key store to a separate certificate file, from which you can then import it into your applications trust store. For example, the following command exports the certificate shown above, whose alias is slas, from the Application Servers 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>
438
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: a. List the contents of the certificate file. The Key Tool utilitys -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 certificates fingerprints in human-readable form. The resulting output looks like the following:
Owner: CN=helios, OU=Sun Java System Application Server, O=Sun Microsystems, L=Santa Clara, ST=California, C=US Issuer: CN=helios, OU=Sun Java System Application Server, O=Sun Microsystems, L=Santa Clara, ST=California, C=US Serial number: 45f74784 Valid from: Tue Nov 13 13:18:39 PST 2007 until: Fri Nov 10 13:18:39 PST 2017 Certificate fingerprints: MD5: 67:04:CC:39:83:37:2F:D4:11:1E:81:20:05:98:0E:D9 SHA1: A5:DE:D8:03:96:69:C5:55:DD:E1:C4:13:C1:3D:1D:D0:4C:81:7E:CB Signature algorithm name: MD5withRSA Version: 1
b. Confirm the certificates contents. Examine the output from the keytool -printcert command to make sure that the certificate is correct.
4
Import the certificate into your applications trust store. The Key Tool utilitys -import option installs a certificate from a certificate file in a specified trust store. For example, if your client applications 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"
439
Step 4 (HTTP and HTTPS): Deploying the Tunnel Servlet

You can deploy the HTTP or HTTPS tunnel servlet on Sun GlassFish Application Server either from the command line or by using the Application Servers Web-based administration GUI. In either case, you must then modify the Application Servers 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 Servers Security Policy File on page 441 for instructions on how to grant it the appropriate permissions.
To Deploy the HTTP or HTTPS Tunnel Servlet

1
Deploy the tunnel servlet: a. In the Web-based administration GUI, choose App Server>Instances>appServerInstance>Applications>Web Applications where appServerInstance is the Application Server instance on which you are deploying the tunnel servlet. b. Click the Deploy button.
Specify the .war file location: a. Enter the location of the tunnel servlets 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, Distribution-Specific Locations of Message Queue Data). b. Click the OK button.
440
Specify the context root directory: a. Enter the /contextRoot portion of the tunnel servlets 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 b. 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 servers security policy file Once you have deployed the HTTP or HTTPS tunnel servlet, you must grant it the appropriate permissions by modifying the Application Servers security policy file, as described in the next procedure.
Modifying the Application Servers Security Policy File

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:
1
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 GlassFish Application Server is installed.
2
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.
Step 5 (HTTP and HTTPS): Configuring the Connection Service

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 C2 shows broker configuration properties pertaining specifically to these two connection services. Once reconfigured, the broker can be started normally, as described under Starting Brokers on page 70.
TABLE C2 Property
Broker Configuration Properties for the httpjms and httpsjms Connection Services
imq.httpjms.http.servletHost imq.httpsjms.https.servletHost imq.httpjms.http.servletPort imq.httpsjms.https.servletPort imq.httpjms.http.pullPeriod imq.httpsjms.https.pullPeriod
String Integer Integer
localhost httpjms: 7675 httpsjms: 7674 1
Host name or IP address of (local or remote) host running tunnel servlet Port number of tunnel servlet Interval, in seconds, between client HTTP/HTTPS requests If zero or negative, the client will keep one request pending at all times.
imq.httpjms.http.connectionTimeout imq.httpsjms.https.connectionTimeout
Integer
60
Tunnel servlet timeout interval
To Activate the httpjms or httpsjms Connection Service

1
Open the brokers 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:
442
.../instances/instanceName/props/config.properties (See Appendix A, Distribution-Specific Locations of Message Queue Data, for the location of the instances directory.)
2
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 C2): for example, imq.httpjms.http.servletHost=helios imq.httpjms.http.servletPort=7675 You can also improve performance by reconfiguring the connection services 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 clients 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.)
Step 6 (HTTP and HTTPS): Configuring a Connection

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.
Installing a Root Certificate (HTTPS Only)

If the root certificate of the certification authority (CA) that signed your application servers (or Web servers) 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 CAs root certificate is already in the trust store by default.)
Installing a Root Certificate in the Trust Store

1
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
Configuring the Connection Factory (HTTP and HTTPS)

To enable HTTP/HTTPS support, you need to set the connection factorys 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 on page 440. 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 on page 206). 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 Developers Guide for Java Clients).
Using a Single Servlet to Access Multiple Brokers (HTTP and HTTPS)

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 C1.
EXAMPLE C1
Tunnel Servlet Status Report
HTTP tunnel servlet ready. Servlet Start Time : Thu May 30 01:08:18 PDT 2002 Accepting secured connections from brokers on port : 7675 Total available brokers = 2 Broker List : helios:broker1 selene:broker2
445
Troubleshooting
Using an HTTP Proxy

To use an HTTP proxy to access the HTTPS tunnel servlet, set the system properties http.proxyHost and http.proxyPort to the proxy servers host name and port number. You can set these properties using the -D option to the command that launches the client application.
Troubleshooting
This section describes possible problems with an HTTP or HTTPS connection and provides guidance on how to handle them.
Server or Broker Failure

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.
Client Failure to Connect Through the Tunnel Servlet

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

1 2 3
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.
446
A P P E N D I X
JMX Support
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 Developers Guide for JMX Clients. This appendix describes the JMX support infrastructure on the broker side, including the following topics:

JMX Connection Infrastructure on page 447 JMX Configuration on page 450
JMX Connection Infrastructure

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 GlassFish Message Queue 4.4 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 resources configuration properties and monitoring its runtime state.
MBean Access Mechanism

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
447
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 on page 454). 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.
FIGURE D1
Basic JMX Infrastructure
JMX Runtime
Broker
MBean Server
JMX Client
JMX Connector Stub
JMX Connector MBean Server Connection MBeans
The JMX Service URL

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.
448
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 on page 452) or dynamic (see Dynamic JMX Service URL: Not Using an RMI Registry on page 453). 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 on page 450). 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.
FIGURE D2
Obtaining a Connector Stub from an RMI Registry
JMX Client
JMX Runtime
RMI Registry
Broker
JMX Connector Stub JMX Connector JMX Connector Stub MBean Server Connection
MBean Server
MBeans
The Admin Connection Factory

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
Appendix D JMX Support 449
JMX Configuration
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.
FIGURE D3
Obtaining a Connector Stub from an Admin Connection Factory
JMX Client
MQ/JMX Runtime
Admin Connection Factory MBean Server Connection
Broker
Port Mapper MBean Server JMX Connector
JMX Connector Stub
MBeans
For programmatic details, see Obtaining a JMX Connector from an Admin Connection Factory in Sun GlassFish Message Queue 4.4 Developers Guide for JMX Clients
JMX Configuration
Broker configuration properties that support JMX are listed in Table 1716. 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 on page 450 SSL-Based JMX Connections on page 454 JMX Connections Through a Firewall on page 455
RMI Registry Configuration

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:
450
JMX Configuration
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 D1 Scenario
Advantages and Disadvantages of Using an RMI Registry

Broker Configuration Advantages Disadvantages
Using a Registry
Configuration Properties:
imq.jmx.rmigegistry.start (Static JMX imq.jmx.rmigegistry.use Service URL) 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.
Appendix D JMX Support
451
JMX Configuration
TABLE D1 Scenario
Advantages and Disadvantages of Using an RMI Registry

Broker Configuration Advantages
(Continued)
Disadvantages
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 161).
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 on page 448) 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.
EXAMPLE D1
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 ------------------------452 Sun GlassFish Message Queue 4.4 Administration Guide June 2010
JMX Configuration
EXAMPLE D1
JMX Service URL When Using an RMI Registry 7676
(Continued)
localhost Name jmxrmi
Active URL 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 D2
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 jmxrmi Active URL true service:jmx:rmi://yourhost/stub/rO0ABdmVyLlJlpIDJy==
ssljmxrmi false Successfully listed JMX Connectors.

JMX Configuration
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 on page 447, 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.
To 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 on page 167. 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.
2 3
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");
JMX Configuration
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:
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.
EXAMPLE D3
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 D4
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:
JMX Configuration
EXAMPLE D4
JMX Configuration for Firewall When Using an RMI Registry
(Continued)
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.
456
A P P E N D I X
Frequently Used Command Utility Commands
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 on page 318 in Command Utility on page 318
Syntax
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
Broker and Cluster Management

imqcmd imqcmd imqcmd imqcmd imqcmd imqcmd imqcmd query bkr pause bkr restart bkr resume bkr shutdown bkr -b myBroker:7676 update bkr -o "imq.system.max_count=1000" reload cls
457
Service and Connection Management
Broker Configuration Properties (-o option)

Broker Configuration Properties (-o option) on page 458 lists frequently used broker configuration properties. For a full list of broker configuration properties and their descriptions, see Chapter 17, Broker Properties Reference
TABLE E1 Property
Broker Configuration Properties ( -o option)

Notes
imq.autocreate.queue imq.autocreate.queue.maxNumActiveConsumers imq.autocreate.queue.maxNumBackupConsumers imq.autocreate.topic imq.cluster.url imq.destination.DMQ.truncateBody imq.destination.logDeadMessages imq.log.file.rolloverbytes imq.log.file.rolloversecs imq.log.level Specify 1 for unlimited Specify 1 for unlimited NONE ERROR WARNING INFO Specify 1 for unlimited Specify 1 for unlimited Specify 1 for unlimited
imq.message.max_size imq.portmapper.port imq.system.max_count imq.system.max_size
Specify 1 for unlimited Specify 1 for unlimited
Service and Connection Management

imqcmd imqcmd imqcmd imqcmd imqcmd imqcmd imqcmd
458
list svc query svc update svc -n jms -o "minThreads=200" -o "maxThreads=400" -o "port=8995" pause svc -n jms resume svc -n jms list cxn -svn jms query cxn -n 1234567890
Destination Management
Durable Subscriber Management

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"
Transaction Management
imqcmd imqcmd imqcmd imqcmd list txn commit txn -n 1234567890 query txn -n 1234567890 rollback txn -n 1234567890
Destination Management
imqcmd imqcmd imqcmd imqcmd imqcmd imqcmd imqcmd imqcmd imqcmd
create dst -n MyQueue -t q -o "maxNumMsgs=1000" -o "maxNumProducers=5" update dst -n MyTopic -t t -o "limitBehavior=FLOW_CONTROL| REMOVE_OLDEST|REJECT_NEWEST|REMOVE_LOW_PRIORITY compact dst -n MyQueue -t q purge dst -n MyQueue -t q pause dst -n MyQueue -t q -pst PRODUCERS|CONSUMERS|ALL resume dst -n MyQueue -t q destroy dst -n MyQueue -t q query dst -n MyQueue -t q list dst -tmp
Destination Configuration Properties (-o option)

Destination Configuration Properties (-o option) on page 459 lists frequently used destination configuration properties. For a full list of destination configuration properties and their descriptions, see Chapter 18, Physical Destination Property Reference
TABLE E2 Property

Notes
consumerFlowLimit isLocalOnly (create only) limitBehavior
Specify 1 for unlimited
FLOW_CONTROL REMOVE_OLDEST REJECT_NEWEST REMOVE_LOW_PRIORITY
localDeliveryPreferred (queue only)
Appendix E Frequently Used Command Utility Commands
459
Metrics
TABLE E2 Property

Notes
(Continued)
maxNumActiveConsumers (queue only) maxNumBackupConsumers (queue only) maxBytesPerMsg maxNumMsgs maxNumProducers maxTotalMsgBytes useDMQ
Specify 1 for unlimited Specify 1 for unlimited Specify 1 for unlimited Specify 1 for unlimited Specify 1 for unlimited Specify 1 for unlimited
Metrics
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
460
Index
A
access control file location, 422, 423, 424 acknowledgeMode ActivationSpec property, 398 ActivationSpec JavaBean, 397 addressList ActivationSpec property, 397 addressList managed connection factory attribute, 395 addressList Resource Adapter attribute, 392 addressListBehavior managed connection factory attribute, 395 addressListBehavior Resource Adapter attribute, 393 addressListIterations managed connection factory attribute, 395 addressListIterations Resource Adapter attribute, 393 admin connection service, 97 ADMIN service type, 96 admin user changing password, 146 initial entry, 142 administered objects attributes (reference), 381 deleting, 208-209 listing, 209-210 managing, 195-214 object store See object stores querying, 210 required information, 205 updating, 211 XA connection factory See connection factory administered objects
Administration Console starting, 42 tutorial, 41 administration tasks development environment, 35-36 production environment, 36-37 administration tools Administration Console, 39 built-in, 38-39 command line utilities, 38 JMX-based administration, 40 administrator password, 146 API documentation, 422, 423, 425 attributes of physical destinations, 375-379 audit logging, 172 authentication See also access control about, 139 JAAS-based See JAAS-based authentication managing, 141-155 authorization See also access control about, 140 managing, 155-161 user groups, 140 auto-create destinations, access control settings, 140 auto-created destinations access control settings, 160 broker properties (table), 342-345 default property values, 112 automatic reconnection, 200
461
Index
automatic reconnection (Continued) limitations, 200 AUTOSTART property, 72, 73
B
benchmarks, performance, 266-267 bottlenecks, performance, 269 broker clusters adding brokers to, 184 architecture, 277 configuration file, 176, 182, 183, 188, 361 configuration properties, 175, 361-363 connecting conventional brokers, 182 conventional automatic reconnection in, 200 high-availability automatic reconnection in, 200 listing brokers, 94, 180-181, 323 pausing physical destinations in, 113 performance effect of, 277 purging physical destinations in, 114 reasons for using, 277 reloading configuration, 322 secure interbroker connections (SSL), 184 broker components clustering services, 80 connection services, 79, 95 monitoring services, 80, 245-246 persistence services, 79, 127-128 routing services, 79, 121 security services, 79, 137-140 broker metrics Logger properties, 249, 253, 360 metrics messages, 260 metrics quantities (table), 404-406 reporting interval, Logger, 317 using broker log files, 253 using imqcmd, 256-257, 258 using message-based monitoring, 261 broker monitoring service, properties, 357-361 broker responses, wait period for client, 386 broker states, 180 brokerEnableHA Resource Adapter attribute, 393
462
brokerID Resource Adapter attribute, 394 brokerInstanceName Resource Adapter attribute, 392 brokers access control See authorization auto-create physical destination properties, 342-345 clock synchronization, 69-70 clustering, 182 clusters See broker clusters commands for managing, 321-323 configuration files See configuration files displaying metrics, 323 failure recovery, 127 httpjms connection service properties, 442 httpsjms connection service properties, 442 instance configuration properties, 81 instance name, 314 interconnected See broker clusters JMX, and, 40, 259 limit behaviors, 122, 277 listing, 94 listing connection services, 101 listing property values, 322 logging See Logger managing, 85-94 memory management, 122, 277 message capacity, 92, 122, 340 message flow control See message flow controls metrics See broker metrics pausing, 91, 322 permissions required for starting, 70 programmatic management of, 40, 259 properties (reference), 337, 375 querying, 92 quiescing, 90, 322 re-creating state, 127 removing, 76 restarting, 90, 322
Index
brokers (Continued) restarting automatically, 72, 73 resuming, 91, 322 running as Windows service, 73-76 setting properties, 322 shutting down, 89, 321 starting automatically, 71-76 starting interactively, 70-71 startup with SSL, 165 states of See broker states takeover, 322 unquiescing, 90, 322 updating properties of, 91-92 viewing information about, 92-94 viewing metric information, 93
C
certificates self-signed, 161-167, 433 signed, 167-170 client applications example, 422, 423, 425 factors affecting performance, 270-274 client identifier (ClientID) for durable subscribers, 202-203 in destroying durable subscription, 124 client runtime configuration of, 278 message flow tuning, 282 clientID activation specification attribute, 398 clientID ActivationSpec property, 398 clientID managed connection factory attribute, 395 clients clock synchronization, 69-70 starting, 77 clock synchronization, 69-70 cluster configuration file, 176, 182, 183, 188, 361 cluster configuration properties, 175, 361 cluster connection service configuring for SSL, 161, 184 host name or IP address for, 177, 362 network transport for, 177, 362
cluster connection service (Continued) port number for, 177, 362 cluster identifier, 178, 363 cluster.properties file, 80 clusterID Resource Adapter attribute, 394 clustering brokers, 182 clustering services, broker, 80 clusters, See broker clusters command files, 211-214 command line syntax, 313 command line utilities about, 38 basic syntax, 313 displaying version, 87, 144, 321 help, 88, 144, 321 imqbrokerd, See, imqbrokerd command, 38 imqcmd, See, imqcmd command, 38 imqdbmgr See, imqdbmgr command, 38 imqkeytool, See, imqkeytool command, 38 imqobjmgr, See, imqobjmgr command, 38 imqsvcadmin, See, imqsvcadmin command, 38 imqusermgr, See, imqusermgr command, 38 command line utility executables location, 421, 423, 424 command options, as configuration overrides, 77 compacting file-based data store, 129 physical destinations, 119 config.properties file, 80, 81, 184, 186, 442 configuration change record backing up, 187 restoring, 187 configuration files broker (figure), 81 cluster, 80, 176, 182, 183, 188, 361 default, 80 installation, 80 instance, 80, 81, 421, 423, 424 location, 421, 423, 424 modifying, 80 template location, 421, 423, 424 templates, 421, 423, 424 connection factories, adding administered objects for, 206-207
463
Index
connection factory administered objects application server support attributes, 388 attributes, 198-205 client identification attributes, 201-203 connection handling attributes, 198-201 JMS properties support attributes, 204 overriding message header fields, 204 queue browser behavior attributes, 204, 387-388 reliability and flow control attributes, 203 standard message properties, 388 connection service metrics metrics quantities, 406-407 using imqcmd metrics, 257 using imqcmd query, 258 connection services access control for, 138, 352 activated at startup, 338 admin See admin connection service cluster, 362 See cluster connection service commands for managing, 323-324 displaying metrics, 324 HTTP See HTTP connections httpjms See httpjms connection service HTTPS See HTTPS connections httpsjms See httpsjms connection service jms See jms connection service listing, 101 listing available, 323 listing property values, 323 pausing, 99, 323 Port Mapper See Port Mapper properties, 338-340 protocol type, 96 querying, 101 resuming, 100, 323 service type, 96
464
connection services (Continued) SSL-based, 164 ssladmin See ssladmin connection service ssljms See ssljms connection service ssljms connection service, 96 thread allocation, 100 thread pool management, 98 updating, 100, 323 viewing information about, 101-103 viewing metric information, 102 connection services, broker, 79 connections automatic reconnection See automatic reconnection commands for managing, 324 destroying, 104, 324 failover See automatic reconnection limited by file descriptor limits, 70 listing, 103, 324 performance effect of, 275-276 querying, 104, 125, 324 connectionURL Resource Adapter attribute, 392 consumerFlowLimit destination property, 377, 417 consumerFlowLimit property, 203 customAcknowledgeMode ActivationSpec property, 399
D
data store about, 127, 128 compacting, 129 contents of, 127 file-based, 128-129 JDBC-based, 131-133 location, 422, 423, 424 performance effect of, 277-278 resetting, 315 synchronizing to disk, 129 dead message queue configuring use of, 120
Index
dead message queue (Continued) described, 120-121 logging, 121, 249 managing, 120-121 truncating message bodies, 121 UseDMQ property, 417 variant treatment of physical destination properties, 120-121 dead messages See also dead message queue logging, 249 default.properties file, 80 deleting, broker instance, 76 delivery modes, performance effect of, 271 destination activation specification attribute, 398 destination ActivatioSpec property, 397 destination administered objects, attributes, 205 destination metrics metrics quantities, 407-412 using imqcmd metrics, 255, 257-258 using imqcmd query, 258 using message-based monitoring, 261 destinations See physical destinations adding administered objects for, 207-208 destinationType activation specification attribute, 398 destinationType ActivationSpec property, 398 destroying connections, 104, 324 durable subscriptions, 326 physical destinations, 112, 325 development environment administration tasks, 35-36 directory lookup for clusters (Linux), 183 disk utilization by physical destinations, 118-120 displaying product version, 87, 144, 321 DN username format, 355 durable subscriptions commands for managing, 326-327 destroying, 124, 326 listing, 123, 326 managing, 123 performance effect of, 273 purging messages for, 326
E
encryption about, 137, 140 implementing, 161-170 Key Tool and, 140 endpointExceptionRedeliveryAttempts ActivationSpec property, 399 enhanced clusters, takeover states, 180 /etc/hosts file (Linux), 183 example applications, 422, 423, 425 external resource files directory, 422, 424, 425
F
file-based persistence about, 128 configuring, 129 properties, 128-129 file-based persistence, tuning for performance, 281 file descriptor limits, 70 connection limits and, 70 file synchronization imq.persist.file.sync.enabled option, 347 with Sun Cluster, 347 firewalls, 431 flow control, See message flow controls fragmentation of messages, 129
G
guest user, 142
H
hardware, performance effect of, 275 help (command line), 88, 144, 321 hosts file (Linux), 183 HTTP connection service See httpjms connection service proxy, 431 support architecture, 431-432
465
Index
HTTP (Continued) transport driver, 431 HTTP connections request interval, 442 support for, 431 tunnel servlet See HTTP tunnel servlet HTTP protocol type, 97 HTTP tunnel servlet about, 431 deploying, 440-442 httpjms connection service, 97 configuring broker for, 442-443 HTTPS connection service See httpsjms connection service support architecture, 431-432 HTTPS connections multiple brokers, for, 445-446 request interval, 442 support for, 431 tunnel servlet See HTTPS tunnel servlet HTTPS protocol type, 97 HTTPS tunnel servlet about, 431 deploying, 440-442 httpsjms connection service, 161 configuring broker for, 442-443 intoduced, 97 setting up, 432-446
I
imq.accesscontrol.enabled property, 137, 352 imq.accesscontrol.file.filename property, 138, 352 imq.accesscontrol.file.url property, 353 imq.accesscontrol.type property, 352 imq.admin.tcp.port property, 171 imq.audit.bsm.disabled property, 354 imq.audit.enabled property, 172, 173, 354 imq.authentication.basic.user_repository property, 139, 351
466
imq.authentication.client.response.timeout property, 139, 352 imq.authentication.type property, 139, 351 imq.autocreate.destination.isLocalOnly property, 344 imq.autocreate.destination.limitBehavior property, 342, 343 imq.autocreate.destination.maxBytesPerMsg property, 342 imq.autocreate.destination.maxCount property, 342 imq.autocreate.destination.maxNumMsgs property, 342 imq.autocreate.destination.maxNumProducers property, 343 imq.autocreate.destination.maxTotalMsgBytes property, 343, 345 imq.autocreate.destination.useDMQ property, 120 imq.autocreate.queue.consumerFlowLimit property, 344 imq.autocreate.queue.localDeliveryPreferred property, 345 imq.autocreate.queue.maxNumActiveConsumers property, 92, 344 imq.autocreate.queue.maxNumBackupConsumers property, 92, 344 imq.autocreate.queue property, 92, 342 imq.autocreate.reaptime property, 342 imq.autocreate.topic property, 92, 342 imq.broker.adminDefinedRoles.count property, 361, 369 imq.broker.adminDefinedRoles.nameN property, 361 imq.broker.adminDefinedRoles.namen property, 369, 414 imq.brokerid property, 133, 178, 338 imq.cluster.brokerlist property, 177, 182, 183, 184, 185, 362 imq.cluster.clusterid property, 178, 363 imq.cluster.ha, 361 imq.cluster.ha property, 178 imq.cluster.heartbeat.hostname property, 179, 363 imq.cluster.heartbeat.interval property, 179, 363 imq.cluster.heartbeat.port property, 179, 363 imq.cluster.heartbeat.threshold property, 179, 363 imq.cluster.hostname property, 177, 362 imq.cluster.masterbroker property, 177, 185, 186, 362
Index
imq.cluster.monitor.interval property, 179, 363 imq.cluster.monitor.threshold property, 179, 363 imq.cluster.port property, 177, 362 imq.cluster.transport property, 177, 184, 185, 362 imq.cluster.url property, 92, 176, 183, 184, 185, 186, 361 imq.destination.DMQ.truncateBody property, 92, 121, 122, 341 imq.destination.logDeadMsgs property, 92, 249, 357 imq.hostname property, 98, 338 imq.httpjms.http.connectionTimeout property, 442 imq.httpjms.http.pullPeriod property, 442 imq.httpjms.http.servletHost property, 442 imq.httpjms.http.servletPort property, 442 imq.httpsjms.https.connectionTimeout property, 442 imq.httpsjms.https.pullPeriod property, 442 imq.httpsjms.https.servletHost property, 442 imq.httpsjms.https.servletPort property, 442 imq.imqcmd.password property, 139, 171, 353 imq.jms.tcp.port property, 171 imq.jmx.connector.activelist property, 366 imq.jmx.connector.RMIconnectorName. brokerHostTrusted property, 367 imq.jmx.connector.RMIconnectorName.port property, 366 imq.jmx.connector.RMIconnectorName.urlpath property, 366 imq.jmx.connector.RMIconnectorName.useSSL property, 367 imq.jmx.rmiregistry.port property, 368 imq.jmx.rmiregistry.start property, 367 imq.jmx.rmiregistry.use property, 367 imq.keystore.file.dirpath property, 164, 353 imq.keystore.file.name property, 164, 353 imq.keystore.password property, 140, 171, 353 imq.log.console.output property, 249, 358 imq.log.console.stream property, 249, 357 imq.log.file.dirpath property, 249, 358 imq.log.file.filename property, 249, 358 imq.log.file.output property, 249, 358 imq.log.file.rolloverbytes property, 92, 249, 358 imq.log.file.rolloversecs property, 92, 249, 359 imq.log.level property, 92, 249, 357 imq.log.syslog.facility property, 359
imq.log.syslog.identity property, 359 imq.log.syslog.logconsole property, 360 imq.log.syslog.logpid property, 359 imq.log.syslog.output property, 249, 359 imq.log.timezone property, 360 imq.message.expiration.interval property, 122, 341 imq.message.max_size property, 92, 122, 341 imq.metrics.enabled property, 245, 360 imq.metrics.interval property, 245, 360 imq.metrics.topic.enabled property, 261, 360 imq.metrics.topic.interval property, 261, 360 imq.metrics.topic.persist property, 261, 360 imq.metrics.topic.timetolive property, 261, 361 imq.passfile.dirpath property, 139, 353 imq.passfile.enabled property, 139, 353 imq.passfile.name property, 139, 353 imq.persist.file.destination.message.filepool.limit property, 129, 347 imq.persist.file.message.cleanup property, 129, 347 imq.persist.file.message.filepool.cleanratio property, 129, 347 imq.persist.file.message.max_record_size property, 346 imq.persist.file.message.vrfile.max_record_size property, 129 imq.persist.file.newTxnLog.enabled property, 348 imq.persist.file.sync.enabled property, 129, 347 imq.persist.file.sync property, 129 imq.persist.file.transaction.memorymappedfile.enabled property, 272, 347 imq.persist.file.txnLog.groupCommit property, 348 imq.persist.file.txnLog.logNonTransactedMsgAck property, 349 imq.persist.file.txnLog.logNonTransactedMsgSend property, 349 imq.persist.jdbc.connection.limit property, 350 imq.persist.jdbc.connection.limitr property, 132 imq.persist.jdbc.dbVendor property, 132, 350 imq.persist.jdbc.password property, 171 imq.persist.jdbc.vendorName.closedburl property, 350 imq.persist.jdbc.vendorName.createdburl property, 350 imq.persist.jdbc.vendorName.driver property, 350
467
Index
imq.persist.jdbc.vendorName.needpassword property, 132, 350 imq.persist.jdbc.vendorName.opendburl property, 350 imq.persist.jdbc.vendorName.password property, 132, 350 imq.persist.jdbc.vendorName.property.propName property, 132, 351 imq.persist.jdbc.vendorName.tableoption property, 351 imq.persist.jdbc.vendorName.tableoption property., 132 imq.persist.jdbc.vendorName.user property, 132, 350 imq.persist.store property, 127, 131, 133, 346 imq.ping.interval property, 99, 340 imq.portmapper.backlog property, 98, 339 imq.portmapper.hostname property, 98, 338 imq.portmapper.port property, 92, 97, 338 imq.primaryowner.contact property, 361, 372, 414 imq.primaryowner.name property, 361, 372, 414 imq.protocol.protocolType.inbufsz, 279 imq.protocol.protocolType.nodelay, 279 imq.protocol.protocolType.outbufsz, 279 imq.resource_state.count property, 341 imq.resource_state.threshold property, 341 imq.resourceState.count property, 123 imq.service.activelist property, 97, 338 imq.service_name.accesscontrol.file.filename property, 353 imq.service_name.accesscontrol.file.urlmax property, 353 imq.service_name.authentication.type property, 351 imq.service_name.max_threads property, 339, 416 imq.service_name.min_threads property, 339, 416 imq.service_name.protocol_type.hostname property, 338 imq.service_name.protocol_type.port property, 339 imq.service_name.threadpool_model property, 339 imq.serviceName.accesscontrol.enabled property, 138, 352 imq.serviceName.accesscontrol.file.filename property, 138 imq.serviceName.authentication.type property, 139 imq.serviceName.max_threads property, 98 imq.serviceName.min_threads property, 98
468
imq.serviceName.protocolType.hostname property, 98 imq.serviceName.protocolType.port property, 97 imq.serviceName.threadpool_model property, 98 imq.shared.connectionMonitor_limit property, 99, 340 imq.ssladmin.tls.port property, 172 imq.ssljms.tls.port property, 171 imq.system.max_count property, 92, 122, 340 imq.system.max_size property, 92, 122, 340 imq.transaction.autorollback property, 341 imq.transaction.consumer.maxNumMsgs property, 341 imq.transaction.producer.maxNumMsgs property, 341 imq.user_repository.jaas.groupPrincipalClass property, 356 imq.user_repository.jaas.name property, 356 imq.user_repository.jaas.userPrincipalClass property, 356 imq.user_repository.ldap.base property, 355 imq.user_repository.ldap.gidattr property, 355 imq.user_repository.ldap.grpbase property, 355 imq.user_repository.ldap.grpfilter property, 355 imq.user_repository.ldap.grpsearch property, 355 imq.user_repository.ldap.memattr property, 355 imq.user_repository.ldap.password property, 139, 171, 355 imq.user_repository.ldap.principal property, 139, 354 imq.user_repository.ldap.property_name property, 355 imq.user_repository.ldap.server property, 139, 354 imq.user_repository.ldap.ssl.enabled property, 356 imq.user_repository.ldap.timeout property, 356 imq.user_repository.ldap.uidattr property, 355 imq.user_repository.ldap.usrfilter property, 355 imq.user_repository.ldap.usrformat property, 355 imqAckTimeout attribute, 203, 386 imqAddressList attribute, 199, 200, 382 dynamically updated in enhanced clusters, 200, 382 imqAddressListBehavior attribute, 199, 200, 382 imqAddressListIterations attribute, 199, 200, 382 imqbridgemgr command options, 334 reference, 332
Index
imqbrokerd command, 70 about, 38 backing up configuration change record, 187 clearing the data store, 129 connecting brokers, 184 in password file, 170 options, 314-318 passing arguments to, 82 reference, 314 removing a broker, 76 removing a broker from a cluster, 186 restoring configuration change record, 187 setting logging properties, 251 imqbrokerd.conf file, 71 imqcmd command about, 38 displaying version, 87 general options, 320 in password file, 170 metrics monitoring, 254-258 physical destination management, 108-109 physical destination subcommands (table), 108-109 reference, 318 secure connection to broker, 166-167, 320 transaction management, 124 usage help, 88 imqConfiguredClientID attribute, 202, 385 imqConnectionFlowCount attribute, 203, 282, 386 imqConnectionFlowLimit attribute, 203, 284, 386 imqConnectionFlowLimitEnabled attribute, 203, 284, 386 imqConsumerFlowLimit attribute, 203, 283, 387 imqConsumerFlowThreshold attribute, 203, 283, 387 imqdbmgr command about, 38 in password file, 170 options, 330-331 reference, 329 imqDefaultPassword attribute, 201, 202, 385 imqDefaultUsername attribute, 201, 202, 385 imqDestinationDescription attribute, 205, 389 imqDestinationName attribute, 205, 389 imqDisableSetClientID attribute, 385 imqFlowControlLimit attribute, 387
imqJMSDeliveryMode attribute, 389 imqJMSExpiration attribute, 389 imqJMSPriority attribute, 205, 389 imqkeytool command about, 38 reference, 336 using, 163 imqLoadMaxToServerSession attribute, 204, 388 imqobjmgr command about, 38 options, 328 reference, 327 subcommands, 327 imqOverrideJMSDeliveryMode attribute, 389 imqOverrideJMSExpiration attribute, 389 imqOverrideJMSHeadersToTemporaryDestinations attribute, 205, 389 imqOverrideJMSPriority attribute, 205, 389 imqPingInterval attribute, 201 imqQueueBrowserMax MessagesPerRetrieve attribute, 204, 387 imqQueueBrowserRetrieveTimeout attribute, 204, 387 imqReconnectAttempts attribute, 200, 383 imqReconnectEnabled attribute, 200, 382 imqReconnectInterval attribute, 200, 383 imqSetJMSXAppID attribute, 388 imqSetJMSXConsumerTXID attribute, 388 imqSetJMSXProducerTXID attribute, 388 imqSetJMSXRcvTimestamp attribute, 388 imqSetJMSXUserID attribute, 388 imqSSLIsHostTrusted attribute, 383 imqSSLIsHostTrusted attribute, 162 imqsvcadmin command about, 38 options, 335 reference, 334 subcommands, 334 imqusermgr command, 143-147 about, 38 displaying version, 144 general options, 332 general options (table), 144 options, 331 passwords, 144
469
Index
imqusermgr command (Continued) reference, 331 subcommands, 331 subcommands (table), 143 usage help, 144 user names, 144 imqusermgr utility, 138 install.properties file, 80 instance configuration files, See configuration files instance directory, removing, 76 isLocalOnly destination property, 377, 417
J
J2EE connector architecture (JCA), 391 JAAS-based authentication, 150-155 configuration file, 151 configuration file for, 152 JAAS API, 150 JAAS client, 150 login module, 150 setting up, 153-155 Java ES Monitoring Framework (JESMF), 259-260 Java Management Extensions, See JMX java.naming.factory.initial attribute, 196, 197 java.naming.provider.url attribute, 196, 197 java.naming.security.authentication attribute, 197 java.naming.security.credentials attribute, 196 java.naming.security.principal attribute, 196 Java runtime for Windows service, 75 specifying path to, 316, 321, 328, 335 Java Virtual Machine, See JVM javahome option, 75 JCA (J2EE connector architecture), 391 JDBC-based persistence about, 131 JDBC driver, 350 properties, 131-133 setting up, 133-135 JES Monitoring Framework (JESMF), 413-418 brokers, 414-415 common attributes, 413-414 connection services, 415-416
470
JES Monitoring Framework (JESMF) (Continued) destinations, 416-417 Message Queue product, 414 persistent data store, 417 Port Mapper, 415 user repository, 418 JESMF, See JES Monitoring Framework jms connection service, 96 JMSDeliveryMode message header field, 204 JMSExpiration message header field, 204 JMSPriority message header field, 204 JMSXAppID message property, 204 JMSXConsumerTXID message property, 204 JMSXProducerTXID message property, 204 JMSXRcvTimestamp message property, 204 JMSXUserID message property, 204 JMX administrative support for, 447-456 commands for managing, 327 configuration properties, 366 JMX-based administration, 40, 259 JMX connectors, introduced, 448 JMX imqcmd subcommands, 327 JNDI lookup, 55 lookup name, 205, 206 object store, 38, 195 object store attributes, 196-197, 206 jrehome option, 75 JVM metrics See JVM metrics performance effect of, 275 tuning for performance, 278-279 JVM metrics metrics quantities, 404 using broker log files, 253 using imqcmd metrics, 256 using message-based monitoring, 261
K
key pairs generating, 163, 434
Index
key pairs (Continued) regenerating, 164 key store, 164, 434 Key Tool, 140 keystore, file, 164 keytool command command syntax, 433 using, 433
logging, See Logger loopback address, 183
M
ManagedConnectionFactory JavaBean, 394 master broker management, 186-187 specifying, 177 maxBytesPerMsg destination property, 376, 416 maxNumActiveConsumers destination property, 377, 417 maxNumBackupConsumers destination property, 377, 417 maxNumMsgs destination property, 375, 416 maxNumProducers destination property, 377, 417 maxTotalMsgBytes destination property, 376, 417 MBean server, introduced, 448 MBeans server See MBean server MDBs, See message-driven beans memory management, for broker, 122 message-driven beans Resource Adapter configuration for, 391, 397 message expiration, clock synchronization and, 69 message flow controls broker, 122 connection factory attributes, 203 connection flow limits, 284 connection flow metering, 282 consumer flow limits, 283-284 tuning for performance, 282-284 message header overrides, 204-205 message service architecture, 277 message service performance, 274-278 messages body type and performance, 274 broker limits on, 92, 122, 340 destination limits on, 343, 376 flow control See message flow controls fragmentation, 129
471
L
LDAP repository, 138 LDAP server as user repository, 147-149 object store attributes, 196 limit behaviors broker, 122 physical destinations, 122, 376 limitBehavior destination property, 375, 376, 417 load-balanced queue delivery, See queue load-balanced delivery localDeliveryPreferred destination property, 378, 417 log files changing default location, 250 changing default name, 251 dead message logging, 253-254 default location, 422, 423, 424 names, 250 reporting metrics, 253 rollover criteria, 249, 252, 358 rollover frequency, 251 setting properties, 251 Logger about, 248 changing configuration, 251 dead message format, 254 levels, 249, 317, 357 message format, 249 metrics information, 360 output channels, 248, 249, 251-252 redirecting log messages, 252 rollover criteria, 252 setting properties, 251 writing to console, 249, 318, 358
Index
messages (Continued) metrics messages See metrics messages pausing flow of, 112 persistence of, 127 purging from a physical destination, 325 reclamation of expired, 122, 341 size, and performance, 273-274 messageSelector ActivationSpec property, 398 metric information brokers, 93 connection services, 102 physical destinations, 117 metrics about, 245 data See metrics data messages See metrics messages topic destinations, 261 metrics data broker See broker metrics physical destination See physical destination metrics using broker log files, 253 using message-based monitoring API, 261-262 metrics messages about, 260 type, 261 metrics monitoring tools compared, 246-248 message-based monitoring API, 260-263 Message Queue Command Utility (imqcmd), 254-258 Message Queue log files, 253 monitoring, See performance monitoring monitoring, support for Java ES, 259-260 monitoring services, broker, 80, 245-246 multiple queue consumers, 284
nsswitch.conf file (Linux), 183
O
object stores, 195-198 file-system, 197-198 file-system store attributes, 197-198 initial context, 196 LDAP server, 195-197 LDAP server attributes, 196 location, 196 locations, 422, 423, 424 security, 196 operating system performance effect of, 275 tuning Solaris performance, 278 options ActivationSpec property, 400 options managed connection factory attribute, 396 Oracle, 135 overrides for message header, 204-205 on command line, 77
P
password file broker configuration properties, 139, 353 command line option, 316 location, 171, 422, 423, 425 permissions, 170 using, 170-171 password managed connection factory attribute, 395 password Resource Adapter attribute, 393 passwords administrator, 146, 171 default, 385 encoding of, 351 format, 144 JDBC, 171 LDAP, 171 password file See password file SSL key store, 171
N
NORMAL service type, 96
472
Index
passwords (Continued) SSL keystore, 164 pausing brokers, 91, 322 connection services, 99, 323 physical destinations, 112, 325 performance about, 265-268 baseline patterns, 267-268 benchmarks, 266-267 bottlenecks, 269 factors affecting See performance factors indicators, 266 measures of, 266 monitoring See performance monitoring optimizing See performance tuning reliability tradeoffs, 270 troubleshooting, 287 tuning See performance tuning performance factors acknowledgment mode, 272 broker limit behaviors, 277 connections, 275-276 data store, 277-278 delivery mode, 271 durable subscriptions, 273 file synchronization, 347 hardware, 275 JVM, 275 message body type, 274 message flow control, 282 message service architecture, 277 message size, 273-274 operating system, 275 selectors, 273 transactions, 271-272 transport protocols, 276 performance monitoring JES Monitoring Framework (JESMF) See Java ES Monitoring Framework
performance monitoring (Continued) metrics data See metrics data tools See metrics monitoring tools performance tuning broker adjustments, 281-282 client runtime adjustments, 282-284 process overview, 265-266 system adjustments, 278-281 permissions access control file, 140 admin service, 140 computing, 158-159 data store, 128 embedded database, 133 password file, 170 user repository, 143, 331 persistence about, 127 data store See data store file-based data store, 128-129 JDBC-based See JDBC-based persistence options (figure), 127 properties, 346-347 security for, 130, 135 persistence services, broker, 79, 127-128 physical destinations auto-created See auto-created destinations batching messages for delivery, 344, 377 commands for managing, 324-326 compacting, 119 compacting file-based data store, 325 creating, 109, 325 destroying, 112, 325 disk utilization, 118-120 displaying metrics, 326 getting information about, 326 limit behaviors, 376 listing, 114, 326 managing, 107-121
473
Index
physical destinations (Continued) metrics See destination metrics naming conventions, 109 pausing, 112, 325 properties of, 375-379 purging, 113-114 purging messages from, 325 querying, 115 restricted scope in cluster, 344, 377 resuming, 113, 325 temporary, 115 types, 324 updating attributes, 325 updating properties, 114 using dead message queue, 120 viewing information about, 114-118 viewing metric information, 117 Port Mapper about, 97 port assignment for, 314 precedence (of configuration properties), 81 producers destination limits on, 343, 377 production environment administration tasks, 36-37 maintaining, 37 setting up, 36-37 properties auto-create, 342-345 broker instance configuration, 81 broker monitoring service, 357-361 cluster configuration, 361-363 connection services, 338-340 httpjms connection service, 442 httpsjms connection service, 442 JDBC-related, 350-351 Logger, 357-361 persistence, 346-347 physical destinations See physical destinations, properties of routine services, 340-342 security, 351-354 syntax, 82
474
protocol types HTTP, 97 HTTPS, 97 TCP, 96, 97 TLS, 96, 97 protocols, See transport protocols purging physical destinations, 113-114
Q
querying broker clusters, 180-181 brokers, 92 connection services, 101 physical destinations, 115 queue load-balanced delivery auto-created queue, 344 auto-created queues, 344 behavior, 284 properties, 377 tuning for performance, 285 queues, auto-created, 342 quiescing brokers, 90, 322
R
reconnectAttempts managed connection factory attribute, 395 reconnectAttempts Resource Adapter attribute, 393 reconnectEnabled managed connection factory attribute, 395 reconnectEnabled Resource Adapter attribute, 393 reconnectInterval managed connection factory attribute, 395 reconnectInterval Resource Adapter attribute, 393 reconnection, automatic, See automatic reconnection reliable delivery and flow control, 203 performance tradeoffs, 270 reloadXMLSchemaOnFaulure destination property, 379 Resource Adapter properties, 391
Index
Resource Adapter (Continued) reconnection, 393, 395 ResourceAdapter JavaBean, 392 RESTART property, 72, 73 restarting brokers, 90, 322 resuming brokers, 91, 322 connection services, 100, 323 physical destinations, 113, 325 routine services, properties, 340-342 routing services, broker, 79, 121
S
Secure Socket Layer standard, See SSL security authentication See authentication authorization See authorization encryption See encryption manager See security manager object store, for, 196 security manager about, 137 properties, 351-354 security services, broker, 79, 137-140 selectors about, 273 performance effect of, 273 self-signed certificates, 161-167, 433 sendUndeliverableMsgsToDMQ ActivationSpec property, 399 server, MBean, See MBean server service (Windows) Java runtime for, 75 reconfiguring, 74 removing broker, 75-76 running broker as, 73-76 startup parameters for, 75 troubleshooting startup, 76
service types ADMIN, 96 NORMAL, 96 shutting down brokers, 89, 321 as Windows service, 75-76 Simple Network Time Protocol (SNTP), 69 SSL about, 140 broker clusters, 184 connection services See SSL-based connection services SSL, enabling, 165 SSL encryption and, 161 SSL-based connection services, implementing, 161 SSL-based connection services, starting up, 165 ssladmin connection service, 97, 161 ssljms connection service, 96, 161 starting clients, 77 SSL-based connection services, 165 startup parameters for broker Windows service, 75 subscriptionDurability activation specification attribute, 398 subscriptionDurability ActivationSpec property, 398 subscriptionName activation specification attribute, 398 subscriptionName ActivationSpec property, 398 Sun Cluster, configuration for, 347 synchronizing clocks, 69-70 memory to disk, 129 syntax for all commands, 313-314 syslog, 249, 252 system clock synchronization, 69-70
T
TCP protocol type, 96, 97 temporary physical destinations, 115 thread pool management about, 98 dedicated threads, 98 shared threads, 98
475
Index
time synchronization service, 69 time-to-live, See message expiration TLS protocol type, 96, 97 tools, administration, See administration tools topics, auto-created, 342 transactions commands for managing, 327 displaying information about, 327 managing, 124-126 performance effect of, 271-272 transport protocols performance effect of, 276 protocol types See protocol types relative speeds, 276 tuning for performance, 279-281 troubleshooting, 287 Windows service startup, 76 tunnel servlet connection, 446 tutorial, 41
user repository (Continued) flat-file, 141-147 initial entries, 142 LDAP, 147-149 location, 422, 423, 424 platform dependence, 331 populating, 144-145 user groups, 141-143 userName managed connection factory attribute, 395 userName Resource Adapter attribute, 393 useSharedSubscriptionInClusteredContainer ActivationSpec property, 401 useSharedSubscriptionInClusteredContainer managed connection factory property, 397
V
validateXMLSchemaEnabled destination property, 378 version, displaying, 87, 144, 321
U
ulimit command, 70 unquiescing brokers, 90, 322 updating brokers, 91-92 connection services, 100, 323 usage help, 88, 144, 321 useDMQ destination property, 378, 417 useDMQ property, 120 user data, 138 user groups default, 140 deleting assignment, 141 predefined, 142 user names, 385 default, 143 format, 144 user repository about, 138 activating and deactivating users, 146 changing passwords, 145-146 deleting users, 145
476
W
W32Time service, 70 wildcards destination names, 109 publishers, 111 subscribers, 111 Windows service, See service (Windows) write operations (for file based store), 129
X
XMLSchemaURIList destination property, 378 xntpd daemon, 69

Sun GlassFish Message Queue 4.4 Administration Guide

Uploaded by

Copyright:

Available Formats

Sun GlassFish Message Queue 4.4 Administration Guide

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Sun GlassFish Message Queue 4.4 Administration Guide

Uploaded by

Copyright:

Available Formats

Sun GlassFish Message Queue 4.

Copyright 2009Sun Microsystems, Inc.

4150 Network Circle, Santa Clara, CA 95054 U.S.A.

Introduction to Message Queue Administration ........................................................................... 33

Administrative Tasks ........................................................................................................................... 67

Configuring Persistence Services ...................................................................................................127 Introduction to Persistence Services ............................................................................................... 127

Sun GlassFish Message Queue 4.4 Administration Guide June 2010

Sun GlassFish Message Queue 4.4 Administration Guide June 2010

Sun GlassFish Message Queue 4.4 Administration Guide June 2010

Index ................................................................................................................................................... 461

Sun GlassFish Message Queue 4.4 Administration Guide June 2010

TABLE 177 TABLE 178 TABLE 179

Sun GlassFish Message Queue 4.4 Administration Guide June 2010

TABLE A3 TABLE B1 TABLE B2 TABLE C1 TABLE C2

TABLE D1 TABLE E1 TABLE E2

Sun GlassFish Message Queue 4.4 Administration Guide June 2010

Sun GlassFish Message Queue 4.4 Administration Guide June 2010

Who Should Use This Book

Before You Read This Book

How This Book Is Organized

Sun GlassFish Message Queue 4.4 Administration Guide June 2010

Appendix E, Frequently Used Command Utility Commands

Contains optional arguments ls [-l] and command options.

The -l option is not required.

Sun GlassFish Message Queue 4.4 Administration Guide June 2010

Shell Prompt Conventions

Shell Prompt Conventions

machine-name% machine-name# $ # C:\>

Directory Variable Conventions

Directory Variable Conventions

Sun GlassFish Message Queue 4.4 Administration Guide June 2010

Message Queue Documentation Set

Message Queue Documentation Set

Sun GlassFish Message Queue 4.4 Developers Guide for C Clients

Java Message Service (JMS) Specification

IPS image Solaris SVR4 packages Linux RPM packages

IMQ_HOME/javadoc/index.html1 /usr/share/javadoc/imq/index.html /opt/sun/mq/javadoc/index.html

IMQ_HOME is the Message Queue home directory.

Example Client Applications

Example Java Client Applications

IPS image Solaris SVR4 packages Linux RPM packages

IMQ_HOME/examples1 /usr/demo/imq /opt/sun/mq/examples

IMQ_HOME is the Message Queue home directory.

Example C Client Programs

IMQ_HOME is the Message Queue home directory.

Sun GlassFish Message Queue 4.4 Administration Guide June 2010

Solaris SVR4 packages Linux RPM packages

Example JMX Client Programs

IPS image Solaris SVR4 packages Linux RPM packages

IMQ_HOME/examples/jmx1 /opt/SUNWimq/demo/imq/jmx /opt/sun/mq/examples/jmx

IMQ_HOME is the Message Queue home directory.

Third-Party Web Site References

Searching Sun Product Documentation

For example, to search for broker, type the following:

Documentation, Support, and Training

Documentation (http://www.sun.com/documentation/) Support (http://www.sun.com/support/) Training (http://www.sun.com/training/)

Sun Welcomes Your Comments

Sun GlassFish Message Queue 4.4 Administration Guide June 2010

Introduction to Message Queue Administration

Chapter 1, Administrative Tasks and Tools Chapter 2, Quick-Start Tutorial