Sun Java System Message Queue

4.1 Administration Guide

Sun Microsystems, Inc.

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

Part No: 819–7755

September 2007
Copyright 2007 Sun Microsystems, Inc. 4150 Network Circle, Santa Clara, CA 95054 U.S.A. All rights reserved.

Sun Microsystems, Inc. has intellectual property rights relating to technology embodied in the product that is described in this document. In particular, and without
limitation, these intellectual property rights may include one or more U.S. patents or pending patent applications in the U.S. and in other countries.
U.S. Government Rights – Commercial software. Government users are subject to the Sun Microsystems, Inc. standard license agreement and applicable provisions
of the FAR and its supplements.
This distribution may include materials developed by third parties.
Parts of the product may be derived from Berkeley BSD systems, licensed from the University of California. UNIX is a registered trademark in the U.S. and other
countries, exclusively licensed through X/Open Company, Ltd.
Sun, Sun Microsystems, the Sun logo, the Solaris logo, the Java Coffee Cup logo, docs.sun.com, Java, and Solaris are trademarks or registered trademarks of Sun
Microsystems, Inc. in the U.S. and other countries. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC
International, Inc. in the U.S. and other countries. Products bearing SPARC trademarks are based upon an architecture developed by Sun Microsystems, Inc.
The OPEN LOOK and SunTM Graphical User Interface was developed by Sun Microsystems, Inc. for its users and licensees. Sun acknowledges the pioneering efforts
of Xerox in researching and developing the concept of visual or graphical user interfaces for the computer industry. Sun holds a non-exclusive license from Xerox to
the Xerox Graphical User Interface, which license also covers Sun's licensees who implement OPEN LOOK GUIs and otherwise comply with Sun's written license
agreements.
Products covered by and information contained in this publication are controlled by U.S. Export Control laws and may be subject to the export or import laws in
other countries. Nuclear, missile, chemical or biological weapons or nuclear maritime end uses or end users, whether direct or indirect, are strictly prohibited. Export
or reexport to countries subject to U.S. embargo or to entities identified on U.S. export exclusion lists, including, but not limited to, the denied persons and specially
designated nationals lists is strictly prohibited.
DOCUMENTATION IS PROVIDED “AS IS” AND ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANY
IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE DISCLAIMED, EXCEPT TO
THE EXTENT THAT SUCH DISCLAIMERS ARE HELD TO BE LEGALLY INVALID.

Copyright 2007 Sun Microsystems, Inc. 4150 Network Circle, Santa Clara, CA 95054 U.S.A. Tous droits réservés.
Sun Microsystems, Inc. détient les droits de propriété intellectuelle relatifs à la technologie incorporée dans le produit qui est décrit dans ce document. En particulier,
et ce sans limitation, ces droits de propriété intellectuelle peuvent inclure un ou plusieurs brevets américains ou des applications de brevet en attente aux Etats-Unis
et dans d'autres pays.
Cette distribution peut comprendre des composants développés par des tierces personnes.
Certaines composants de ce produit peuvent être dérivées du logiciel Berkeley BSD, licenciés par l'Université de Californie. UNIX est une marque déposée aux
Etats-Unis et dans d'autres pays; elle est licenciée exclusivement par X/Open Company, Ltd.
Sun, Sun Microsystems, le logo Sun, le logo Solaris, le logo Java Coffee Cup, docs.sun.com, Java et Solaris sont des marques de fabrique ou des marques déposées de
Sun Microsystems, Inc. aux Etats-Unis et dans d'autres pays. Toutes les marques SPARC sont utilisées sous licence et sont des marques de fabrique ou des marques
déposées de SPARC International, Inc. aux Etats-Unis et dans d'autres pays. Les produits portant les marques SPARC sont basés sur une architecture développée par
Sun Microsystems, Inc.
L'interface d'utilisation graphique OPEN LOOK et Sun a été développée par Sun Microsystems, Inc. pour ses utilisateurs et licenciés. Sun reconnaît les efforts de
pionniers de Xerox pour la recherche et le développement du concept des interfaces d'utilisation visuelle ou graphique pour l'industrie de l'informatique. Sun détient
une licence non exclusive de Xerox sur l'interface d'utilisation graphique Xerox, cette licence couvrant également les licenciés de Sun qui mettent en place l'interface
d'utilisation graphique OPEN LOOK et qui, en outre, se conforment aux licences écrites de Sun.
Les produits qui font l'objet de cette publication et les informations qu'il contient sont régis par la legislation américaine en matière de contrôle des exportations et
peuvent être soumis au droit d'autres pays dans le domaine des exportations et importations. Les utilisations finales, ou utilisateurs finaux, pour des armes nucléaires,
des missiles, des armes chimiques ou biologiques ou pour le nucléaire maritime, directement ou indirectement, sont strictement interdites. Les exportations ou
réexportations vers des pays sous embargo des Etats-Unis, ou vers des entités figurant sur les listes d'exclusion d'exportation américaines, y compris, mais de manière
non exclusive, la liste de personnes qui font objet d'un ordre de ne pas participer, d'une façon directe ou indirecte, aux exportations des produits ou des services qui
sont régis par la legislation américaine en matière de contrôle des exportations et la liste de ressortissants spécifiquement designés, sont rigoureusement interdites.
LA DOCUMENTATION EST FOURNIE "EN L'ETAT" ET TOUTES AUTRES CONDITIONS, DECLARATIONS ET GARANTIES EXPRESSES OU TACITES
SONT FORMELLEMENT EXCLUES, DANS LA MESURE AUTORISEE PAR LA LOI APPLICABLE, Y COMPRIS NOTAMMENT TOUTE GARANTIE
IMPLICITE RELATIVE A LA QUALITE MARCHANDE, A L'APTITUDE A UNE UTILISATION PARTICULIERE OU A L'ABSENCE DE CONTREFACON.

070903@18135
 Contents

Preface ...................................................................................................................................................21

Part I Introduction to Message Queue Administration ........................................................................... 31

1 Administrative Tasks and Tools ......................................................................................................... 33

Administrative Tasks .......................................................................................................................... 33
Administration in a Development Environment ..................................................................... 33
Administration in a Production Environment ......................................................................... 34
Administration Tools .......................................................................................................................... 36
Command Line Utilities .............................................................................................................. 36
Administration Console .............................................................................................................. 36

2 Quick-Start Tutorial .............................................................................................................................39

Starting the Administration Console ................................................................................................ 40
Administration Console Online Help ............................................................................................... 42
Working With Brokers ....................................................................................................................... 43
Starting a Broker .......................................................................................................................... 43
Adding a Broker to the Administration Console ..................................................................... 43
▼ To Add a Broker to the Administration Console .............................................................. 43
Connecting to a Broker ............................................................................................................... 45
▼ To Connect to a Broker ........................................................................................................ 45
Viewing Connection Services ..................................................................................................... 46
▼ To View Available Connection Services ............................................................................ 46
Working With Physical Destinations ............................................................................................... 48
Creating a Physical Destination ................................................................................................. 48
▼ To Add a Physical Destination to a Broker ........................................................................ 48
Viewing Physical Destination Properties .................................................................................. 49

3
Contents

▼ To View or Modify the Properties of a Physical Destination .......................................... 50

Purging Messages From a Physical Destination ....................................................................... 52
▼ To Purge Messages From a Physical Destination ............................................................. 52
Deleting a Physical Destination ................................................................................................. 52
▼ To Delete a Physical Destination ........................................................................................ 53
Working With Object Stores .............................................................................................................. 53
Adding an Object Store ............................................................................................................... 53
▼ To Add an Object Store to the Administration Console .................................................. 54
Connecting to an Object Store ................................................................................................... 55
▼ To Connect to an Object Store ............................................................................................ 56
Working With Administered Objects ............................................................................................... 56
Adding a Connection Factory .................................................................................................... 56
▼ To Add a Connection Factory to an Object Store ............................................................. 56
Adding a Destination ................................................................................................................... 58
▼ To Add a Destination to an Object Store ........................................................................... 58
Viewing Administered Object Properties ................................................................................. 60
▼ To View or Modify the Properties of an Administered Object ....................................... 60
Deleting an Administered Object .............................................................................................. 61
▼ To Delete an Administered Object ..................................................................................... 61
Running the Sample Application ...................................................................................................... 61
▼ To Run the Sample Application ................................................................................................. 62

Part II Administrative Tasks ........................................................................................................................... 65

3 Starting Brokers and Clients .............................................................................................................. 67

Preparing System Resources .............................................................................................................. 67
Synchronizing System Clocks .................................................................................................... 67
Setting the File Descriptor Limit ................................................................................................ 68
Starting Brokers ................................................................................................................................... 68
Starting Brokers Interactively ..................................................................................................... 68
Starting Brokers Automatically .................................................................................................. 69
Removing Brokers ............................................................................................................................... 72
Removing a Broker on Solaris or Linux .................................................................................... 72
Removing a Windows Broker Service ....................................................................................... 73
Starting Clients .................................................................................................................................... 73

4 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Contents

4 Broker Configuration ..........................................................................................................................75

Broker Services .................................................................................................................................... 75
Connection Services .................................................................................................................... 76
Routing Services ........................................................................................................................... 78
Persistence Services ...................................................................................................................... 80
Security Services ........................................................................................................................... 83
Monitoring Services ..................................................................................................................... 86
Setting Broker Properties ................................................................................................................... 89
Configuration Files ...................................................................................................................... 89
Setting Configuration Options from the Command Line ...................................................... 91
Configuring a Persistent Data Store .................................................................................................. 92
Configuring a File-Based Store ................................................................................................... 92
Configuring a JDBC-Based Store ............................................................................................... 92
▼ To Configure a JDBC-Based Data Store ............................................................................ 93
Displaying Information About the Persistent Store ................................................................ 94
Securing Persistent Data ............................................................................................................. 94

5 Broker Management ...........................................................................................................................97

Command Utility Preliminaries ........................................................................................................ 97
Using the Command Utility ............................................................................................................... 98
Specifying the User Name and Password .................................................................................. 98
Specifying the Broker Name and Port ....................................................................................... 99
Displaying the Product Version ................................................................................................. 99
Displaying Help ............................................................................................................................ 99
Examples ....................................................................................................................................... 99
Managing Brokers ............................................................................................................................. 100
Shutting Down and Restarting a Broker ................................................................................. 100
Quiescing a Broker ..................................................................................................................... 101
Pausing and Resuming a Broker ............................................................................................... 102
Updating Broker Properties ...................................................................................................... 103
Viewing Broker Information .................................................................................................... 104
Managing Connection Services ....................................................................................................... 106
Pausing and Resuming a Connection Service ........................................................................ 106
Updating Connection Service Properties ............................................................................... 107
Viewing Connection Service Information .............................................................................. 107

5
Contents

Managing Connections .................................................................................................................... 109

Managing Durable Subscriptions .................................................................................................... 111
Managing Transactions .................................................................................................................... 112

6 Physical Destinations ........................................................................................................................115

Command Utility Subcommands for Physical Destination Management ................................. 116
Creating and Destroying Physical Destinations ............................................................................ 116
Pausing and Resuming a Physical Destination .............................................................................. 117
Purging a Physical Destination ........................................................................................................ 119
Updating Physical Destination Properties ..................................................................................... 119
Viewing Physical Destination Information ................................................................................... 120
Managing Physical Destination Disk Utilization .......................................................................... 123
Dead Message Queue ........................................................................................................................ 124
Managing the Dead Message Queue ........................................................................................ 124
Enabling Dead Message Logging ............................................................................................. 125

7 Administered Objects .......................................................................................................................127

Object Stores ...................................................................................................................................... 127
LDAP Server Object Stores ....................................................................................................... 127
File-System Object Stores ......................................................................................................... 129
Administered Object Attributes ...................................................................................................... 130
Connection Factory Attributes ................................................................................................. 130
Destination Attributes ............................................................................................................... 137
Using the Object Manager Utility .................................................................................................... 137
Adding Administered Objects .................................................................................................. 138
Deleting Administered Objects ................................................................................................ 141
Listing Administered Objects ................................................................................................... 141
Viewing Administered Object Information ........................................................................... 142
Modifying Administered Object Attributes ............................................................................ 142
Using Command Files ............................................................................................................... 143

8 Broker Clusters ...................................................................................................................................147

Types of Cluster ................................................................................................................................. 147
Conventional Clusters ............................................................................................................... 147

6 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Contents

High-Availability Clusters ........................................................................................................ 148

Configuring Clusters ......................................................................................................................... 149
Setting the Cluster Configuration ............................................................................................ 149
Cluster Configuration Properties ............................................................................................ 150
Displaying the Cluster Configuration ..................................................................................... 152
Managing Clusters ............................................................................................................................ 154
Managing Conventional Clusters ............................................................................................ 154
Managing High-Availability Clusters ...................................................................................... 159

9 Security ............................................................................................................................................... 165

User Authentication .......................................................................................................................... 165
Using a Flat-File User Repository ............................................................................................ 166
Using an LDAP User Repository .............................................................................................. 172
▼ To Set Up an Administrative User .................................................................................... 173
Using JAAS-Based Authentication .......................................................................................... 174
User Authorization ............................................................................................................................ 180
Access Control File Syntax ........................................................................................................ 180
Application of Authorization Rules ......................................................................................... 182
Authorization Rules for Connection Services ........................................................................ 183
Authorization Rules for Physical Destinations ...................................................................... 184
Message Encryption .......................................................................................................................... 185
Using Self-Signed Certificates .................................................................................................. 185
▼ To Set Up an SSL-Based Connection Service Using Self-Signed Certificates ............. 186
Using Signed Certificates .......................................................................................................... 191
▼ To Use a Signed Certificate ................................................................................................ 191
Password Files .................................................................................................................................... 193
Security Concerns ...................................................................................................................... 194
Password File Contents ............................................................................................................. 194
Connecting Through a Firewall ....................................................................................................... 195
▼ To Enable Broker Connections Through a Firewall .............................................................. 196

10 Monitoring Broker Operations ........................................................................................................197

Introduction to Monitoring Tools .................................................................................................. 197
Configuring and Using Broker Logging ......................................................................................... 199
Log Message Format .................................................................................................................. 199

7
Contents

Default Logging Configuration ................................................................................................ 200

Changing the Logging Configuration ..................................................................................... 201
▼ To Change the Logger Configuration for a Broker ........................................................ 201
Displaying Metrics Interactively ...................................................................................................... 204
imqcmd metrics ......................................................................................................................... 205
Using the metrics Subcommand to Display Metrics Data .................................................... 206
▼ To Use the metrics Subcommand ..................................................................................... 206
Metrics Outputs: imqcmd metrics ........................................................................................... 207
imqcmd query ............................................................................................................................ 208
Using the JES Monitoring Framework ........................................................................................... 209
Writing an Application to Monitor Brokers .................................................................................. 210
Setting Up Message-Based Monitoring ................................................................................... 210
▼ To Set Up Message-based Monitoring ............................................................................. 210
Security and Access Considerations ........................................................................................ 211
Metrics Outputs: Metrics Messages ......................................................................................... 212

11 Analyzing and Tuning a Message Service ..................................................................................... 213

About Performance ........................................................................................................................... 213
The Performance Tuning Process ............................................................................................ 213
Aspects of Performance ............................................................................................................. 214
Benchmarks ................................................................................................................................ 214
Baseline Use Patterns ................................................................................................................. 215
Factors Affecting Performance ........................................................................................................ 216
▼ Message Delivery Steps .............................................................................................................. 217
Application Design Factors Affecting Performance .............................................................. 218
Message Service Factors Affecting Performance .................................................................... 222
Adjusting Configuration To Improve Performance ..................................................................... 226
System Adjustments .................................................................................................................. 226
Broker Adjustments ................................................................................................................... 229
Client Runtime Message Flow Adjustments ........................................................................... 231

12 Troubleshooting ............................................................................................................................... 235

A Client Cannot Establish a Connection ........................................................................................ 235
Connection Throughput Is Too Slow ............................................................................................. 239
A Client Cannot Create a Message Producer ................................................................................. 241

8 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Contents

Message Production Is Delayed or Slowed ..................................................................................... 242

Messages Are Backlogged ................................................................................................................. 244
Broker Throughput Is Sporadic ....................................................................................................... 248
Messages Are Not Reaching Consumers ........................................................................................ 249
Dead Message Queue Contains Messages ...................................................................................... 252

Part III Reference ............................................................................................................................................259

13 Command Line Reference ................................................................................................................261

Command Line Syntax ..................................................................................................................... 261
Broker Utility ..................................................................................................................................... 262
Command Utility .............................................................................................................................. 266
Broker Management .................................................................................................................. 268
Connection Service Management ............................................................................................ 270
Connection Management ......................................................................................................... 271
Physical Destination Management .......................................................................................... 271
Durable Subscription Management ......................................................................................... 273
Transaction Management ......................................................................................................... 273
JMX Management ...................................................................................................................... 274
General Command Utility Options ......................................................................................... 274
Object Manager Utility ..................................................................................................................... 275
Database Manager Utility ................................................................................................................. 277
User Manager Utility ......................................................................................................................... 278
Service Administrator Utility ........................................................................................................... 280
Key Tool Utility ................................................................................................................................. 281

14 Broker Properties Reference ...........................................................................................................283

Connection Properties ...................................................................................................................... 283
Routing Properties ............................................................................................................................ 286
Persistence Properties ....................................................................................................................... 290
File-Based Persistence Properties ............................................................................................ 291
JDBC-Based Persistence Properties ......................................................................................... 292
Security Properties ............................................................................................................................ 293
Monitoring Properties ...................................................................................................................... 298

9
Contents

Cluster Configuration Properties .................................................................................................... 302

JMX Properties .................................................................................................................................. 304
Alphabetical List of Broker Properties ............................................................................................ 307

15 Physical Destination Property Reference ......................................................................................313

Physical Destination Properties ....................................................................................................... 313

16 Administered Object Attribute Reference ....................................................................................317

Connection Factory Attributes ........................................................................................................ 317
Connection Handling ................................................................................................................ 317
Client Identification ................................................................................................................... 321
Reliability and Flow Control ..................................................................................................... 321
Queue Browser and Server Sessions ........................................................................................ 323
Standard Message Properties .................................................................................................... 324
Message Header Overrides ....................................................................................................... 324
Destination Attributes ...................................................................................................................... 325

17 JMS Resource Adapter Property Reference .................................................................................. 327

ResourceAdapter JavaBean .............................................................................................................. 327
ManagedConnectionFactory JavaBean .......................................................................................... 330
ActivationSpec JavaBean .................................................................................................................. 331

18 Metrics Reference ..............................................................................................................................335

JVM Metrics ....................................................................................................................................... 335
Brokerwide Metrics ........................................................................................................................... 336
Connection Service Metrics ............................................................................................................. 338
Physical Destination Metrics ........................................................................................................... 339

19 JES Monitoring Framework Reference ...........................................................................................345

Common Attributes .......................................................................................................................... 345
Message Queue Product Information ............................................................................................. 346
Broker Information ........................................................................................................................... 346
Port Mapper Information ................................................................................................................. 347
Connection Service Information ..................................................................................................... 347

10 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Contents

Destination Information .................................................................................................................. 349

Persistent Store Information ............................................................................................................ 350
User Repository Information ........................................................................................................... 350

Part IV Appendixes .........................................................................................................................................351

A Platform-Specific Locations of Message Queue Data ................................................................. 353

Solaris .................................................................................................................................................. 353
Linux ................................................................................................................................................... 354
Windows ............................................................................................................................................ 355

B Stability of Message Queue Interfaces .......................................................................................... 357

Classification Scheme ....................................................................................................................... 357
Interface Stability ............................................................................................................................... 358

C HTTP/HTTPS Support ........................................................................................................................361

HTTP/HTTPS Support Architecture ............................................................................................. 361
Enabling HTTP/HTTPS Support .................................................................................................... 362
Step 1 (HTTPS Only): Generating a Self-Signed Certificate for the Tunnel Servlet .......... 363
Step 2 (HTTPS Only): Specifying the Key Store Location and Password ............................ 365
▼ To Specify the Location and Password of the Certificate Key Store ............................. 365
Step 3 (HTTPS Only): Validating and Installing the Server’s Self-Signed Certificate ........ 366
▼ To Validate and Install the Server’s Self-Signed Certificate ........................................... 366
Step 4 (HTTP and HTTPS): Deploying the Tunnel Servlet .................................................. 370
▼ To Deploy the HTTP or HTTPS Tunnel Servlet ............................................................. 370
▼ Modifying the Application Server’s Security Policy File ................................................ 371
Step 5 (HTTP and HTTPS): Configuring the Connection Service ...................................... 372
▼ To Activate the httpjms or httpsjms Connection Service ........................................... 372
Step 6 (HTTP and HTTPS): Configuring a Connection ....................................................... 373
Troubleshooting ................................................................................................................................ 377
Server or Broker Failure ............................................................................................................ 377
Client Failure to Connect Through the Tunnel Servlet ......................................................... 377
▼ If a Client Cannot Connect ................................................................................................ 377

11
Contents

D JMX Support .......................................................................................................................................379

Broker Properties for JMX Support ................................................................................................. 379
SSL Support for JMX Clients ............................................................................................................ 380
▼ Configuring JMX for SSL Operation ....................................................................................... 380

E Frequently Used Command Utility Commands ............................................................................ 383

Syntax .................................................................................................................................................. 383
Broker and Cluster Management .................................................................................................... 383
Broker Configuration Properties (-o option) ......................................................................... 384
Service and Connection Management ............................................................................................ 384
Durable Subscriber Management .................................................................................................... 385
Transaction Management ................................................................................................................ 385
Destination Management ................................................................................................................. 385
Destination Configuration Properties (-o option) ................................................................ 385
Metrics ................................................................................................................................................ 386

Index ................................................................................................................................................... 387

12 Sun Java System Message Queue 4.1 Administration Guide • September 2007
Figures

FIGURE 1–1 Local and Remote Administration Utilities ........................................................... 37

FIGURE 2–1 Administration Console Window ........................................................................... 41
FIGURE 2–2 Administration Console Help Window ................................................................. 42
FIGURE 2–3 Add Broker Dialog Box ............................................................................................. 44
FIGURE 2–4 Broker Displayed in Administration Console Window ....................................... 45
FIGURE 2–5 Connect to Broker Dialog Box ................................................................................. 46
FIGURE 2–6 Viewing Connection Services .................................................................................. 47
FIGURE 2–7 Service Properties Dialog Box .................................................................................. 47
FIGURE 2–8 Add Broker Destination Dialog Box ....................................................................... 49
FIGURE 2–9 Broker Destination Properties Dialog Box ............................................................. 51
FIGURE 2–10 Durable Subscriptions Panel .................................................................................... 52
FIGURE 2–11 Add Object Store Dialog Box ................................................................................... 54
FIGURE 2–12 Object Store Displayed in Administration Console Window .............................. 55
FIGURE 2–13 Add Connection Factory Object Dialog Box ......................................................... 57
FIGURE 2–14 Add Destination Object Dialog Box ........................................................................ 59
FIGURE 2–15 Destination Object Displayed in Administration Console Window .................. 60
FIGURE 4–1 Persistent Data Storage ............................................................................................. 80
FIGURE 4–2 Security Support ........................................................................................................ 84
FIGURE 4–3 Monitoring Support .................................................................................................. 87
FIGURE 4–4 Broker Configuration Files ....................................................................................... 90
FIGURE 9–1 JAAS Elements ......................................................................................................... 175
FIGURE 9–2 How Message Queue Uses JAAS ............................................................................ 176
FIGURE 9–3 Setting Up JAAS Support ........................................................................................ 177
FIGURE 11–1 Message Delivery Through a Message Queue Service ......................................... 217
FIGURE 11–2 Transport Protocol Speeds ..................................................................................... 224
FIGURE C–1 HTTP/HTTPS Support Architecture ................................................................... 362

13
14
Tables

TABLE 4–1 Message Queue Connection Services ...................................................................... 76

TABLE 4–2 Metric Topic Destinations ........................................................................................ 88
TABLE 5–1 Connection Service Properties Updated by Command Utility ......................... 107
TABLE 6–1 Physical Destination Subcommands for the Command Utility ........................ 116
TABLE 6–2 Dead Message Queue Treatment of Physical Destination Properties ............... 125
TABLE 7–1 LDAP Object Store Attributes ................................................................................ 128
TABLE 7–2 File-system Object Store Attributes ....................................................................... 129
TABLE 8–1 Required Configuration Properties for HA Clusters .......................................... 159
TABLE 8–2 Vendor-Specific Configuration Properties for HADB Database ....................... 160
TABLE 8–3 Vendor-Specific Configuration Properties for MySQL Database ..................... 160
TABLE 9–1 Initial Entries in Flat-File User Repository ........................................................... 167
TABLE 9–2 User Manager Subcommands ................................................................................ 168
TABLE 9–3 General User Manager Options ............................................................................. 168
TABLE 9–4 Broker Properties for JAAS Support ..................................................................... 179
TABLE 9–5 Authorization Rule Elements ................................................................................. 181
TABLE 9–6 Distinguished Name Information Required for a Self-Signed Certificate ........ 186
TABLE 9–7 Commands That Use Passwords ........................................................................... 194
TABLE 9–8 Passwords in a Password File ................................................................................. 195
TABLE 9–9 Broker Configuration Properties for Static Port Addresses ............................... 195
TABLE 10–1 Benefits and Limitations of Metrics Monitoring Tools ...................................... 198
TABLE 10–2 Logging Levels ......................................................................................................... 199
TABLE 10–3 imqcmd metrics Subcommand Syntax ................................................................ 205
TABLE 10–4 imqcmd metrics Subcommand Options .............................................................. 205
TABLE 10–5 imqcmd query Subcommand Syntax .................................................................... 208
TABLE 10–6 Metrics Topic Destinations .................................................................................... 210
TABLE 11–1 Comparison of High-Reliability and High-Performance Scenarios ................. 219
TABLE 13–1 Broker Utility Options ............................................................................................ 262
TABLE 13–2 Command Utility Subcommands ......................................................................... 266

15
Tables

TABLE 13–3 Command Utility Subcommands for Broker Management .............................. 268
TABLE 13–4 Command Utility Subcommands for Connection Service Management ........ 270
TABLE 13–5 Command Utility Subcommands for Connection Service Management ........ 271
TABLE 13–6 Command Utility Subcommands for Physical Destination Management ....... 272
TABLE 13–7 Command Utility Subcommands for Durable Subscription Management ..... 273
TABLE 13–8 Command Utility Subcommands for Transaction Management ..................... 274
TABLE 13–9 Command Utility Subcommand for JMX Management .................................... 274
TABLE 13–10 General Command Utility Options ...................................................................... 274
TABLE 13–11 Object Manager Subcommands ............................................................................ 275
TABLE 13–12 Object Manager Options ........................................................................................ 276
TABLE 13–13 Database Manager Subcommands ........................................................................ 277
TABLE 13–14 Database Manager Options .................................................................................... 278
TABLE 13–15 User Manager Subcommands ................................................................................ 279
TABLE 13–16 General User Manager Options ............................................................................. 279
TABLE 13–17 Service Administrator Subcommands .................................................................. 280
TABLE 13–18 Service Administrator Options .............................................................................. 280
TABLE 14–1 Broker Connection Properties ............................................................................... 284
TABLE 14–2 Broker Routing Properties ..................................................................................... 286
TABLE 14–3 Broker Properties for Auto-Created Destinations .............................................. 287
TABLE 14–4 Global Broker Persistence Property ...................................................................... 290
TABLE 14–5 Broker Properties for File-Based Persistence ....................................................... 291
TABLE 14–6 Broker Properties for JDBC-Based Persistence ................................................... 292
TABLE 14–7 General Broker Security Properties ....................................................................... 294
TABLE 14–8 Broker Security Properties for LDAP Authentication ........................................ 296
TABLE 14–9 Broker Monitoring Properties ............................................................................... 298
TABLE 14–10 Broker Properties for Cluster Configuration ....................................................... 302
TABLE 14–11 Broker Properties for JMX Support ....................................................................... 305
TABLE 14–12 Alphabetical List of Broker Properties .................................................................. 307
TABLE 15–1 Physical Destination Properties ............................................................................. 313
TABLE 16–1 Connection Factory Attributes for Connection Handling ................................. 318
TABLE 16–2 Message Broker Addressing Schemes ................................................................... 320
TABLE 16–3 Message Broker Address Examples ....................................................................... 321
TABLE 16–4 Connection Factory Attributes for Client Identification .................................... 321
TABLE 16–5 Connection Factory Attributes for Reliability and Flow Control ...................... 322
TABLE 16–6 Connection Factory Attributes for Queue Browser and Server Sessions .......... 323
TABLE 16–7 Connection Factory Attributes for Standard Message Properties ..................... 324

16 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Tables

TABLE 16–8 Connection Factory Attributes for Message Header Overrides ......................... 325
TABLE 16–9 Destination Attributes ............................................................................................ 325
TABLE 17–1 Resource Adapter Properties ................................................................................. 328
TABLE 17–2 Managed Connection Factory Properties ............................................................. 330
TABLE 17–3 Activation Specification Properties ....................................................................... 331
TABLE 18–1 JVM Metrics ............................................................................................................. 336
TABLE 18–2 Brokerwide Metrics ................................................................................................. 336
TABLE 18–3 Connection Service Metrics ................................................................................... 338
TABLE 18–4 Physical Destination Metrics ................................................................................. 339
TABLE 19–1 JESMF Common Object Attributes ...................................................................... 345
TABLE 19–2 JESMF-Accessible Message Queue Product Attributes ...................................... 346
TABLE 19–3 JESMF-Accessible Message Queue Broker Attributes ........................................ 346
TABLE 19–4 JESMF-Accessible Message Queue Port Mapper Attributes .............................. 347
TABLE 19–5 JESMF-Accessible Message Queue Connection Service Attributes .................. 348
TABLE 19–6 JESMF-Accessible Message Queue Destination Attributes ................................ 349
TABLE 19–7 JESMF-Accessible Message Queue Persistent Store Attributes ......................... 350
TABLE 19–8 JESMF-Accessible Message Queue User Repository Attributes ........................ 350
TABLE A–1 Message Queue Data Locations on Solaris Platform ........................................... 353
TABLE A–2 Message Queue Data Locations on Linux Platform ............................................ 354
TABLE A–3 Message Queue Data Locations on Windows Platform ..................................... 356
TABLE B–1 Interface Stability Classification Scheme .............................................................. 357
TABLE B–2 Stability of Message Queue Interfaces ................................................................... 358
TABLE C–1 Distinguished Name Information Required for a Self-Signed Certificate ........ 364
TABLE C–2 Broker Configuration Properties for the httpjms and httpsjms Connection
Services ..................................................................................................................... 372
TABLE E–1 Broker Configuration Properties ( -o option) ..................................................... 384
TABLE E–2 Destination Configuration Properties (-o option) ............................................. 385

17
18
Examples

EXAMPLE 2–1 Output from Sample Application ............................................................................ 63

EXAMPLE 3–1 Displaying Broker Service Startup Options ........................................................... 72
EXAMPLE 4–1 Displaying Persistent Store Information ................................................................ 94
EXAMPLE 5–1 Broker Information Listing .................................................................................... 104
EXAMPLE 5–2 Broker Metrics Listing ............................................................................................ 105
EXAMPLE 5–3 Connection Services Listing ................................................................................... 108
EXAMPLE 5–4 Connection Service Information Listing .............................................................. 108
EXAMPLE 5–5 Connection Service Metrics Listing ...................................................................... 109
EXAMPLE 5–6 Broker Connections Listing ................................................................................... 110
EXAMPLE 5–7 Connection Information Listing ........................................................................... 111
EXAMPLE 5–8 Durable Subscription Information Listing ........................................................... 112
EXAMPLE 5–9 Broker Transactions Listing ................................................................................... 113
EXAMPLE 5–10 Transaction Information Listing ........................................................................... 113
EXAMPLE 6–1 Physical Destination Information Listing ............................................................ 121
EXAMPLE 6–2 Physical Destination Metrics Listing .................................................................... 122
EXAMPLE 6–3 Destination Disk Utilization Listing ..................................................................... 123
EXAMPLE 7–1 Adding a Connection Factory ................................................................................ 139
EXAMPLE 7–2 Adding a Destination to an LDAP Object Store .................................................. 140
EXAMPLE 7–3 Adding a Destination to a File-System Object Store ........................................... 140
EXAMPLE 7–4 Deleting an Administered Object .......................................................................... 141
EXAMPLE 7–5 Listing All Administered Objects .......................................................................... 141
EXAMPLE 7–6 Listing Administered Objects of a Specific Type ................................................. 142
EXAMPLE 7–7 Viewing Administered Object Information ......................................................... 142
EXAMPLE 7–8 Modifying an Administered Object’s Attributes .................................................. 143
EXAMPLE 7–9 Object Manager Command File Syntax ................................................................ 143
EXAMPLE 7–10 Example Command File ......................................................................................... 144
EXAMPLE 7–11 Partial Command File ............................................................................................. 144
EXAMPLE 7–12 Using a Partial Command File ............................................................................... 145

19
Examples

EXAMPLE 8–1 Configuration Listing for a Conventional Cluster .............................................. 153

EXAMPLE 8–2 Configuration Listing for an HA Cluster .............................................................. 153
EXAMPLE 9–1 Viewing Information for a Single User ................................................................. 171
EXAMPLE 9–2 Viewing Information for All Users ....................................................................... 172
EXAMPLE 9–3 Connection Services Listing ................................................................................... 190
EXAMPLE C–1 Tunnel Servlet Status Report .................................................................................. 376

20 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Preface

This Sun JavaTM System Message Queue 4.1 Administration Guide provides background and
information needed by system administrators to set up and manage a Sun Java System Message
Queue messaging system.

This preface consists of the following sections:

■ “Who Should Use This Book” on page 21
■ “Before You Read This Book” on page 21
■ “How This Book Is Organized” on page 22
■ “Documentation Conventions” on page 23
■ “Related Documentation” on page 26
■ “Sun Welcomes Your Comments” on page 29

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 Java System Message Queue 4.1 Technical
Overview to become familiar with Message Queue’s 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.

21
Preface

How This Book Is Organized

Table P–1 describes the contents of this manual.

TABLE P–1 Contents of This Manual

Chapter/Appendix Description

Part I

Chapter 1, “Administrative Tasks and Introduces Message Queue administrative tasks and tools.
Tools”

Chapter 2, “Quick-Start Tutorial” Provides a hands-on tutorial to acquaint you with the Message Queue
Administration Console.

Part II

Chapter 3, “Starting Brokers and Describes how to start the Message Queue broker and clients.
Clients”

Chapter 4, “Broker Configuration” Describes how configuration properties are set and read, and gives an
introduction to the configurable aspects of the broker. Also describes
how to set up a file or database to perform persistence functions.

Chapter 5, “Broker Management” Describes broker management tasks.

Chapter 6, “Physical Destinations” Describes management tasks relating to physical destinations.

Chapter 7, “Administered Objects” Describes the object store and shows how to perform tasks related to
administered objects (connection factories and destinations).

Chapter 8, “Broker Clusters” Describes how to set up and manage a cluster of Message Queue
brokers.

Chapter 9, “Security” Describes security-related tasks, such as managing password files,

authentication, authorization, and encryption.

Chapter 10, “Monitoring Broker Describes how to set up and use Message Queue monitoring facilities.
Operations”

Chapter 11, “Analyzing and Tuning a Describes techniques for analyzing and optimizing message service
Message Service” performance.

Chapter 12, “Troubleshooting” Provides suggestions for determining the cause of common Message
Queue problems and the actions you can take to resolve them.

Part III

Chapter 13, “Command Line Provides syntax and descriptions for Message Queue command line
Reference” utilities.

Chapter 14, “Broker Properties Describes the configuration properties of Message Queue message
Reference” brokers.

22 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Preface

TABLE P–1 Contents of This Manual (Continued)

Chapter/Appendix Description

Chapter 15, “Physical Destination Describes the configuration properties of physical destinations.
Property Reference”

Chapter 16, “Administered Object Describes the configuration properties of administered objects
Attribute Reference” (connection factories and destinations).

Chapter 17, “JMS Resource Adapter Describes the configuration properties of the Message Queue Resource
Property Reference” Adapter for use with an application server.

Chapter 18, “Metrics Reference” Describes the metric information that a Message Queue message
broker can provide for monitoring, turning, and diagnostic purposes. .

Chapter 19, “JES Monitoring Lists Message Queue attributes that are accessible by means of the Java
Framework Reference” Enterprise System Monitoring Framework (JESMF).

Part IV

Appendix A,“ Platform-Specific Lists the locations of Message Queue files on each supported platform.
Locations of Message Queue Data”

Appendix B,“ Stability of Message Describes the stability of various Message Queue interfaces.
Queue Interfaces”

Appendix C, “HTTP/HTTPS Describes how to set up and use the Hypertext Transfer Protocol
Support” (HTTP) for Message Queue communication.

Appendix D, “JMX Support” Describes Message Queue’s administrative support for client programs
using the Java Management Extensions (JMX) application
programming interface

Appendix E, “Frequently Used Lists some frequently used Message Queue Command utility (imqcmd)
Command Utility Commands” commands.

Documentation Conventions
This section describes various conventions used in Message Queue documentation.

Typographic Conventions
Table P–2 shows the typographic conventions used inMessage Queue documentation.

23
Preface

TABLE P–2 Typographic Conventions

Typeface Meaning Examples

AaBbCc123 Names of commands, files, and directories, and Edit your .login file.
onscreen computer output
Use ls -a to list all files.
machine_name% you have mail.

AaBbCc123 What you type, contrasted with onscreen machine_name% su

computer output
Password:

AaBbCc123 Placeholder: replace with a real name or value The command to remove a file is
rm fileName.

AaBbCc123 Book titles, new terms, and emphasized words 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 online in boldface.

Symbol Conventions
Table P–3 shows symbol conventions used inMessage Queue documentation.

TABLE P–3 Symbol Conventions

Symbol Description Example Meaning

[] Encloses optional ls [-l] The -l option is optional.

arguments and command
options

{|} Encloses a set of choices -d {y|n} The -d option requires that you use either
for a required command the y argument or the n argument.
option

${ } Indicates a variable ${com.sun.javaRoot} References the value of the variable

reference com.sun.javaRoot.

- Joins simultaneous Ctrl-A Hold down the Control key while

multiple keystrokes pressing the A key.

+ Joins consecutive Ctrl+A+N Press the Control key, release it, and then
multiple keystrokes press the subsequent keys.

24 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Preface

TABLE P–3 Symbol Conventions (Continued)

Symbol Description Example Meaning

→ Indicates hierarchical File → New → Templates From the File menu, choose New; from
menu selection in a the New submenu, choose Templates.
graphical user interface

Directory Variable Conventions

Message Queue makes use of three directory variables; how they are set varies from platform to
platform. Table P–4 describes these variables and how they are used on the SolarisTM, Linux, and
Windows platforms.

Note – In this manual, these directory variables are shown without platform-specific
environment variable notation or syntax (such as $IMQ_HOME on UNIX). Non-platform-specific
pathnames use UNIX directory separator (/) notation.

TABLE P–4 Directory Variable Conventions

Variable Description

IMQ_HOME Message Queue home directory:

■ Unused on Solaris and Linux; there is no Message Queue home
directory.
■ On Windows, denotes the directory mqInstallHome\mq, where
mqInstallHome is the installation home directory specified when the
product was installed (by default, C:\Program
Files\Sun\MessageQueue).

Note – The information above applies only to the standalone installation

of Message Queue. When Message Queue is installed and run as part of a
Sun Java System Application Server installation, IMQ_HOME is set to
appServerInstallDir/imq, where appServerInstallDir is the Application
Server installation directory.

25
Preface

TABLE P–4 Directory Variable Conventions (Continued)

Variable Description

IMQ_VARHOME Directory in which Message Queue temporary or dynamically created

configuration and data files are stored; can be set as an environment
variable to point to any directory.
■ On Solaris, defaults to /var/imq.
■ On Linux, defaults to /var/opt/sun/mq.
■ On Windows, defaults to IMQ_HOME\var.

Note – The information above applies only to the standalone installation

of Message Queue. When Message Queue is installed and run as part of a
Sun Java System Application Server installation, IMQ_VARHOME is set to
appServerDomainDir/imq, where appServerDomainDir is the domain
directory for the domain starting the Message Queue broker.

IMQ_JAVAHOME Location of the Java runtime environment (JRE) used by Message Queue
executables.

Related Documentation
The information resources listed in this section provide further information about Message
Queue in addition to that contained in this manual.

Message Queue Documentation Set

Table P–5 lists the documents in the Message Queue documentation set, in the order in which
you would normally use them. These documents are available through the Sun documentation
Web site at
http://www.sun.com/documentation/

Click “Sun Java Systems,” followed by “Software,” “Application & Integration Services,” and then
“Message Queue.”

TABLE P–5 Message Queue Documentation Set

Document Audience Description

Message Queue Installation Guide Developers and Explains how to install Message Queue software
administrators on Solaris, Linux, and Windows platforms

Message Queue Release Notes Developers and Includes descriptions of new features,
administrators limitations, and known bugs, as well as
technical notes

26 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Preface

TABLE P–5 Message Queue Documentation Set (Continued)

Document Audience Description

Message Queue Technical Overview Developers and Introduces basic Message Queue concepts,
administrators features, and components

Message Queue Administration Guide Administrators (also Provides background and information needed
recommended for by system administrators to set up and manage
developers) a Message Queue messaging system

Message Queue Developer’s Guide for Developers Provides information on developing Java client
Java Clients programs using Message Queue's Java
application programming interface

Message Queue Developer’s Guide for Developers Provides information on developing C and C++
C Clients client programs using Message Queue's C
application programming interface (C API)

Message Queue Developer’s Guide for Developers Provides information on developing Java client
JMX Clients programs using the Message Queue
implementation of the Java Management
Extensions (JMX) application programming
interface

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

JavaDoc
JMS and Message Queue API documentation in JavaDoc format is included in your Message
Queue installation at the locations shown in Table P–6, depending on your platform. This
documentation can be viewed in any HTML browser. It includes standard JMS API
documentation as well as Message Queue–specific APIs.

TABLE P–6 JavaDoc Locations

Platform Location

Solaris /usr/share/javadoc/imq/index.html

Linux /opt/sun/mq/javadoc/index.html

27
Preface

TABLE P–6 JavaDoc Locations (Continued)

Platform Location

Windows IMQ_HOME\javadoc\index.html
where IMQ_HOME is the Message Queue home directory

Example Client Applications

Example client applications providing sample application code are included in your Message
Queue installation at the locations shown in Table P–7, depending on your platform. The
README files located in these directories and their subdirectories provide descriptive
information about the example applications.

TABLE P–7 Code Example Locations

Platform Location

Solaris /usr/demo/imq (Java examples)

/opt/SUNWimq/demo (C examples)

Linux /opt/sun/mq/examples

Windows IMQ_HOME\demo
where IMQ_HOME is the Message Queue home directory

Online Help
Online help is available for the Message Queue command line utilities; see Chapter 13,
“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 “Administration Console Online Help” on page 42.

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

28 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Preface

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.

Sun Welcomes Your Comments

Sun is always interested in improving its documentation and welcomes your comments and
suggestions. To share your comments, go to the Sun documentation Web site at
http://docs.sun.com

and click Send comments. In the resulting online form, provide the document title and part
number along with your comment. (The part number is a 7-digit or 9-digit number that can be
found on the book’s title page or in the document's URL. For example, the part number of this
book is 819-4467.)

29
30
P A R T I

Introduction to Message Queue

Administration
■ Chapter 1, “Administrative Tasks and Tools”
■ Chapter 2, “Quick-Start Tutorial”

31
32
 1
C H A P T E R 1

Administrative Tasks and Tools

This chapter provides an overview of Sun JavaTM System 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 33
■ “Administration Tools” on page 36

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

33
Administrative Tasks

■ 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 User’s
Password” on page 170)
■ Controlling individual or group access to the administrative connection service
(“Authorization Rules for Connection Services” on page 183) and the dead message queue
(“Authorization Rules for Physical Destinations” on page 184)
■ Regulating administrative group access to a file-based or Lightweight Directory Access
Protocol (LDAP) user repository (“User Groups and Status” on page 166, “Using an LDAP
User Repository” on page 172)

General security
■ Managing the contents of a file-based user repository (“Using the User Manager Utility” on
page 167) or configuring the broker to use an existing LDAP user repository (“Using an
LDAP User Repository” on page 172)
■ Controlling the operations that individual users or groups are authorized to perform (“User
Authorization” on page 180)
■ Setting up encryption services using the Secure Socket Layer (SSL) (“Message Encryption”
on page 185)

Administered objects
■ Setting up and configuring an LDAP object store ( “LDAP Server Object Stores” on
page 127)
■ Creating connection factories and destinations ( “Adding Administered Objects” on
page 138)

Broker clusters

34 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Administrative Tasks

■ Creating a cluster configuration file (“Setting the Cluster Configuration” on page 149)
■ Designating a master broker (“Managing the Configuration Change Record” on page 158)

Persistence
■ Configuring a broker to use a persistent store ( “Configuring a Persistent Data Store” on
page 92).

Memory management
■ Setting a destination’s configuration properties to optimize its memory usage (“Updating
Physical Destination Properties” on page 119, Chapter 15, “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 11, “Analyzing and Tuning
a Message Service”)
■ Managing broker memory resources (“Routing Services” on page 78)
■ Creating and managing broker clusters to balance message load (Chapter 8, “Broker
Clusters”)
■ Recovering failed brokers (“Starting Brokers” on page 68).

Administered objects
■ Adjusting connection factory attributes to ensure the correct behavior of client applications
(“Connection Factory Attributes” on page 130)
■ Monitoring and managing physical destinations ( Chapter 6, “Physical Destinations”)
■ Controlling user access to destinations ( “Authorization Rules for Physical Destinations” on
page 184)

Client management
■ Monitoring and managing durable subscriptions (see “Managing Durable Subscriptions”
on page 111).
■ Monitoring and managing transactions (see “Managing Transactions” on page 112).

Chapter 1 • Administrative Tasks and Tools 35

Administration Tools

Administration Tools
Message Queue administration tools fall into two categories:
■ Command line utilities
■ The graphical Administration Console

Command Line Utilities

All Message Queue utilities are accessible via a command line interface. Utility commands share
common formats, syntax conventions, and options. They include the following:
■ The Broker utility (imqbrokerd) starts up brokers and specifies their configuration
properties, including connecting them together into a cluster.
■ The Command utility (imqcmd) controls brokers and their resources and manages physical
destinations.
■ The Object Manager utility (imqobjmgr ) manages provider-independent administered
objects in an object store accessible via the Java Naming and Directory Interface (JNDI).
■ The Database Manager utility (imqdbmgr ) creates and manages databases for persistent
storage that conform to the Java Database Connectivity (JDBC) standard.
■ The User Manager utility (imqusermgr ) populates a file-based user repository for user
authentication and authorization.
■ The Service Administrator utility ( imqsvcadmin) installs and manages a broker as a
Windows service.
■ The Key Tool utility (imqkeytool) generates self-signed certificates for Secure Socket Layer
(SSL) authentication.

See Chapter 13, “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

36 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Administration Tools

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 1–1).
Remote
Admin Host

Broker Host

Administration
Console

Broker

imqcmd

imqbrokerd imqkeytool
imqobjmgr

imqusermgr imqdbmgr

imqsvcadmin
(Windows only)

FIGURE 1–1 Local and Remote Administration Utilities

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 37

38
 2
C H A P T E R 2

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 40
■ “Administration Console Online Help” on page 42
■ “Working With Brokers” on page 43
■ “Working With Physical Destinations” on page 48
■ “Working With Object Stores” on page 53
■ “Working With Administered Objects” on page 56
■ “Running the Sample Application” on page 61

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, “Platform-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 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

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

Starting the Administration Console

To start the Administration Console, use one of the following methods:
■ On Solaris, enter the command

/usr/bin/imqadmin
■ On Linux, enter the command

/opt/sun/mq/bin/imqadmin
■ On Windows, choose Start > Programs > Sun Microsystems > Sun Java System Message
Queue 4.1 > Administration.

You may need to wait a few seconds before the Administration Console window is displayed
(see Figure 2–1).

40 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Starting the Administration Console

FIGURE 2–1 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 JavaTM System 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 41

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
Console’s Help window (Figure 2–2) will be displayed.

FIGURE 2–2 Administration Console Help Window

The Help window’s 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 window’s 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 window’s 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.

42 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Working With Brokers

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:
■ On Solaris, enter the command

/usr/bin/imqbrokerd
■ On Linux, enter the command

/opt/sun/mq/bin/imqbrokerd
■ On Windows, choose Start > Programs > Sun Microsystems > Sun Java System Message
Queue 4.1 > Message Broker.

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 window’s 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 2–3) will appear.

Chapter 2 • Quick-Start Tutorial 43

Working With Brokers

FIGURE 2–3 Add Broker Dialog Box

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

3 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 2–4. The
red X over the broker’s icon indicates that it is not currently connected to the Administration
Console.

44 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Working With Brokers

FIGURE 2–4 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 43, 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 broker’s name in the Administration Console window’s navigation pane and choose
Connect to Broker from the Actions menu.
Alternatively, you can right-click on the broker’s name and choose Connect to Broker from the
pop-up context menu. In either case, the Connect to Broker dialog box ( Figure 2–5) will
appear.

Chapter 2 • Quick-Start Tutorial 45

Working With Brokers

FIGURE 2–5 Connect to Broker Dialog Box

2 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 165); 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.

3 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 broker’s 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 broker’s name in the Administration Console window’s navigation
pane.
A list of the available services will appear in the result pane (see Figure 2–6), showing the name,
port number, and current state of each service.

46 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Working With Brokers

FIGURE 2–6 Viewing Connection Services

2 Select a service by clicking on its name in the result pane.

For this exercise, select the name jms.

3 Choose Properties from the Actions menu.

The Service Properties dialog box (Figure 2–7) 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.

FIGURE 2–7 Service Properties Dialog Box

For this exercise, do not change any of the connection service’s 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 Console’s link to
the broker: if you paused it, you would no longer be able to access the broker.

Chapter 2 • Quick-Start Tutorial 47

Working With Physical Destinations

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 broker’s name in the Administration Console window’s
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 2–8) will
appear.

48 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Working With Physical Destinations

FIGURE 2–8 Add Broker Destination Dialog Box

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

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

4 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 Console’s Actions menu to view or
modify the properties of a physical destination.

Chapter 2 • Quick-Start Tutorial 49

Working With Physical Destinations

▼ To View or Modify the Properties of a Physical Destination

1 Select Destinations under the broker’s name in the Administration Console window’s
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 Select a physical destination by clicking on its name in the result pane.

3 Choose Properties from the Actions menu.

The Broker Destination Properties dialog box (Figure 2–9) 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.

50 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Working With Physical Destinations

FIGURE 2–9 Broker Destination Properties Dialog Box

For this exercise, do not change any of the destination’s 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 2–10), listing information about all durable subscriptions currently associated with the
given topic.

Chapter 2 • Quick-Start Tutorial 51

Working With Physical Destinations

FIGURE 2–10 Durable Subscriptions Panel

You can use the Durable Subscriptions panel’s 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 broker’s name in the Administration Console window’s
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 Select a destination by clicking on its name in the result pane.

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

4 Click Yes to confirm the operation and dismiss the confirmation dialog.

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.

52 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Working With Object Stores

▼ To Delete a Physical Destination

1 Select Destinations under the broker’s name in the Administration Console window’s
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 Select a destination by clicking on its name in the result pane.

3 Choose Delete from the Edit menu.

A confirmation dialog box will appear, asking you to confirm that you wish to proceed with the
operation.

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

Working With Object Stores

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 application’s 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.

Chapter 2 • Quick-Start Tutorial 53

Working With Object Stores

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 window’s 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 2–11) will appear.

FIGURE 2–11 Add Object Store Dialog Box

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

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

c. Click the Add button to add the specified attribute value.

The property and its value will appear in the property summary pane.

54 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Working With Object Stores

Repeat steps “Adding an Object Store” on page 53 to “Adding an Object Store” on page 53
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 127 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 2–12. The red X over the object store’s icon indicates that it is not currently connected to
the Administration Console.

FIGURE 2–12 Object Store Displayed in Administration Console Window

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 2–11, to view or modify any of its properties.

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.

Chapter 2 • Quick-Start Tutorial 55

Working With Administered Objects

▼ To Connect to an Object Store

● Click on the object store’s name in the Administration Console window’s navigation pane and
choose Connect to Object Store from the Actions menu.
Alternatively, you can right-click on the object store’s name and choose Connect to Object Store
from the pop-up context menu. In either case, the red X will disappear from the object store’s
icon, indicating that it is now connected to the Administration Console.

Working With Administered Objects

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 non–Message 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 Store”on page 55).

2 Click on the Connection Factories item under the object store’s name in the Administration
Console window’s 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 2–13) will appear.

56 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Working With Administered Objects

FIGURE 2–13 Add Connection Factory Object Dialog Box

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

4 Choose the type of connection factory you wish to create from the Factory Type pull-down
menu.
For this exercise, choose QueueConnectionFactory.

5 Click the Connection Handling tab.

The Connection Handling panel will appear, as shown in Figure 2–13.

6 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 broker’s 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 317 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 57

Working With Administered Objects

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.

8 If appropriate, click the Read-Only checkbox.

This locks the connection factory object’s configuration attributes to the values they were given
at creation time. A read-only administered object’s attributes cannot be overridden, whether
programmatically from client code or administratively from the command line.
For this exercise, do not check Read-Only.

9 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 48, 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 Store”on page 55).

58 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Working With Administered Objects

2 Click on the Destinations item under the object store’s name in the Administration Console
window’s 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 2–14) will
appear.

FIGURE 2–14 Add Destination Object Dialog Box

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

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

5 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 48).
For this exercise, type in the name MyQueueDest.

6 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

Chapter 2 • Quick-Start Tutorial 59

Working With Administered Objects

7 If appropriate, click the Read-Only checkbox.

This locks the destination object’s configuration attributes to the values they were given at
creation time. A read-only administered object’s attributes cannot be overridden, whether
programmatically from client code or administratively from the command line.
For this exercise, do not check Read-Only.

8 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 2–15.

FIGURE 2–15 Destination Object Displayed in Administration Console Window

Viewing Administered Object Properties

You can use the Properties command on the Administration Console’s 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 store’s name in the Administration
Console window’s 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 Select an administered object by clicking on its name in the result pane.

3 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 2–13) or Add Destination Object
(Figure 2–14) dialog. You can use this dialog box to change the selected object’s configuration

60 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Running the Sample Application

attributes. Note, however, that you cannot change the object’s 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 store’s name in the Administration
Console window’s 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 Select an administered object by clicking on its name in the result pane.

3 Choose Delete from the Edit menu.

A confirmation dialog box will appear, asking you to confirm that you wish to proceed with the
operation.

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

Running the Sample Application

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
The code creates a simple queue sender and receiver, and sends and receives a Hello World
message.

Chapter 2 • Quick-Start Tutorial 61

Running the Sample Application

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

1 Make the directory containing the HelloWorldmessageJNDI application your current directory,
using one of the following commands (depending on the platform you’re using):
■ On Solaris:

cd /usr/demo/imq/helloworld/helloworldmessagejndi
■ On Linux:

cd /opt/sun/mq/examples/helloworld/helloworldmessagejndi
■ On Windows:

cd IMQ_HOME\\demo\\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 Developer’s 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 Developer’s 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 you’re using):
■ On Solaris or Linux:

% java HelloWorldMessageJNDI file:///tmp

■ On Windows:

62 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Running the Sample Application

java HelloWorldMessageJNDI
If the application runs successfully, you should see the output shown in Example 2–1.

Example 2–1 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

Chapter 2 • Quick-Start Tutorial 63

64
P A R T I I

Administrative Tasks
■ Chapter 3, “Starting Brokers and Clients”
■ Chapter 4, “Broker Configuration”
■ Chapter 5, “Broker Management”
■ Chapter 6, “Physical Destinations”
■ Chapter 7, “Administered Objects”
■ Chapter 8, “Broker Clusters”
■ Chapter 9, “Security”
■ Chapter 10, “Monitoring Broker Operations”
■ Chapter 11, “Analyzing and Tuning a Message Service”
■ Chapter 12, “Troubleshooting”

65
66
 3
C H A P T E R 3

Starting Brokers and Clients

After installing Sun JavaTM System Message Queue and performing some preparatory steps, you
can begin starting brokers and clients. A broker’s 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, “Broker Configuration” for more information.

This chapter contains the following sections:

■ “Preparing System Resources” on page 67
■ “Starting Brokers” on page 68
■ “Removing Brokers” on page 72
■ “Starting Clients” on page 73

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

67
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
user’s 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 76).

68 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 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
broker’s operation. The following example 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 broker’s instance configuration file (config.properties). The instance
configuration file is described under “Configuration Files” on page 89. The following example
sets a broker’s 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

See “Broker Utility” on page 262 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

from the command line.

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 Startup on Solaris and Linux

On Solaris and 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 /etc/imq/imqbrokerd.conf (Solaris) or
/etc/opt/sun/mq/imqbrokerd.conf (Linux) 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.

Chapter 3 • Starting Brokers and Clients 69

Starting Brokers

Automatic 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

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
■ Remove a broker that is 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 command’s -D option, as described under “Starting
Brokers” on page 68. Use the Command utility (imqcmd) to control broker operations as usual.

See “Service Administrator Utility” on page 280 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.

70 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Starting Brokers

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.

2 Remove the service.

On the command line, enter the command
imqsvcadmin remove

3 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 service’s 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 command’s -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 service’s 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

Chapter 3 • Starting Brokers and Clients 71

Removing Brokers

Displaying Broker Service Startup Options

To determine the startup options for the broker service, use the imqsvcadmin query command,
as shown in Example 3–1.

EXAMPLE 3–1 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

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 Open the Windows Administrative Tools control panel.

2 Start the Event Viewer tool.

3 Select the Application event log.

4 Choose Refresh from the Action menu to display any error events.

Removing Brokers
The procedure for removing a broker again varies from one platform to another, as described in
the following sections.

Removing a Broker on Solaris or Linux

To remove a broker instance on the Solaris or Linux platform, use the imqbrokerd command
with the -remove option:

imqbrokerd [options...] -remove instance

72 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Starting Clients

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.

If the broker is set up to start automatically at system startup, edit the configuration file
/etc/imq/imqbrokerd.conf (Solaris) or /etc/opt/sun/mq/imqbrokerd.conf (Linux) and set
the AUTOSTART property to NO.

See “Broker Utility” on page 262 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

Removing a Windows Broker Service

To remove a broker that is running as a Windows service, use the command

imqcmd shutdown bkr

to shut down the broker, followed by

imqsvcadmin remove

to remove the service.

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 removing the broker service.

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 Developer’s 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.

Chapter 3 • Starting Brokers and Clients 73

Starting Clients

The application’s 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 16, “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.

74 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 4
C H A P T E R 4

Broker Configuration

A broker’s 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 75
■ “Setting Broker Properties” on page 89
■ “Configuring a Persistent Data Store” on page 92

For full reference information about broker configuration properties, see Chapter 14, “Broker
Properties Reference”

Broker Services
Broker configuration properties can be divided into several categories, depending 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.
■ Routing services route and deliver JMS payload messages, as well as control messages used by
the message service to support reliable delivery.
■ Persistence services manage the writing and retrieval of data to and from persistent storage.
■ Security services authenticate users connecting to the broker and authorize their actions.
■ Monitoring services generate metric and diagnostic information about the broker’s
performance.

The following sections describe each of these services and the properties you use to customize
them for your particular needs.

75
Broker Services

Connection Services
Message brokers can offer various connection services supporting both application and
administrative clients, using a variety of transport protocols. Broker configuration properties
related to connection services are listed under “Connection Properties” on page 283.

Table 4–1 shows the available connection services, which are distinguished by two
characteristics:
■ 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.

TABLE 4–1 Message Queue Connection Services

Service Name Service Type Protocol Type

jms NORMAL TCP

ssljms NORMAL TLS (SSL-based security)

httpjms NORMAL HTTP

httpsjms NORMAL HTTPS (SSL-based security)

admin ADMIN TCP

ssladmin ADMIN TLS (SSL-based security)

By setting a broker’s 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
“Security Services” on page 83 for more information.

Note – There is also a special cluster connection service, used internally by the brokers within a
cluster to exchange information about the cluster’s configuration and state. This service is not
intended for use by clients communicating with a broker. See Chapter 8, “Broker Clusters” for
more information about broker clusters.

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
broker’s Port Mapper assign one dynamically. The Port Mapper itself resides at the broker’s

76 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Broker Services

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 4–1). (Only the jms, ssljms, admin, and ssladmin connection services can be configured
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 195), 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.

Chapter 4 • Broker Configuration 77

Broker Services

The broker’s 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 don’t 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 service’s 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
saving on memory resources. Under heavy loads, the number of threads might increase until
the pool’s 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.

Routing Services
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 Properties” on page 286 to
manage these tasks in a way that suits your application’s 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 15, “Physical Destination Property Reference.” They include limits on the number

78 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Broker Services

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 14–3 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
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 systemwide and destination limits to optimize memory resources.

Chapter 4 • Broker Configuration 79

Broker Services

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.

An important use for persistent data stores is for providing high availability message service. In
this model, two or more brokers are joined together in a broker cluster sharing the same
persistent store. If one of the brokers should fail, another broker within the cluster can then take
over ownership of its messages and see that they are delivered to their destinations without
interruption of service. (See Chapter 8, “Broker Clusters” and the Message Queue Technical
Overviewfor more information on clusters and how they operate.)

Message Queue supports both file-based and JDBC-based persistence modules (see Figure 4–1).
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-compliant
data store. While file-based persistence is generally faster than JDBC-based, some users prefer
the redundancy and administrative control provided by a JDBC-compliant store. The broker
configuration property imq.persist.store (see Table 14–4) specifies which of the two forms
of persistence to use.

Broker
File-based
Data Store

Physical
JDBC-compliant
Destinations
Data Store

FIGURE 4–1 Persistent Data Storage

80 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Broker Services

Note – 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. As a result of
these changes, the persistent store version numbers were updated to 370 for file-based and 400
for JDBC-based stores. You can use the imqdbmgr query command (see “Displaying
Information About the Persistent Store” on page 94) 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 store and automatically migrate it to the latest format:
■ File-based store versions 200 and 350 will be migrated to the version 370 format.
■ JDBC-based store versions 350 and 370 will be migrated to the version 400 format. (If you
need to upgrade a version 200 store, you will need to step through an intermediate 3.5 or 3.6
release.)

This upgrade leaves the older copy of the persistent store intact, allowing you to roll back the
upgrade if necessary. To do so, you can uninstall Message Queue 4.0 or 4.1 and reinstall the
earlier version you were previously running. The older version’s message brokers will locate and
use the older copy of the persistent store.

File-Based Persistence
By default, Message Queue uses a file-based persistent data store, in which individual files store
persistent data such as messages, destinations, durable subscriptions, and transactions. Broker
configuration properties related to file-based persistence are listed under “File-Based
Persistence Properties” on page 291.

The file-based 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, “Platform-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 persistent data store can contain messages of a sensitive or proprietary
nature, you should secure the …/instances/instanceName/fs370 directory against
unauthorized access; see “Securing Persistent Data” on page 94.

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

Chapter 4 • Broker Configuration 81

Broker Services

messages are added and removed (see “Managing Physical Destination Disk Utilization” on
page 123). 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 destination’s 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 broker’s 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 persistent 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 persistent storage
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.
Note, however, that although the data is not lost, it is not available to any other broker in a
cluster, since clustered brokers do not currently share data.

JDBC-Based Persistence
Instead of using file-based persistence, 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 Store” on
page 92 for specifics.

The properties for configuring a broker to use a JDBC database are listed in Table 14–6. 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).

82 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Broker Services

The imq.persist.jdbc.dbVendor property identifies the database vendor being used for the
persistent data store; all of the remaining properties are qualified by this vendor name. The
imq.persist.jdbc.vendorName.driver property gives the Java class name of the JDBC driver
to use in connecting to the database. There are also properties specifying the URLs for
connecting to an existing database (imq.persist.jdbc.vendorName.opendburl), creating a
new database (imq.persist.jdbc.vendorName.createdburl), and closing a database
connection (imq.persist.jdbc.vendorName.closedburl).
The imq.persist.jdbc.vendorName.user and imq.persist.jdbc.vendorName.password
properties give the user name and 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 password should be specified only in a password
file designated with the -passfile command line option; if no such password file is specified,
the imqbrokerd and imqdbmgr commands will prompt for the password interactively. Similarly,
the user name can be supplied from the command line using the -dbuser option to the
imqbrokerd command or the -u option to imqdbmgr. If any additional, vendor-specific
properties are required, you can set them by using broker properties of the form
imq.persist.jdbc.vendorName.property.propName.
In a JDBC database shared by multiple broker instances, the configuration property
imq.brokerid specifies a unique instance identifier for each, to be appended to the names of
database tables. (This is usually unnecessary for an embedded database, which stores data for
only one broker instance.)
Besides setting all of the broker’s needed JDBC configuration properties, you must also install
your JDBC driver’s .jar file in the appropriate directory location, depending on your
operating-system platform (as listed in Appendix A, “Platform-Specific Locations of Message
Queue Data”) and then execute the Database Manager command
imqdbmgr create tbl
to create the database schema for the persistent data store.

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 293. The boolean property

Chapter 4 • Broker Configuration 83

Broker Services

imq.accesscontrol.enabled acts as a master switch that controls whether access control is

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 4–1: for example,
imq.httpjms.accesscontrol.enabled.
Figure 4–2 shows the components needed 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.
Two User
Repository Options

LDAP
Server User
Repository

Broker
Authentication imqusermgr
Flat File User
Repository

Physical Access Control

Authorization Properties File
Destinations
accesscontrol.properties

FIGURE 4–2 Security Support

As Figure 4–2 shows, you can store user data in a flat-file user repository that is provided with
the Message Queue service or you can plug in a preexisting Lightweight Directory Access
Protocol (LDAP) repository:
■ If you choose a flat-file repository, you must use the Message Queue User Manager utility
(imqusermgr) to manage the repository. This option is built-in and easy to use.
■ 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’s
instance configuration file to enable the broker to query the LDAP server for information
about users and groups.

84 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Broker Services

The broker’s imq.authentication.basic.user_repository property specifies which type of

repository to use. In general, an LDAP repository 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 165 for more information on setting up a flat-file
or LDAP user repository.

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 193, 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 293 for details.

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

Chapter 4 • Broker Configuration 85

Broker Services

When a user attempts to perform an operation, the broker checks the user’s 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

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.

Monitoring Services
The broker includes components for monitoring and diagnosing application and broker
performance. These include the following:
■ Components that generate data, a Metrics Generator and broker code that logs events
■ A Logger component that writes out information to a number of output channels
■ A Metrics Message Producer that sends JMS messages containing metric information to
topic destinations for consumption by JMS monitoring clients

The general scheme is illustrated in Figure 4–3. Broker properties for configuring the
monitoring services are listed under “Monitoring Properties” on page 298.

86 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Broker Services

Output Channels
Logger
Broker
log file
Code
ERROR
console
WARNING
INFO syslog (Solaris)
Metrics
Generator
Metrics
Message topic destinations
Producer

FIGURE 4–3 Monitoring Support

Metrics Generator
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;
imq.metrics.interval specifies how often.

Logger
The Logger takes information generated by broker code and the Metrics Generator and writes
that information to standard output (the console), to a log file, and, on Solaris platforms, to the
syslog daemon process in case of errors. The log file to use is identified by the
imq.log.file.dirpath and imq.log.file.filename broker properties;
imq.log.console.stream 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. The
imq.log.console.output and imq.log.file.output properties control which of the specified
categories will be written 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. There is also an
imq.destination.logDeadMsgs property that specifies whether to log when dead messages are
discarded or moved to the dead message queue.

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.

Chapter 4 • Broker Configuration 87

Broker Services

See “Monitoring Properties” on page 298 for additional broker properties related to logging, and
“Configuring and Using Broker Logging” on page 199 for further details about how to configure
the Logger and how to use it to obtain performance information.

Metrics Message Producer

The Metrics Message Producer receives information from the Metrics Generator at regular
intervals and writes the information into metrics messages, which it then sends to one of a
number of metric topic destinations, depending on the type of metric information contained in
the message (see Table 4–2). Message Queue clients subscribed to these metric topic
destinations can consume the messages and process the metric data they contain. This allows
developers to create custom monitoring tools to support messaging applications. For details of
the metric quantities reported in each type of metrics message, see the Message Queue
Developer’s Guide for Java Clients.

TABLE 4–2 Metric Topic Destinations

Topic Name Type of Metric Information

mq.metrics.broker Broker metrics

mq.metrics.jvm Java Virtual Machine metrics

mq.metrics.destination_list List of destinations and their types

mq.metrics.destination.queue.queueName Destination metrics for specified queue

mq.metrics.destination.topic.topicName Destination metrics for specified topic

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.

88 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Setting Broker Properties

Setting Broker Properties

You can specify a broker’s configuration properties in either of two ways:
■ Edit the broker’s configuration file.
■ Supply the property values directly from the command line.

The following two sections describe these two methods of configuring a broker.

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, “Platform-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 302 for more information.

At startup, the broker merges property values from the various configuration files. As shown in
Figure 4–4, 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.

Chapter 4 • Broker Configuration 89

Setting Broker Properties

imqbrokerd
-name MyBroker Overrides
-metrics 5

Startup
Command
config.properties

Overrides

Instance
Configuration File

install.properties

Overrides

Install
Configuration File

default.properties

Default
Configuration File

FIGURE 4–4 Broker Configuration Files

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, “Platform-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 262) to specify an instance name that Message Queue
can use to create the file.

Note – The instances/instanceName directory and the instance configuration file are owned by
the user who created the corresponding broker instance. The broker instance must always be
restarted by that same user.

90 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Setting Broker Properties

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 customize the broker’s behavior and resource use. To do
so, you must be the owner of the instances/instanceName directory or log in as the root user to
change the directory’s access privileges.

The broker reads its instance configuration file only at startup. To make permanent changes to
the broker’s configuration, you must shut down the broker, edit the file, and then restart the
broker. Property definitions in the 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 75 and Chapter 14, “Broker Properties Reference” for
information on the available broker configuration properties and their default values.

Setting Configuration Options from the Command

Line
You can enter broker configuration options 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
command’s -D option, you can specify any broker configuration property and its value; see
“Starting Brokers” on page 68 and “Broker Utility” on page 262 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 280.

You can also change certain broker properties while a broker is running. To modify the
configuration of a running broker, you use the Command utility’s imqcmd update bkr
command; see “Updating Broker Properties” on page 103 and “Broker Management” on
page 268.

Chapter 4 • Broker Configuration 91

Configuring a Persistent Data Store

Configuring a Persistent Data Store

A broker’s persistent data store holds information about physical destinations, durable
subscriptions, messages, transactions, and acknowledgments. 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 14–4) specifies which of the two forms of persistence
to use.

Configuring a File-Based Store

A file-based data store is automatically created when you create a broker instance. The store is
located in the broker’s instance directory; see Appendix A, “Platform-Specific Locations of
Message Queue Data” for the exact location.

By default, Message Queue performs asynchronous write operations to disk. The operating
system can buffer these operations for efficient performance. However, if an unexpected system
failure should occur between write operations, messages could be lost. To improve reliability (at
the cost of reduced performance), you can set the broker property imq.persist.file.sync to
write data synchronously instead. For further discussion about this property, see “File-Based
Persistence” on page 81 and Table 14–5.

When you start a broker instance, you can use the imqbrokerd command’s -reset option to
clear the file system store. For more information about this option and its suboptions, see
“Broker Utility” on page 262.

Configuring a JDBC-Based Store

To configure a broker to use JDBC-based persistence, you set JDBC-related properties in the
broker’s 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 277 for more information.

92 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Configuring a Persistent Data Store

Note – Example configurations are available for HADB, Java DB (Apache Derby), Oracle, and
MySQL database products. The location of these files is platform-dependent, and is listed under
“Example applications and configurations” in the relevant tables of Appendix A,
“Platform-Specific Locations of Message Queue Data.” In addition, examples for Oracle are
provided as commented-out values in the instance configuration file, config.properties, and
for MySQL in the default broker configuration file, default.properties.

▼ To Configure a JDBC-Based Data Store

1 Set JDBC-related properties in the broker’s instance configuration file.

The relevant properties are discussed under “JDBC-Based Persistence” on page 82 and listed in
Table 14–6. In particular, you must set the broker’s imq.persist.store property to jdbc (see
“Persistence Properties” on page 290).

2 Place a copy of, or a symbolic link to, your JDBC driver’s .jar file in the following location,
depending on your platform:
Solaris: /usr/share/lib/imq/ext/
Linux: /opt/sun/mq/share/lib/
Windows: IMQ_VARHOME\\lib\\ext
For example, if you are using HADB on a Solaris system, the following command copies the
driver’s .jar file to the appropriate location:

cp /opt/SUNWhadb/4/lib/hadbjdbc4.jar /usr/share/lib/imq/ext
The following command creates a symbolic link instead:

ln -s /opt/SUNWhadb/4/lib/hadbjdbc4.jar /usr/share/lib/imq/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 277.

a. Change to the directory where the Database Manager utility resides, depending on your
platform:
Solaris: cd /usr/bin
Linux: cd /opt/sun/mq/bin
Windows: cd IMQ_HOME\\bin

b. Enter the imqdbmgr command:

imqdbmgr create all

Chapter 4 • Broker Configuration 93

Configuring a Persistent Data Store

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.

Displaying Information About the Persistent Store

The query subcommand of the Database Manager utility (imqdbmgr) displays information
about the persistent store, including the store version, the database user, and whether the
database tables have been created. Example 4–1 shows an example of the output.

EXAMPLE 4–1 Displaying Persistent Store Information

dbmgr query

[04/Oct/2005:15:30:20 PDT] Using plugged-in persistent store:

version=400
brokerid=Mozart1756
database connection url=jdbc:oracle:thin:@Xhome:1521:mqdb
database user=scott
Running in standalone mode.
Database tables have already been created.

Securing Persistent Data

The persistent 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 or JDBC-based data store.

Securing a File-Based Store

A broker using file-based persistence writes persistent data to a flat-file data store whose
location is platform-dependent (see Appendix A, “Platform-Specific Locations of Message
Queue Data”):

.../instances/instanceName/fs370

94 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Configuring a Persistent Data Store

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 directory’s 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 directory’s permissions can be set using the mechanisms provided by the
Windows operating system. This generally involves opening a Properties dialog for the
directory.

Securing a JDBC-Based 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 IMQ). 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 command’s
-dbuserand -dbpassword options (see “Broker Utility” on page 262).

For an embedded database that is accessed directly by the broker by means of the database’s
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 Store” on page 94
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.

Chapter 4 • Broker Configuration 95

96
 5
C H A P T E R

Broker Management
5

This chapter explains how to use the Message Queue Command utility (imqcmd) to manage a
broker and its services. The chapter has the following sections:
■ “Command Utility Preliminaries” on page 97
■ “Using the Command Utility” on page 98
■ “Managing Brokers” on page 100
■ “Managing Connection Services” on page 106
■ “Managing Connections” on page 109
■ “Managing Durable Subscriptions” on page 111
■ “Managing Transactions” on page 112

This chapter does not cover all topics related to managing a broker. Additional topics are
covered in the following separate chapters:
■ For information on managing physical destinations on the broker, such as how to create,
display, update, and destroy physical destinations and how to use the dead message queue,
see Chapter 6, “Physical Destinations.”
■ For information about setting up security for the broker, such as user authentication, access
control, encryption, and password files, see Chapter 9, “Security.”

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 other command line
utilities 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 management
commands.

97
Using the Command Utility

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, “Security” 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.
■ Set up and enable the ssladmin service on the target broker instance, if you want to use a
secure connection to the broker. For more information, see “Message Encryption” on
page 185.

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 266 for general
reference information about the syntax, subcommands, and options of the imqcmd command,
and Chapter 14, “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.

98 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Using the Command Utility

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

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.

Chapter 5 • Broker Management 99

Managing Brokers

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 user’s 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
This section describes how to use Command utility subcommands to perform the following
broker management tasks:
■ “Shutting Down and Restarting a Broker” on page 100
■ “Quiescing a Broker” on page 101
■ “Pausing and Resuming a Broker” on page 102
■ “Updating Broker Properties” on page 103
■ “Viewing Broker Information” on page 104

Shutting Down and Restarting a Broker

The subcommand imqcmd shutdown bkr shuts down a broker:

imqcmd shutdown bkr [-b hostName:portNumber]

[-time nSeconds]
[-nofailover]

100 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Managing Brokers

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 a high-availability cluster, it will not attempt to take over for any other broker
during the shutdown interval.

If the broker is part of a high-availability cluster (see “High-Availability Clusters” on page 148),
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 Takeover of a Broker” on page 163 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]

Chapter 5 • Broker Management 101

Managing Brokers

If the broker is part of a high-availability 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

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 106 and “Pausing and
Resuming a Physical Destination” on page 117.

The subcommand imqcmd resume bkr reactivates a broker’s 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):

102 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Managing Brokers

imqcmd resume bkr -u admin

Updating Broker Properties

The subcommand imqcmd update bkr changes the values of specified 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:
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 14, “Broker Properties Reference” for detailed information about these properties.

Chapter 5 • Broker Management 103

Managing Brokers

Viewing Broker Information

To display information about a single broker, use the imqcmd query bkr subcommand:

imqcmd query bkr -b hostName:portNumber

This lists the current settings of the broker’s properties, as shown in Example 5–1.

EXAMPLE 5–1 Broker Information Listing

Querying the broker specified by:

-------------------------
Host Primary Port
-------------------------
localHost 7676

Version 4.1
Instance Name imqbroker
Broker ID mybroker
Primary Port 7676

Current Number of Messages in System 0

Current Total Message Bytes in System 0

Current Number of Messages in Dead Message Queue 0

Current Total Message Bytes in Dead Message Queue 0

Log Dead Messages true

Truncate Message Body in Dead Message Queue false

Max Number of Messages in System unlimited (-1)

Max Total Message Bytes in System unlimited (-1)
Max Message Size 70m

Auto Create Queues true

Auto Create Topics true
Auto Created Queue Max Number of Active Consumers 1
Auto Created Queue Max Number of Backup Consumers 0

Cluster ID myClusterID
Cluster Is Highly Available true
Cluster Broker List (active)
Cluster Broker List (configured)
Cluster Master Broker
Cluster URL

Log Level INFO

Log Rollover Interval (seconds) 604800
Log Rollover Size (bytes) unlimited (-1)

104 Successfully
Sun queried
Java System Message the4.1
Queue broker.
Administration Guide • September 2007
 Managing Brokers

The imqcmd metrics bkr subcommand displays detailed metric information about a broker’s
operation:

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 5–2 shows an example of the resulting output.

EXAMPLE 5–2 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 336.

For brokers belonging to a broker cluster, the imqcmd list bkr subcommand displays
information about the configuration of the cluster; see “Displaying the Cluster Configuration”
on page 152 for more information.

Chapter 5 • Broker Management 105

Managing Connection Services

Managing Connection Services

Message Queue brokers support connections from both application clients and administrative
clients. See “Connection Services” on page 76 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 4–1. Subcommands are available for the following connection service management tasks:
■ “Pausing and Resuming a Connection Service” on page 106
■ “Updating Connection Service Properties” on page 107
■ “Viewing Connection Service Information” on page 107

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:

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]

106 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Managing Connection Services

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 5–1. See “Connection Properties” on page 283 for a description
of these properties.

TABLE 5–1 Connection Service Properties Updated by Command Utility

Property 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 Minimum number of threads assigned to the service

maxThreads 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

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

Chapter 5 • Broker Management 107

Managing Connection Services

Example 5–3 shows an example of the resulting output.

EXAMPLE 5–3 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

Example 5–4 shows an example of the resulting output.

EXAMPLE 5–4 Connection Service Information Listing

Service Name jms

Service State RUNNING
Port Number 60920 (dynamic)

Current Number of Allocated Threads 0

Current Number of Connections 0

Min Number of Threads 10

Max Number of Threads 1000

To display metric information about a connection service, use the imqcmd metrics svc
subcommand:

imqcmd metrics svc -n serviceName

[-b hostName:portNumber]

108 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Managing Connections

[-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
Example 5–5 shows an example of the resulting output.

EXAMPLE 5–5 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 338.

Managing Connections
The Command utility’s 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]

Chapter 5 • Broker Management 109

Managing Connections

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

Example 5–6 shows an example of the resulting output.

EXAMPLE 5–6 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

110 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Managing Durable Subscriptions

produces output like that shown in Example 5–7.

EXAMPLE 5–7 Connection Information Listing

Connection ID 421085509902214374
User guest
Service jms
Producers 0
Consumers 1
Host 111.22.333.444
Port 60953
Client ID
Client Platform

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

Managing Durable Subscriptions

Message Queue clients subscribing to a topic destination can register the subscription as
durable. A durable subscription has a unique, persistent identity and requires the broker to
retain messages addressed to it even when its message consumer 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 broker’s 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):

Chapter 5 • Broker Management 111

Managing Transactions

imqcmd list dur -d SPQuotes

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 5–8 shows an example.

EXAMPLE 5–8 Durable Subscription Information Listing

Name Client ID Number of Durable Sub

Messages State
----------------------------------------------------------------
myDurable myClientID 1 INACTIVE

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 5–8:

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 5–8:

imqcmd destroy dur -n myCurable -c myClientID

Managing Transactions
All transactions initiated by client applications are tracked by the broker. These can be simple
Message Queue transactions or distributed transactions managed by a distributed transaction
(XA resource) 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.

112 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Managing Transactions

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 5–9 shows an example of the resulting output.

EXAMPLE 5–9 Broker Transactions Listing

---------------------------------------------------------------
Transaction ID State User name # Msgs/ Creation time
# Acks
---------------------------------------------------------------

64248349708800 PREPARED guest 4/0 1/30/02 10:08:31 AM

64248371287808 PREPARED guest 0/4 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 5–10.

EXAMPLE 5–10 Transaction Information Listing

Client ID
Connection [email protected]:62209->jms:62195
Creation time 1/30/02 10:08:31 AM
Number of acknowledgments 0
Number of messages 4
State PREPARED
Transaction ID 64248349708800
User name guest
XID 6469706F6C7369646577696E6465723130313234313431313030373230

Chapter 5 • Broker Management 113

Managing Transactions

In case of broker failure, it is possible that a distributed transaction could be left in the prepared
state without ever being 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
may need to monitor such transactions and commit them or roll them back manually. For
example, if the broker’s imq.transaction.autorollback property (see Table 14–2) is set to
false, you must manually commit or roll back transactions found in the prepared state at broker
startup, using the Command utility’s 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 5–10:

imqcmd commit txn -n64248349708800

Note – Only transactions in the prepared state can be committed or 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.

114 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 6
C H A P T E R 6

Physical Destinations

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 maintains a specialized
physical destination, the dead message queue, whose properties differ somewhat from those of
other destinations. This chapter describes how to use the Message Queue Command utility
(imqcmd) to manage physical destinations.

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. Only the
broker to which a message was originally produced manages persistence and acknowledgment
for that message.

This chapter covers the following topics:

■ “Command Utility Subcommands for Physical Destination Management” on page 116
■ “Creating and Destroying Physical Destinations” on page 116
■ “Pausing and Resuming a Physical Destination” on page 117
■ “Purging a Physical Destination” on page 119
■ “Updating Physical Destination Properties” on page 119
■ “Viewing Physical Destination Information” on page 120
■ “Managing Physical Destination Disk Utilization” on page 123
■ “Dead Message Queue” on page 124

Note – For provider independence and portability, client applications typically use destination
administered objects to interact with physical destinations. Chapter 7, “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.

115
Command Utility Subcommands for Physical Destination Management

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 13, “Command Line Reference” for general
reference information about the syntax, subcommands, and options of the imqcmd command,
andChapter 15, “Physical Destination Property Reference” for specific information on the
configuration properties used to specify physical destination behavior.
Table 6–1 lists the imqcmd subcommands for physical destination management. For full
reference information about these subcommands, see Table 13–6.

TABLE 6–1 Physical Destination Subcommands for the Command Utility

Subcommand Description

create dst Create physical destination

destroy dst Destroy physical destination

pause dst Pause message delivery for physical destination

resume dst Resume message delivery for physical destination

purge dst Purge all messages from physical destination

compact dst Compact physical destination

update dst Set physical destination properties

list dst List physical destinations

query dst List physical destination property values

metrics dst 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.
The name must conform to the following rules:
■ It must contain only alphanumeric characters.
■ It must not contain spaces.
■ It must begin with an alphabetic character (A–Z, a–z), an underscore (_), or a dollar sign ($).

116 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Pausing and Resuming a Physical Destination

■ 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

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 15, “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 broker’s instance configuration file; see Table 14–3 for
information on these properties.)

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

To pause the delivery of messages to or from a physical destination, use the imqcmd pause dst
subcommand:

Chapter 6 • Physical Destinations 117

Pausing and Resuming a Physical Destination

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 Pause delivery from message producers to the destination
CONSUMERS Pause delivery from the destination to message consumers
ALL 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

118 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Updating Physical Destination Properties

Purging a Physical Destination

Purging a physical destination deletes all messages it is currently holding. You might want to do
this when a destination’s accumulated messages are taking up too much of the system’s
resources, such as when a queue is receiving messages but has no registered consumers to which
to deliver them, or when a topic’s 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

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 utility’s
-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 15–1 (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

Chapter 6 • Physical Destinations 119

Viewing Physical Destination Information

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]

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

120 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Viewing Physical Destination Information

Example 6–1shows an example of the resulting output. You can use the imqcmd update dst
subcommand (see “Updating Physical Destination Properties” on page 119) to change the value
of any of the properties listed.

EXAMPLE 6–1 Physical Destination Information Listing

------------------------------------
Destination Name Destination Type
------------------------------------
curlyQueue Queue

On the broker specified by:

-------------------------
Host Primary Port
-------------------------
localhost 7676

Destination Name curlyQueue

Destination Type Queue
Destination State RUNNING
Created Administratively true

Current Number of Messages 0

Current Total Message Bytes 0
Current Number of Producers 0
Current Number of Active Consumers 0
Current Number of Backup Consumers 0

Max Number of Messages unlimited (-1)

Max Total Message Bytes unlimited (-1)
Max Bytes per Message unlimited (-1)
Max Number of Producers 100
Max Number of Active Consumers 1
Max Number of Backup Consumers 0

Limit Behavior REJECT_NEWEST

Consumer Flow Limit 1000
Is Local Destination false
Local Delivery is Preferred false
Use Dead Message Queue true

To display metric information about a physical destination, use the imqcmd metrics dst
subcommand:

Chapter 6 • Physical Destinations 121

Viewing Physical Destination Information

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

Example 6–2 shows an example of the resulting output.

EXAMPLE 6–2 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 339.

122 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Managing Physical Destination Disk Utilization

Managing Physical Destination Disk Utilization

Because of the way message storage is structured in a file-based persistent data store (see
“File-Based Persistence” on page 81), disk space can become fragmented over time, resulting in
inefficient utilization of the available resources. Message Queue’s 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 destination’s 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 destination’s 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
Example 6–3 shows an example of the resulting output.

EXAMPLE 6–3 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]

Chapter 6 • Physical Destinations 123

Dead Message Queue

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 117):

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 destination’s reserved disk space continues to increase over time, try reconfiguring its
maxNumMsgs, maxBytesPerMsg, maxTotalMsgBytes, and limitBehavior properties (see
“Physical Destination Properties” on page 313).

Dead Message Queue

The dead message queue, mq.sys.dmq, is a system-created physical destination that holds the
dead messages of a broker and of its other 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 destination’s 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 destination’s 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 broker’s 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

124 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Dead Message Queue

message queue is system-created, you cannot create, pause, or destroy it. Also, as shown in
Table 6–2, default values for the dead message queue’s configuration properties sometimes
differ from those of ordinary queues.

TABLE 6–2 Dead Message Queue Treatment of Physical Destination Properties

Property Variant Treatment by Dead Message Queue

maxNumMsgs Default value is 1000, rather than −1 (unlimited) as for ordinary

queues.

maxTotalMsgBytes Default value is 10m (10 megabytes), rather than −1 (unlimited) as for
ordinary queues.

limitBehavior Default value is REMOVE_OLDEST, rather than REJECT_NEWEST as for

ordinary queues.
Flow control is not supported for the dead message queue.

maxNumProducers Does not apply to the dead message queue.

isLocalOnly Permanently set to false in broker clusters; the dead message queue
in a cluster is always a global physical destination.

localDeliveryPreferred Does not apply to the dead message queue.

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 broker’s
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:

Chapter 6 • Physical Destinations 125

Dead Message Queue

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.

126 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 7
C H A P T E R 7

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 127
■ “Administered Object Attributes” on page 130
■ “Using the Object Manager Utility” on page 137

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.

127
Object Stores

To use an LDAP server as your object store, you must specify the attributes shown in Table 7–1.
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 7–1 LDAP Object Store Attributes

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

128 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Object Stores

TABLE 7–1 LDAP Object Store Attributes (Continued)

Attribute 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 7–2. 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 7–2 File-system Object Store Attributes

Attribute 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 7 • Administered Objects 129

Administered Object Attributes

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 object’s 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 56.

Connection Factory Attributes

Client applications use connection factory administered objects to create connections with
which to exchange messages with a broker. A connection factory’s 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 connection’s 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 16, “Administered Object Attribute Reference” and are discussed in the following
sections below:
■ “Connection Handling” on page 130
■ “Client Identification” on page 133
■ “Reliability And Flow Control” on page 135
■ “Queue Browser and Server Sessions” on page 136
■ “Standard Message Properties” on page 136
■ “Message Header Overrides” on page 136

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

130 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Administered Object Attributes

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 “Connection Services” on page 76) and the method of
establishing a connection:
■ mq uses the broker’s 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 16–2.
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 16–2. Table 16–3 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.

Chapter 7 • Administered Objects 131

Administered Object Attributes

Note – Because high-availability clusters are self-configuring (see “Cluster Configuration

Properties” on page 150 and “Clustering High-Availability Brokers” on page 159), their
membership can change over time as brokers enter and leave the cluster. In this type of
cluster, the value of each member broker’s imqAddressList attribute is updated
dynamically so that it always reflects the cluster’s 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” on page 147), you
enable this behavior by setting the connection factory’s 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 factory’s 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 connection’s 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 a high-availability cluster (see “High-Availability Clusters” on page 148), another

broker can take over a failed broker’s 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 factory’s imqReconnectEnabled and
imqAddressListIterations attributes are ignored; the client runtime will simply iterate
through the address list indefinitely until it succeeds in reconnecting to a takeover broker. (Note

132 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Administered Object Attributes

that, as described in the preceding section, the address list is kept updated dynamically so that it
always reflects the current membership of the cluster.) The effect is equivalent to an
imqReconnectEnabled value of true and an imqAddressListIterations value of −1,
overriding any other explicit or default settings of these attributes. The only way for a client
application to avoid such indefinite reconnection attempts is to close the connection explicitly
on broker failure.
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 application’s 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 16–4 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 7 • Administered Objects 133

Administered Object Attributes

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 object’s 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 factory’s 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 factory’s
imqConfiguredClientID attribute is ${u}Hobbes, the client identifier assigned will be
u:CalvinHobbes.

134 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Administered Object Attributes

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
client’s 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 factory’s 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 16–5 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 tradeoff between reliability and
throughput; see “Client Runtime Message Flow Adjustments” on page 231 for further
discussion.

Chapter 7 • Administered Objects 135

Administered Object Attributes

Queue Browser and Server Sessions

Table 16–6 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 16–7 control whether the Message Queue client runtime sets certain of
these standard properties. For produced messages, these include the following:
JMSXUserID Identity of the user sending the message
JMSXAppID Identity of the application sending the message
JMSXProducerTXID Transaction identifier of the transaction within which the message was
produced

For consumed messages, they include

JMSXConsumerTXID Transaction identifier of the transaction within which the message was
consumed
JMSXRcvTimestamp Time the message was delivered to the consumer

Message Header Overrides

You can use the connection factory attributes listed in Table 16–8 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 Delivery mode (persistent or nonpersistent)
JMSExpiration Expiration time
JMSPriority Priority level

136 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 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 application’s designers or users.

Destination Attributes
The destination administered object that identifies a physical queue or topic destination has
only two attributes, listed in Table 16–9. 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.

Using the Object Manager Utility

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 Add an administered object to an object store
delete Delete an administered object from an object store
list List existing administered objects in an object store
query Display information about an administered object
update Modify the attributes of an administered object

See “Object Manager Utility” on page 275 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

Chapter 7 • Administered Objects 137

Using the Object Manager Utility

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 127 for information on the possible attributes and their values.
■ The type (-t) of the administered object
Possible types include the following:
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
■ The attributes (-o) of the administered object
See “Administered Object Attributes” on page 130 for information on the possible attributes
and their values.

Adding Administered Objects

The imqobjmgr command’s 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 non–Message 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.

138 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Using the Object Manager Utility

Adding a Connection Factory

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 7–1 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 7–1 Adding a Connection Factory

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

Chapter 7 • Administered Objects 139

Using the Object Manager Utility

The command shown in Example 7–2 adds an administered object to an LDAP object store
representing a topic destination with lookup name myTopic and physical destination name
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 7–2 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 7–3 shows the same command, but with the administered object stored in a Solaris file
system instead of an LDAP server.

EXAMPLE 7–3 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"

140 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Using the Object Manager Utility

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 7–4 deletes the object that was added in “Adding a Destination”
on page 139 above.

EXAMPLE 7–4 Deleting an Administered Object

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"
-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 7–5 shows how to list all administered objects
on an LDAP server.

EXAMPLE 7–5 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"

Chapter 7 • Administered Objects 141

Using the Object Manager Utility

Example 7–6 lists all queue destinations (type q).

EXAMPLE 7–6 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 7–7 displays information about an object whose lookup name is cn=myTopic.

EXAMPLE 7–7 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 object’s lookup name and location, and use the -o option to specify the new
attribute values.

142 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Using the Object Manager Utility

Example 7–8 changes the value of the imqReconnectAttempts attribute for the queue
connection factory that was added to the object store in Example 7–1.

EXAMPLE 7–8 Modifying an Administered Object’s 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.

Example 7–9 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 7–9 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

Chapter 7 • Administered Objects 143

Using the Object Manager Utility

As an example, consider the Object Manager command shown earlier in Example 7–1, which
adds a queue connection factory to an LDAP object store. This command can be encapsulated
in a command file as shown in Example 7–10. If the command file is named MyCmdFile, you can
then execute the command with the command line

imqobjmgr -i MyCmdFile

EXAMPLE 7–10 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 7–11 specifies only the attribute values for an LDAP object store.

EXAMPLE 7–11 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

144 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Using the Object Manager Utility

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 7–12.

EXAMPLE 7–12 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
your platform:
Solaris /usr/demo/imq/imqobjmgr
Linux /opt/sun/mq/examples/imqobjmgr
Windows IMQ_HOME\demo\imqobjmgr

Chapter 7 • Administered Objects 145

146
 8
C H A P T E R

Broker Clusters
8

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 with the volume of message traffic by distributing client connections among
multiple brokers. In addition, clusters help to maintain service availability: in the event of
broker failure, clients can fail over to another broker in the cluster and continue receiving
messages. High availability clusters provide an even greater degree of service availability: if one
of the brokers within the cluster should fail, another can take over ownership of its pending
messages and see that they are delivered to their destinations without interruption of service.
See the Message Queue Technical Overview for a general discussion of clusters and how they
operate.

This chapter describes how to manage broker clusters, connect brokers to them, and configure
them. It contains the following sections:
■ “Types of Cluster” on page 147
■ “Configuring Clusters” on page 149
■ “Managing Clusters” on page 154

Types of Cluster
Two types of cluster can be created: conventional and high availability (HA). The distinction
between the two depends on the value of the imq.cluster.ha property of the brokers belonging
to the cluster. All of the brokers in a given cluster must have the same value for this property: if
the value is false, the cluster is a conventional one; if true, it is a high-availability cluster.

Conventional Clusters
In a conventional cluster, each of the constituent brokers maintains its own separate persistent
data store (see “Persistence Services” on page 80). Brokers within the cluster share information
about one another’s persistent destinations, message consumers, and durable subscriptions.

147
Types of Cluster

However, if one of the brokers should fail, none of the other brokers in the cluster can take over
its operations, since none of them have access to the failed broker’s persistent messages, open
transactions, and other aspects of its internal state.
Changes to a cluster’s destinations, consumers, or durable subscriptions are automatically
propagated to all of the other brokers in the cluster. However, a broker that is offline at the time
of the change (through failure, for instance) will not immediately receive this information. To
keep such state information synchronized throughout the cluster, one of its brokers can
optionally be designated as the master broker to track changes in the cluster’s persistent state.
The master broker maintains a configuration change record containing information about
changes in the persistent entities associated with the cluster, such as durable subscriptions and
administrator-created physical destinations. All brokers in the cluster consult the master broker
during startup to update their information about these persistent entities; thus a broker
returning to operation after having been temporarily offline can update its information about
changes that may have occurred during its absence.

Note – While it is possible to mix brokers with different versions in the same cluster, all brokers
must have a version at least as great as that of the master broker. If there is no master broker, all
brokers in the cluster must have the same version.

Because all brokers in a conventional cluster need the master broker in order to perform
persistent operations, the following imqcmd subcommands for any broker in the cluster will
return an error when a master broker has been configured but is unavailable:
create dst
destroy dst
update dst
destroy dur
Auto-created physical destinations and temporary destinations are unaffected.
In the absence of a master broker, any client application attempting to create a durable
subscriber or unsubscribe from a durable subscription will get an error. However, a client can
successfully specify and interact with an existing durable subscription.

High-Availability Clusters
In a high-availability cluster, all of the brokers share a common JDBC-based persistent data
store holding dynamic state information (destinations, persistent messages, durable
subscriptions, open transactions, and so forth) for each broker. In the event of broker failure,
this enables another broker to assume ownership of the failed broker’s persistent state and
provide uninterrupted service to its clients. Because they share a common JDBC-based data
store, all brokers belonging to an HA cluster must have their imq.persist.store property (see
Table 14–4) set to jdbc.

148 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Configuring Clusters

Brokers within an HA cluster inform each other at regular intervals that they are still in
operation by exchanging heartbeat packets, (using a special internal connection service, the
cluster connection service), and updating their state information in the cluster’s shared
persistent store. When no heartbeat packet is detected from a broker for a specified number of
heartbeat intervals, the broker is considered suspect of failure. The other brokers in the cluster
then begin to monitor the suspect broker’s state information in the persistent store to confirm
whether the broker has indeed failed. If the suspect broker fails to update its state information
within a certain threshold interval, it is considered to have failed. (The duration of these
heartbeat and failure-detection intervals can be adjusted by means of broker configuration
properties to balance the tradeoff between speed and accuracy of failure detection: shorter
intervals result in quicker reaction to broker failure, but increase the likelihood of false
suspicions and erroneous failure detection.)

When a broker in an HA cluster detects that another broker has failed, it will attempt to take
over the failed broker’s persistent state (pending messages, destination definitions, durable
subscriptions, pending acknowledgments, and open transactions), in order to provide
uninterrupted service to the failed broker’s clients. If two or more brokers attempt such a
takeover, only the first will succeed; that broker acquires a lock on the failed broker’s data in the
persistent store, preventing subsequent takeover attempts by other brokers from succeeding.
After an initial waiting period, the takeover broker will then clean up any transient resources
(such as transactions and temporary destinations) belonging to the failed broker; these
resources will be unavailable if the client later reconnects.

Configuring Clusters
You define a cluster by specifying cluster configuration properties for each of its member
brokers. These properties are discussed below under “Cluster Configuration Properties” on
page 150 and are described in detail in Table 14–10.

Setting the Cluster Configuration

Like all broker properties, the 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. 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, you could include the following property in the instance
configuration files for all three brokers:

imq.cluster.brokerlist=host1:9876,host2:5000,ctrlhost

Notice, however, that if you need to change the cluster configuration, this method requires you
to update 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 shared cluster configuration

Chapter 8 • Broker Clusters 149

Configuring Clusters

properties into a central cluster configuration file that all of the individual brokers reference.
This prevents the settings from getting out of agreement and ensures that all brokers in a cluster
share the same, consistent configuration information. In this approach, each broker’s instance
configuration file must set the imq.cluster.url property to point to the location of the cluster
configuration file: for example,

imq.cluster.url=file:/home/cluster.properties

The cluster configuration file then defines the shared configuration properties for all of the
brokers in the cluster, such as the list of brokers to be connected (imq.cluster.brokerlist),
the transport protocol to use for the cluster connection service (imq.cluster.transport),
and optionally, for conventional clusters, the address of the master broker
(imq.cluster.masterbroker). The following code defines the same conventional cluster as in
the previous example, with the broker running on ctrlhost serving as the master broker:

imq.cluster.brokerlist=host1:9876,host2:5000,ctrlhost
imq.cluster.masterbroker=ctrlhost

Cluster Configuration Properties

As shown above, the most important cluster configuration property in a conventional cluster is
imq.cluster.brokerlist, a list of broker addresses defining the membership of the cluster; all
brokers in the cluster must have the same value for this property. (By contrast, high-availability
clusters are self-configuring: any broker configured to use the cluster’s shared store is
automatically registered as part of the cluster, without further action on your part. If
imq.cluster.brokerlist is specified for an HA broker, it is ignored and a warning message is
logged at broker startup.)

Additional cluster configuration properties include the following:

■ imq.cluster.ha is a boolean flag specifying whether the broker is a high-availability broker.
■ imq.cluster.url specifies the location of the cluster configuration file, if any.
■ imq.cluster.hostname gives the host name or IP address for the cluster connection
service, used for internal communication between brokers in the cluster. This setting can be
useful if more than one host is available: for example, if there is more than one network
interface card installed in a computer.
■ imq.cluster.port gives 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.transport specifies the transport protocol used by the cluster connection
service, such as tcp or ssl.
■ imq.cluster.masterbroker (conventional clusters only) designates which broker (if any) is
the master broker that keeps track of state changes.

150 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Configuring Clusters

■ imq.cluster.clusterid (HA clusters only) gives the cluster identifier, which will be
appended to the names of all database tables in the cluster’s 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.

Caution – While the hostname and port properties can be set independently for each individual
broker, all of the other properties listed above must have the same values for all brokers in the
cluster. In addition, in an HA cluster, you must specify a unique broker identifier for each broker
by setting the broker’s imq.brokerid property (see Table 14–1); this value must be different for
each broker in the cluster.

Brokers in a high-availability cluster have additional properties relating to persistent store

configuration, failure detection, and takeover, which are discussed in the following sections.

JDBC Configuration Properties for HA Clusters

The persistent data store for an HA cluster is maintained on a high-availability database server,
using the Java Database Connectivity (JDBC) API (see “JDBC-Based Persistence” on page 82).
All brokers belonging to such a cluster must therefore have their imq.persist.store property
(see Table 14–4) set to jdbc. The remaining persistent store properties are discussed under
“JDBC-Based Persistence” on page 82 and summarized in Table 14–6.

The database server may be Sun’s own High Availability Database (HADB) server, or it may be
an open-source or third-party product such as Apache Software Foundation’s Derby (Java DB)
or Oracle Corporation’s Real Application Clusters (RAC). As described in “JDBC-Based
Persistence” on page 82, 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: for instance, when using Sun’s HADB for the HA server, the Java class name of
the JDBC driver is specified by a property named imq.persist.jdbc.hadb.driver.

Note – 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 message
brokers), the Application Server will automatically propagate these properties to each broker in
the HA 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
properties explicitly for each broker.

After setting all of the needed JDBC configuration properties for the brokers in an HA cluster,
you must also install your JDBC driver’s .jar file in the appropriate directory location,
depending on your operating-system platform (as listed in Appendix A, “Platform-Specific
Locations of Message Queue Data”) and then execute the Database Manager command

imqdbmgr create tbl

Chapter 8 • Broker Clusters 151

Configuring Clusters

to create the database schema for the HA persistent data store.

Failure Detection and Takeover Properties for HA Clusters

The following configuration properties (listed in Table 14–10) specify the parameters for the
exchange of heartbeat and status information within an HA cluster:
■ imq.cluster.heartbeat.hostname gives the host name (or IP address) for the heartbeat
connection service.
■ imq.cluster.heartbeat.port gives the port number for the heartbeat connection service.
■ imq.cluster.heartbeat.interval defines 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 defines the interval, in seconds, at which to monitor a
suspect broker’s 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.

Displaying the Cluster Configuration

To display information about a cluster’s configuration, use the Command utility’s list bkr
subcommand:

imqcmd list bkr

152 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Configuring Clusters

This lists the current status of all brokers included in the cluster to which a given broker
belongs, as shown in Example 8–1 (for a conventional cluster) or Example 8–2 (for an HA
cluster).

EXAMPLE 8–1 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 False

-------------------------
Address State
---------------------
whippet:7676 OPERATING
greyhound:7676 OPERATING

EXAMPLE 8–2 Configuration Listing for an HA 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 myClusterID
Cluster Is Highly Available 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

Chapter 8 • Broker Clusters 153

Managing Clusters

Managing Clusters
The following sections describe how to perform various administrative management tasks for
conventional and high-availability clusters, respectively.

Managing Conventional Clusters

The procedures in this section show how to perform the following tasks for a conventional
cluster:
■ “Clustering Conventional Brokers” on page 154
■ “Adding Brokers to a Conventional Cluster” on page 156
■ “Removing Brokers From a Conventional Cluster” on page 157
■ “Managing the Configuration Change Record” on page 158

Clustering Conventional Brokers

There are two general methods of connecting conventional brokers into a 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.

Note – Whichever clustering method you use, 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 /etc/nsswitch.conf to change the order of the
entries so that DNS lookup is performed before consulting the local hosts file. The line in
/etc/nsswitch.conf should read as follows:

hosts: dns files

154 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Managing Clusters

Note – If you are clustering a Message Queue 4.1 broker together with those from earlier versions
of Message Queue, you must set the value of the 4.1 broker’s
imq.autocreate.queue.maxNumActiveConsumers property to 1. Otherwise the brokers will
not be able to establish a cluster connection.

▼ To Cluster Conventional 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

2 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 Cluster Conventional Brokers Using a Cluster Configuration File

An alternative method, better suited for production systems, is to use a cluster configuration file
to specify the composition 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.

2 For each broker in the cluster, set the imq.cluster.url property in the broker’s instance
configuration file to point to the cluster configuration file.

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

▼ 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
Encryption”on page 185.

Chapter 8 • Broker Clusters 155

Managing Clusters

2 Set each broker’s 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 Add the new broker to the imq.cluster.brokerlist property in the cluster configuration file.

2 Issue the following command to any broker in the cluster:

imqcmd reload cls
This forces each broker to reload the cluster configuration, ensuring that all persistent
information for brokers in the cluster is up to date. Note that 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.

3 (Optional) Set the value of the imq.cluster.url property in the new broker’s instance
configuration file (config.properties) to point to the cluster configuration file.

4 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 broker’s 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)

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

156 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Managing Clusters

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 from the command line or by means of a central cluster
configuration file.

▼ 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 Stop each broker in the cluster, using the imqcmd command.

2 Restart the brokers that will remain in the cluster, using the imqbrokerd command’s -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

▼ 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 isn’t 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.

2 Issue the following command to each broker remaining in the cluster:

imqcmd reload cls
This forces the brokers to reload the cluster configuration.

3 Stop the broker you’re removing from the cluster.

Chapter 8 • Broker Clusters 157

Managing Clusters

4 Edit that broker’s instance configuration file (config.properties), removing or specifying a

different value for its imq.cluster.url property.

Managing the 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 cluster’s 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 cluster’s 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 Shut down all brokers in the cluster.

2 Restore the master broker’s configuration change record from the backup file.
The command is
imqbrokerd -restore mybackuplog

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

4 Restart all brokers in the cluster.

158 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Managing Clusters

Managing High-Availability Clusters

This section presents step-by-step procedures for performing a variety of administrative tasks
for a high-availability cluster:
■ “Clustering High-Availability Brokers” on page 159
■ “Adding and Removing Brokers in a High-Availability Cluster” on page 162
■ “Preventing or Forcing Takeover of a Broker” on page 163
■ “Managing the HA Data Store” on page 164

Clustering High-Availability Brokers

Because high-availability 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 broker’s
configuration properties appropriately and then start the broker; as long as its properties are set
properly, it will automatically be incorporated into the cluster. Table 8–1 shows the required
settings. In addition, there may be vendor-specific settings required for a particular vendor’s
database; Table 8–2 and Table 8–3 show these vendor-specific settings for Sun’s own HADB and
MySQL from MySQLAB, respectively.

TABLE 8–1 Required Configuration Properties for HA Clusters

Property Required Value Description

imq.cluster.ha true Broker is part of an HA cluster

imq.cluster.clusterid Cluster identifier

Must be the same for all brokers in the cluster.

imq.brokerid Broker identifier

Must be different for each broker in the cluster

imq.persist.store jdbc Model for persistent data storage

Only JDBC-based persistence is supported for HA
data stores.

imq.persist.jdbc.dbVendor Database vendor for HA persistent store:

hadb: HADB (Sun Microsystems, Inc.)
derby: Java DB (Derby, Apache Software
Foundation)
oracle: Oracle Real Application Cluster (Oracle
Corporation)
mysql: MySQL (MySQL AB)

Chapter 8 • Broker Clusters 159

Managing Clusters

TABLE 8–2 Vendor-Specific Configuration Properties for HADB Database

Property Description

imq.persist.jdbc.hadb.user User name for opening database connection

imq.persist.jdbc.hadb.password Password for opening database connection

imq.persist.hadb.property.serverList JDBC URL of database

Use the command
hadbm get JdbcURL
to get the URL; remove the prefix
jdbc:sun:hadb
and use
host:port,host:port...
for the property value.

TABLE 8–3 Vendor-Specific Configuration Properties for MySQL Database

Property Description

imq.persist.jdbc.mysql.user User name for opening database connection

imq.persist.jdbc.mysql.password Password for opening database connection

imq.persist.jdbc.mysql.property.url JDBC URL for opening database

The property values can be set separately in each broker’s instance configuration file, or they can
be specified in a cluster configuration file that all the brokers share. The procedures are as
follows:

▼ To Cluster HA Brokers Using Instance Configuration Files

1 For each broker in the cluster:

a. Start the broker with 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.

160 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Managing Clusters

c. Edit the instance configuration file to specify the broker’s HA-related configuration
properties.
Table 8–1 shows the required property values.

d. Specify any additional, vendor-specific properties that may be needed.

Table 8–2 and Table 8–3 show the required properties for HADB and MySQL databases,
respectively.

2 Place a copy of, or a symbolic link to, your JDBC driver’s .jar file in the appropriate location,
depending on your platform:
Solaris: /usr/share/lib/imq/ext/
Linux: /opt/sun/mq/share/lib/
Windows: IMQ_VARHOME\lib\ext

3 Create the database schema needed for Message Queue persistence.

Use the imqdbmgr create tbl command; see “Database Manager Utility” on page 277.

4 Restart each broker with the imqbrokerd command.

The brokers will automatically register themselves into the cluster on startup.

▼ To Cluster HA Brokers Using a Cluster Configuration File

An alternative method, better suited for production systems, is to use a cluster configuration file
to specify the composition of the cluster:

1 Create a cluster configuration file specifying the cluster’s HA-related configuration properties.
Table 8–1 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.

2 Specify any additional, vendor-specific properties that may be needed.

Table 8–2 and Table 8–3 show the required properties for HADB and MySQL databases,
respectively.

3 For each broker in the cluster:

a. Start the broker with 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.

Chapter 8 • Broker Clusters 161

Managing Clusters

c. Edit the instance configuration file to specify the location of the cluster configuration file.
In the broker’s 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 broker’s unique
broker identifier. This value must be different for each broker.

4 Place a copy of, or a symbolic link to, your JDBC driver’s .jar file in the appropriate location,
depending on your platform:
Solaris: /usr/share/lib/imq/ext/
Linux: /opt/sun/mq/share/lib/
Windows: IMQ_VARHOME\lib\ext

5 Create the database schema needed for Message Queue persistence.

Use the imqdbmgr create tbl command; see “Database Manager Utility” on page 277.

6 Restart each broker with the imqbrokerd command.

The brokers will automatically register themselves into the cluster on startup.

Adding and Removing Brokers in a High-Availability Cluster

Because HA 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 HA Cluster

1 Set the new broker’s HA-related properties, as described in the preceding section.
You can do this either by specifying the individual properties in the broker’s instance
configuration file (config.properties) or, if there is a cluster configuration file, by setting the
broker’s imq.cluster.url property to point to it.

2 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 HA Cluster

1 Make sure the broker is not running.

If necessary, use the command
imqcmd shutdown bkr
to shut down the broker.

162 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Managing Clusters

2 Remove the broker from the cluster with the command

imqdbmgr remove bkr

Preventing or Forcing Takeover of a Broker

Although the takeover of a failed broker’s persistent data by another broker in an HA cluster is
normally automatic, there may be times when you want to prevent such a takeover from
occurring. To suppress automatic takeover 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 takeover to occur manually. (This might
be necessary, for instance, if an automatic takeover broker were to fail before completing the
takeover process.) In such cases, you can initiate a takeover 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.

You may also find it useful to quiesce a broker before shutting it down, causing it to refuse any
new client connections while continuing to service old ones. This allows the broker’s operations
to wind down gradually without triggering a takeover by another broker, for instance in
preparation for shutting it down administratively for upgrade or similar purposes; see
“Quiescing a Broker” on page 101 for more information.

Chapter 8 • Broker Clusters 163

Managing Clusters

Managing the HA Data Store

When converting to high-availability operation, you can use the Message Queue Database
Manager utility (imqdbmgr) subcommand

imqdbmgr upgrade hastore

to convert an existing standalone HADB persistent data store to a shared HADB store. You can
use this command in the following cases:
■ Moving from a Message Queue 4.0 standalone HADB store to a Message Queue 4.1 shared
HADB store. In this case, the broker will automatically upgrade the store. You can then run
the imqdbmgr upgrade hastore command to convert the upgraded data store for shared use.
■ Moving from a standalone Message Queue 4.1 HADB store to a shared HADB store. In this
case, you just need to run the imqdbmgr upgrade hastore command to convert the data
store for shared use.

Because this command only supports conversion of HADB stores, it cannot be used to convert
file-based stores or other JDBC-based stores to a shared HADB store. If you were previously
running a 3.x version of Message Queue, you must create an HADB store and then manually
migrate your data to that store in order to use the high availability feature.

For durability and reliability, it is a good idea to back up a high-availability cluster’s shared
persistent 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

164 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 9
C H A P T E R

Security
9

This chapter describes Message Queue’s facilities for security-related tasks such as
authenticating users, defining access control, configuring a Secure Socket Layer (SSL)
connection service to encrypt client-broker communication, and setting up a password file for
use in broker startup. In addition to Message Queue’s own built-in authentication mechanisms,
you can also plug in a preferred external authentication service based on the Java
Authentication and Authorization Service (JAAS) API.

This chapter includes the following sections:

■ “User Authentication” on page 165
■ “User Authorization” on page 180
■ “Message Encryption” on page 185
■ “Password Files” on page 193
■ “Connecting Through a Firewall” on page 195

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

165
User Authentication

■ 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.
■ An external authentication mechanism plugged into Message Queue by means of the Java
Authentication and Authorization Service (JAAS) API.

See “Using a Flat-File User Repository” on page 166, “Using an LDAP User Repository” on
page 172, and “Using JAAS-Based Authentication” on page 174 for information on these three
types of authentication mechanism.

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, “Platform-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 180. A user’s 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.

The flat-file user repository provides three predefined groups:

admin For broker administrators. By default, users in this group are granted the access
privileges needed to configure, administer, and manage message brokers.
user 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.

166 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 User Authentication

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

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
user’s status to inactive rescinds all of that user’s 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 9–1:
■ 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 User’s Password” on
page 170).
■ 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.

TABLE 9–1 Initial Entries in Flat-File User Repository

User Name Password Group Status

admin admin admin Active

guest guest anonymous Active

Using the User Manager Utility

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

Chapter 9 • Security 167

User Authentication

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 9–2 lists the subcommands of the imqusermgr command. For full reference information
about these subcommands, see Table 13–15.

TABLE 9–2 User Manager Subcommands

Subcommand Description

add Add user and password to repository

delete Delete user from repository

update Set user’s password or active status (or both)

list Display user information

The general options listed in Table 9–3 apply to all subcommands of the imqusermgr command.

TABLE 9–3 General User Manager Options

Option Description

-f Perform action without user confirmation

-s Silent mode (no output displayed)

-v Display version information1

-h Display usage help1

1
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

168 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 User Authentication

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

Chapter 9 • Security 169

User Authentication

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 User’s Password

You can use the subcommand imqusermgr update to change a user’s 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

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 user’s active status:

170 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 User Authentication

imqusermgr update [-i brokerName]

-u userName -a activeStatus

The -u identifies the user; -a is a boolean value specifying the user’s 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 AliBaba’s 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]

The command

imqusermgr list -u AliBaba

displays information about user AliBabe, as shown in Example 9–1.

EXAMPLE 9–1 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

Chapter 9 • Security 171

User Authentication

the command lists information about all users in the repository, as in Example 9–2.

EXAMPLE 9–2 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 broker’s 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.
■ 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 14–8 for more
detailed information:

imq.user_repository.ldap.server
imq.user_repository.ldap.principal

172 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 User Authentication

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
■ If you want the broker to use a secure, encrypted SSL (Secure Socket Layer) connection for
communicating with the LDAP server, set the broker’s
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

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 broker’s access control file to
match those defined in the LDAP user repository; see “User Authorization” on page 180 for
more information.

To create administrative users, you use the access control file to specify users and groups that
can create ADMIN connections. These users and groups must be predefined in the LDAP
directory.

Any user or group who can create an ADMIN connection can issue administrative commands.

▼ To Set Up an Administrative User

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.

2 Open the access control file, accesscontrol.properties. The location for the file is listed in
Appendix A,“Platform-Specific Locations of Message Queue Data”
The file contains an entry such as the following:

Chapter 9 • Security 173

User Authentication

service connection access control

##################################
connection.NORMAL.allow.user=*
connection.ADMIN.allow.group=admin
The entries listed are examples. Note that the admin group exists in the file-based user
repository but does not exist by default in the LDAP directory. You must substitute the name of
a group that is defined in the LDAP directory, to which you want to grant Message Queue
administrator privileges.

3 To grant Message Queue administrator privileges to users, enter the user names as follows:
connection.ADMIN.allow.user= userName[[,userName2] …]

4 To grant Message Queue administrator privileges to groups, enter the group names as follows:
connection.ADMIN.allow.group= groupName[[,groupName2] …]

Using JAAS-Based Authentication

The Java Authentication and Authorization Service (JAAS) APIallows 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 Developer’s 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 Queue’s 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.

174 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 User Authentication

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

Elements of JAAS
Figure 9–1 shows the basic elements of JAAS: a JAAS client, a JAAS-compliant authentication
service, and a JAAS configuration file.
■ The JAAS client is an application wishing to perform authentication using a
JAAS-compliant authentication service. It communicates with this 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 relevant information.
■ 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 another module that provides the logic.
■ The JAAS configuration file is a text file that the JAAS client uses to locate the login
module(s) for communicating with the authentication service.

JAAS Client JAAS

Login Context Configuration
Call Back Handler File

LoginModule
Authentication
Service
Authentication
Logic

User
Repository

FIGURE 9–1 JAAS Elements

JAAS and Message Queue

Figure 9–2 shows how JAAS is used by the Message Queue broker. It shows a more complex
implementation of the JAAS model shown in Figure 9–1.

Chapter 9 • Security 175

User Authentication

Message Queue
Broker
Message (JAAS Client)
Queue VM
Client
Login Context
Call Back Handler

LoginModule2 LoginModule3
LoginModule1 (Authentication (Authentication
Logic) Logic)

Authentication
Logic

User User User

Repository Repository Repository

FIGURE 9–2 How Message Queue Uses JAAS

As in the simpler case, the authentication service layer is separate from the broker. The
authentication service consists of one or more login modules, along with additional
authentication modules if needed. The login modules run in the same Java virtual machine as
the broker. The Message Queue broker is represented to the login module as a 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 to the login
modules. The configuration file specifies the order in which the modules are to be used and
some conditions for their use. When the broker starts up, JAAS locates the configuration file by
consulting either the Java system property java.security.auth.login.config or the Java
security properties file. It then selects an entry in the JAAS configuration file according to the
value of the broker property imq.user_repository.jaas.name. That entry specifies which
login modules will be used for authentication. As the figure shows, it is possible for the broker to
use more than one login module. (The relation between the configuration file, the login module,
and the broker is shown in Figure 9–3.)

The fact that the broker uses a JAAS plug-in authentication service remains completely
transparent to the Message Queue client. The client continues to connect to the broker as it did
before, passing a user name and password. In turn, the broker uses a callback handler to pass
this information to the authentication service, and the service uses the information to

176 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 User Authentication

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.

This section illustrates how the JAAS client, the login modules, and the JAAS configuration file
are related and then describes the process required to set up JAAS-compliant authentication.
The next figure shows the relation between the configuration file, the login module, and the
broker.
MyJAASCFile.config
MyEntry1{ Location of the configuration
com.some.module.MyLoginModule1 required file is specified with the Java
debug=true system property
com.some.module.MyLoginModule2 optional java.security.auth.login.config
debug=true }

Entry point into the configuration

file is specified with the broker property
imq.user_repository.jaas.name=MyEntry1

In lib/ext directory,
LoginModule classes
LoginModule1.java
are dynamically loaded
by the broker

MyCallBackHandler Authentication service

communicates with Broker
using MyCallBackHandler

Broker

FIGURE 9–3 Setting Up JAAS Support

As shown in the figure, the JAAS configuration file, MyJAASCFile.config contains references to
several login modules, grouped in an entry point. The JAAS locates the configuration file by
consulting the Java system property java.security.auth.login.config or the Java security

Chapter 9 • Security 177

User Authentication

properties file. The broker then determines which login modules to use by consulting the
broker property imq.user_repository.jaas.name, which specifies the desired entry in the
configuration file. The classes for those modules are found in the lib/ext directory.
To set up JAAS support for Message Queue, you must complete the following steps. (In a
development environment all these steps might be done by the developer. In a production
environment, the administrator would take over some of these tasks.)
1. Create one or more login module classes that implement the authentication service. The
JAAS callback types that the broker supports are listed below.
javax.security.auth.callback.LanguageCallback
The broker uses this callback to pass the authentication service the locale in which the
broker is running This value can be used for localization.
javax.security.auth.callback.NameCallback
The broker uses this callback to pass to the authentication service the user name specified
by the Message Queue client when the connection was requested.
javax.security.auth.callback.TextInputCallback
The broker uses this callback to pass the value of imq.authentication.type to the
authentication service when the TextInputCallback.getPrompt() is
imq.authentication.type. Right now, the only possible value for this field is basic. This
indicates Base-64 password encoding.
javax.security.auth.callback.PasswordCallback
The broker uses this callback to pass to the authentication service the password specified
by the Message Queue client when the connection was requested.
javax.security.auth.callback.TextOutputCallback
The broker 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 and
specify the location of this file to the Message Queue administrator. (The file can be located
remotely, and its location can be specified with a URL.)
3. Note the name of the entry (that references the login implementation classes) in the JAAS
configuration file.
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. Configure the broker properties that relate to JAAS support. These are described in
Table 9–4.
6. Set the following system property (to specify the location of the JAAS configuration file)
when starting the broker.
java.security.auth.login.config=JAAS_Config_File_Location

178 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 User Authentication

For example, you can specify the configuration file when you start the broker.
imqbrokerd -Djava.security.auth.login.config=JAAS_Config_File_Location
There are other ways to specify the location of the JAAS configuration file. For additional
information, please see
http://java.sun.com/
j2se.1.5.0/docs/guide/security/jaas/tutorials/LoginConfigFile.html

The following table lists the broker properties that need to be set to set up JAAS support.

TABLE 9–4 Broker Properties for JAAS Support

Property Description

imq.authentication.type Set to basic to indicate Base-64 password encoding.

This is the only permissible value for JAAS
authentication.

imq.authentication.basic.user_repository Set to jaas to specify JAAS authentication.

imq.accesscontrol.type Set to file.

imq.user_repository.jaas.name Set to the name of the desired entry (in the JAAS
configuration file) that references the login modules
you want to use as the authentication mechanism.
This is the name you noted in Step 3.

imq.user_repository.jaas.userPrincipalClass This property, used by Message Queue access control,

specifies the java.security.Principal
implementation class in the login module(s) that the
broker uses to extract the Principal name to represent
the user entity in the Message Queue access control
file. If, it is not specified, the user name passed from
the Message Queue client when a connection was
requested is used instead.

imq.user_repository.jaas.userPrincipalClass This property, used by Message Queue access control,

specifies the java.security.Principal
implementation class in the login module(s) that the
broker uses to extract the Principal name to represent
the 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.

Chapter 9 • Security 179

User Authorization

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

If access control is enabled (that is, if the broker’s 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, “Platform-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 9–5 describes the various elements.

180 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 User Authorization

TABLE 9–5 Authorization Rule Elements

Element Description

resourceType Type of resource to which rule applies:

connection: Connections
queue: Queue destinations
topic: Topic destinations

resourceVariant Specific resource (connection service type or destination) to which 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 rule applies; see pertinent sections below for possible values

access Level of access authorized:

allow: Authorize user to perform operation
deny: Prohibit user from performing operation

principalType Type of principal (user or group) to which rule applies:

user: Individual user
group: User group

principals List of principals (users or groups) to whom 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.

For example, the authorization rule

queue.q1.consume.allow.user=*

allows all users to consume messages from the queue destination q1. The rule

queue.*.consume.allow.user=Snoopy

allows user Snoopy to consume messages from all queue destinations. The rule

topic.t1.produce.deny.user=Snoopy

prevents Snoopy from producing messages to the topic destination t1.

Chapter 9 • Security 181

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

182 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 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 broker’s
connection services. The rule’s resourceVariant element specifies the service type of the
connection services to which the rule applies, as shown in Table 4–1; 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 it
is enabled, access to these services is controlled by the authorization rules in the access control
file.

Chapter 9 • Security 183

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 broker’s
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 (producing) messages to a queue
■ Receiving (consuming) messages from a queue
■ Publishing (producing) messages to a topic
■ Subscribing to (consuming messages from) a topic
■ Browsing a queue

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.

The final section of the access control file, includes authorization rules that specify for which
users and groups the broker will auto-create a physical destination.

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 broker’s
imq.autocreate.queue or imq.autocreate.topic property is set to true). A separate section
of the access control file controls the ability of users and groups to perform such auto-creation.
This is governed by authorization rules with a resource type of queue or topic and an operation
element of create. the resourceVariant element is omitted, since these rules apply to all queues
or all 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. You can
edit the file to restrict such authorization for specific users. For example, the rule

topic.create.deny.user=Snoopy

184 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Message Encryption

denies user Snoopy the ability to auto-create topic destinations.

Note – Note that 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 sends encrypted messages between clients and broker. 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 service is used internally to provide secure, encrypted communication
between brokers in a cluster, using the TCP/IP transport protocol.

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.

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 steps described in this section and then
follow them with the additional ones in “Using Signed Certificates” on page 191.

Chapter 9 • Security 185

Message Encryption

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. The following procedure shows the steps needed to set up an SSL-based connection
service to use self-signed certificates. The subsections that follow describe each of these steps in
greater detail.

▼ To Set Up an SSL-Based Connection Service Using Self-Signed

Certificates
1 Generate a self-signed certificate.

2 Enable the ssljms, ssladmin, or cluster connection service in the broker.

3 Start the broker.

4 Configure and run the client.

This step applies only to the ssljms connection service and not to ssladmin or cluster.

Generating a Self-Signed Certificate

Run the Key Tool utility (imqkeytool) to generate a self-signed certificate for the broker. (On
UNIX systems, you may need to run the utility as the root user in order to have permission to
create the key store.) The same certificate can be used for the ssljms, ssladmin, or cluster
connection service.

Enter the following at the command prompt:

imqkeytool -broker

The Key Tool utility prompts you for a key store password:

Generating keystore for the broker ...

Enter keystore password:

Next, the utility prompts you for identifying information from which to construct an X.500
distinguished name. Table 9–6 shows the prompts and the values to be provided for each.
Values are case-insensitive and can include spaces.

TABLE 9–6 Distinguished Name Information Required for a Self-Signed Certificate

Prompt X.500 Attribute Description Example

What is your first and last commonName (CN) Fully qualified name of server running mqserver.sun.com
name? the broker

186 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Message Encryption

TABLE 9–6 Distinguished Name Information Required for a Self-Signed Certificate (Continued)
Prompt X.500 Attribute Description Example

What is the name of your organizationalUnit (OU) Name of department or division purchasing
organizational unit?

What is the name of your organizationName (ON) Name of larger organization, such as a Acme Widgets, Inc.
organization? company or government entity

What is the name of your city localityName (L) Name of city or locality San Francisco
or locality?

What is the name of your state stateName (ST) Full (unabbreviated) name of state or California
or province? province

What is the two-letter country (C) Standard two-letter country code US

country code for this unit?

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 when
you start the broker, to allow the broker to open the key store. You can store the key store
password in a password file (see “Password Files” on page 193).

The Key Tool utility generates a self-signed certificate and places it in Message Queue’s key
store. The key store is located in a directory whose location depends upon the operating system
platform, as shown in Appendix A, “Platform-Specific Locations of Message Queue Data.”
The following are the configurable properties for the Message Queue key store for SSL-based
connection services:
imq.keystore.file.dirpath Path to directory containing key store file (see Appendix A,
“Platform-Specific Locations of Message Queue Data” for
default value)
imq.keystore.file.name Name of key store file
imq.keystore.password Key store password

Chapter 9 • Security 187

Message Encryption

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 key store
password when you generated the self-signed certificate.)

▼ To Regenerate a Key Pair

1 Remove the broker’s key store, located as shown in Appendix A,“Platform-Specific Locations of
Message Queue Data.”

2 Run imqkeytool again to generate a new key pair, as described above.

Enabling an SSL-Based Connection Service

To enable an SSL-based connection service in the broker, you need to add ssljms (or ssladmin)
to the imq.service.activelist property.

▼ To Enable an SSL-Based Service in the Broker

1 Open the broker’s 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,
“Platform-Specific Locations of Message Queue Data”):
.../instances/instanceName/props/config.properties

2 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 “Clustering Conventional
Brokers” on page 154.

3 Save and close the instance configuration file.

188 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Message Encryption

Starting the Broker

Start the broker, providing the key store password. You can provide the password in either of
two ways:
■ Put the password in a password file, as described in “Password Files” on page 193. Then set
the property imq.passfile.enabled = true and do one of the following:
■ Pass the location of the password file to the imqbrokerd command:

imqbrokerd -passfile /passfileDirectory/passfileName

■ 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
■ Allow the broker to prompt you for the password when it starts up:

imqbrokerd
Please enter Keystore 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.

Configuring and Running an SSL-Based Client

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

If you are using a version of the Java 2 Software Development Kit (J2SDK) earlier than 1.4, you
must also include the following Java Secure Socket Extension (JSSE) and Java Naming and
Directory Interface (JNDI) .jar files:

Chapter 9 • Security 189

Message Encryption

jsse.jar
jnet.jar
jcert.jar
jndi.jar

(It is not necessary to include these files if you are using J2SDK 1.4 or later, which has JSSE and
JNDI support built in.)

Once the CLASSPATH files are properly specified, one way to start the client and connect to the
broker’s 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 adminName -secure

where adminName is a valid entry in the Message Queue user repository. The command will
prompt you for the password. (If you are using a flat-file repository, see “Changing a User’s
Password” on page 170.)

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 9–3.

EXAMPLE 9–3 Connection Services Listing

Listing all the services on the broker specified by:

Host Primary Port

localhost 7676

Service Name Port Number Service State

admin 33984 (dynamic) RUNNING
httpjms - UNKNOWN
httpsjms - UNKNOWN
jms 33983 (dynamic) RUNNING
ssladmin 35988 (dynamic) RUNNING
ssljms dynamic UNKNOWN

Successfully listed services.

190 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Message Encryption

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 not between
multiple brokers in a cluster. This requires the following extra steps in addition to the ones
described above for configuring self-signed certificates. These steps are described in greater
detail in the subsections that follow.

▼ To Use a Signed Certificate

1 Install the certificate in the key store.

2 Configure the Message Queue client to require signed certificates when establishing an
SSL-based connection to the broker.

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:

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 CA’s 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.

Chapter 9 • Security 191

Message Encryption

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

2 If your certification authority is not supported in J2SE, import the CA’s 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.

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

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.

▼ To Configure the Client Runtime to Require Signed Certificates

1 Set the connection factory's imqSSLIsHostTrusted attribute to false.

By default, the connection factory object that the client will be using to establish broker
connections has its imqSSLIsHostTrusted attribute set to true, meaning that the client
runtime will accept any certificate presented to it. You must change this value to false so 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.

192 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Password Files

2 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” on page 189. 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.

3 Install the signing CA’s root certificate in the client’s 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
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 9–7, the first column lists the commands
that require passwords and the second column lists the reason that passwords are needed.

Chapter 9 • Security 193

Password Files

TABLE 9–7 Commands That Use Passwords

Command Description Purpose of Password

imqbrokerd Start broker Access a JDBC-based persistent data store, an

SSL certificate key store, or an LDAP user
repository

imqcmd Manage broker Authenticate an administrative user who is

authorized to use the command

imqdbmgr Manage JDBC-based data store Access the data store

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.

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 9–8 shows the types of passwords that a password file can
contain.

194 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Connecting Through a Firewall

TABLE 9–8 Passwords in a Password File

Password Affected Commands Description

imq.imqcmd.password imqcmd Administrator password for Message Queue

Command utility (authenticated for each
command)

imq.keystore.password imqbrokerd Key store password for SSL-based services

imq.persist.jdbc.password imqbrokerd Password for opening a database connection, if

imdbmgr required

imq.user_repository.ldap.password imqbrokerd Password associated with the distinguished

name assigned to a broker for binding to a
configured LDAP user repository

A sample password file is provided as part of your Message Queue installation; see Appendix A,
“Platform-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 9–9 Broker Configuration Properties for Static Port Addresses

Connection Service Configuration Property

jms imq.jms.tcp.port

ssljms imq.ssljms.tls.port

admin imq.admin.tcp.port

ssladmin imq.ssladmin.tls.port

Chapter 9 • Security 195

Connecting Through a Firewall

▼ To Enable Broker Connections Through a Firewall

1 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 9–9). 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.

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

196 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 10
C H A P T E R 1 0

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:
■ “Introduction to Monitoring Tools” on page 197
■ “Configuring and Using Broker Logging” on page 199
■ “Displaying Metrics Interactively” on page 204
■ “Using the JES Monitoring Framework” on page 209
■ “Writing an Application to Monitor Brokers” on page 210

Reference information on specific metrics is available in Chapter 18, “Metrics Reference”

Introduction to Monitoring Tools

There are four monitoring interfaces for Message Queue information: log files, interactive
monitoring commands, the Sun JavaTM Enterprise System Monitoring Framework (JESMF),
and a client API that can obtain metrics. Each has its advantages and disadvantages, as follows:
■ Log files provide a long-term record of metrics data, but cannot easily be parsed.
■ Interactive monitoring commands enable you to quickly sample information tailored to
your needs, but do not enable you to look at historical information or manipulate the data
programmatically.
■ The Sun Java Enterprise System Monitoring Framework (JESMF) offers a common,
Web-based graphical interface shared with other JES components, but can monitor only a
subset of all Sun Java System entities and operations.
■ The client API lets you extract information, process it, manipulate the data, present graphs,
or send alerts. However, to use it, you must write a custom application to capture and
analyze the data.

Table 10–1 compares the different tools.

197
Introduction to Monitoring Tools

TABLE 10–1 Benefits and Limitations of Metrics Monitoring Tools

Metrics Monitoring Tool Benefits Limitations

Log files ■ Regular sampling ■ Local monitoring only

■ Creates a historical record ■ 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

Interactive monitoring ■ Remote monitoring ■ Difficult to analyze data

commands ■ Convenient for spot-checking programmatically
■ Data presented in easy-to-read ■ No single command gets all data
tabular format ■ No historical record; difficult to see
■ Easy to select specific data of historical trends
interest
■ Reporting interval set in
command option; can be
changed on the fly

JES Monitoring ■ Web-based graphical interface ■ Limited subset of data available

Framework ■ Data cannot be analyzed
■ Data presented in easy-to-read
format programmatically
■ No historical record; difficult to see
■ Common interface shared with historical trends
other JES components
■ No performance penalty; pulls
data from broker’s existing data
monitoring infrastructure

198 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Configuring and Using Broker Logging

TABLE 10–1 Benefits and Limitations of Metrics Monitoring Tools (Continued)

Metrics Monitoring Tool Benefits Limitations

Client API ■ Remote monitoring ■ Need to write your own monitoring

■ Data can be analyzed client
programmatically and ■ Need to configure broker properties;
presented in any format must shut down and restart broker to
■ Easy to select specific data of take effect
interest
■ 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 18, “Metrics Reference.”

Configuring and Using Broker Logging

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 SolarisTM operating systems, to the syslog daemon
process. You can specify the type of information gathered by the Logger as well as the type
written to each of the output channels. In particular, you can specify that you want metrics
information written out to a log file.

This section describes the default logging configuration for the broker and explains how to
change that configuration to redirect log information to alternative output channels, change log
file rollover criteria, or send metrics data to a log file.

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 10–2). Each level includes those above it
(for example, WARNING includes ERROR).

TABLE 10–2 Logging Levels

Logging Level Description

ERROR Serious problems that could cause system failure

Chapter 10 • Monitoring Broker Operations 199

Configuring and Using Broker Logging

TABLE 10–2 Logging Levels (Continued)

Logging Level Description

WARNING Conditions that should be heeded but will not cause system failure

INFO 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 14–9).

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, “Platform-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.
■ To change the root name of the log files from log to something else, set the
imq.log.file.filename property.

200 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Configuring and Using Broker Logging

■ To change the frequency with which the log files are rolled over, set the property
imq.log.file.rolloversecs.

See Table 14–9 for further information on these properties.

Changing the Logging Configuration

Log-related properties are described in Table 14–9.

▼ To Change the Logger Configuration for a Broker

1 Set the logging level.

2 Set the output channel (file, console, or both) for one or more logging categories.

3 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 Logging interval for broker metrics, in seconds
-loglevel level Logging level (ERROR, WARNING, INFO, or NONE)
-silent Silent mode (no logging to console)
-tty 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 system’s syslog daemon.)

You can change the output channel for log messages in the following ways:

Chapter 10 • Monitoring Broker Operations 201

Configuring and Using Broker Logging

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

202 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Configuring and Using Broker Logging

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

▼ To Use Log Files to Report Metrics Information

1 Configure the broker’s 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.

2 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 18, “Metrics 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.

Chapter 10 • Monitoring Broker Operations 203

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

Displaying Metrics Interactively

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 destination’s 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.

204 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Displaying Metrics Interactively

You can also use the query subcommand to view similar data that also includes configuration
information. See “imqcmd query” on page 208 for more information.

imqcmd metrics
The syntax and options of imqcmd metrics are shown in Table 10–3 and Table 10–4,
respectively.

TABLE 10–3 imqcmd metrics Subcommand Syntax

Subcommand Syntax Metrics Data Provided

metrics bkr Displays broker metrics for the default broker or a broker at
[-b hostName:portNumber] the specified host and port.
[-m metricType]
[-int interval]
[-msp numSamples]

metrics svc -n serviceName Displays metrics for the specified service on the default broker
[-b hostName:portNumber] or on a broker at the specified host and port.
[-m metricType]
[-int interval]
[-msp numSamples]

metrics dst -t destType Displays metrics information for the physical destination of
-n destName the specified type and name.
[-b hostName:portNumber]
[-m metricType]
[-int interval]
[-msp numSamples]

TABLE 10–4 imqcmd metrics Subcommand Options

Subcommand Options Description

-b hostName: portNumber Specifies the hostname and port of the broker for which
metrics data is reported. The default is localhost:7676.

-int interval Specifies the interval (in seconds) at which to display the
metrics. The default is 5 seconds.

Chapter 10 • Monitoring Broker Operations 205

Displaying Metrics Interactively

TABLE 10–4 imqcmd metrics Subcommand Options (Continued)

Subcommand Options Description

-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 Specifies the number of samples displayed in the output. The
default is an unlimited number (infinite).

-n destName Specifies the name of the physical destination (if any) for
which metrics data is reported. There is no default.

-n serviceName Specifies the connection service (if any) for which metrics data
is reported. There is no default.

-t destType Specifies the type (queue or topic) of the physical destination

(if any) for which metrics data is reported. There is no default.

Using the metrics Subcommand to Display Metrics

Data
This section describes the procedure for using the metrics subcommand to report metrics
information.

▼ To Use the metrics Subcommand

1 Start the broker for which metrics information is desired.

See “Starting Brokers” on page 68.

2 Issue the appropriate imqcmd metrics subcommand and options as shown in Table 10–3 and
Table 10–4.

206 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Displaying Metrics Interactively

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 18–2):

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

This command produces output similar to the following (see data descriptions in Table 18–3):

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

This command produces output similar to the following (see data descriptions in Table 18–4):

Chapter 10 • Monitoring Broker Operations 207

Displaying Metrics Interactively

-----------------------------------------------------------------------------
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 destination’s consumers, use the following metrics dst
subcommand:

imqcmd metrics dst -t q -n SimpleQueue -m con -u admin

This command produces output similar to the following (see data descriptions in Table 18–4):

------------------------------------------------------------------
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 10–5 along with a description of
the metrics data provided by the command.

TABLE 10–5 imqcmd query Subcommand Syntax

Subcommand Syntax Metrics Data Provided

query bkr Information on the current number of messages and message

[-b hostName: portNumber] bytes stored in broker memory and persistent store (see
“Viewing Broker Information” on page 104).

or

query svc -n serviceName Information on the current number of allocated threads and
[-b hostName:portNumber] number of connections for a specified connection service (see
“Viewing Connection Service Information” on page 107).

or

query dst -t destType Information on the current number of producers, active and
-n destName backup consumers, and messages and message bytes stored in
[-b hostName:portNumber] memory and persistent store for a specified destination (see
“Viewing Physical Destination Information” on page 120).

208 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Using the JES Monitoring Framework

Note – Because of the limited metrics data provided by imqcmd query , this tool is not
represented in the tables presented in Chapter 18, “Metrics Reference.”

Using the JES Monitoring Framework

Message Queue supports the Sun Java Enterprise System Monitoring Framework (JESMF),
which allows Java Enterprise System components to be monitored using a common graphical
interface. This interface is implemented by a Web-based console called the Sun Java System
Monitoring Console. 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 JES components, you may find it more convenient to use a
single interface to manage all of them.

The JES Monitoring Framework defines a common data model, the Common Monitoring
Model (CMM), to be used by all JES component products. This model enables a centralized and
uniform view of all JES components. Message Queue exposes the following objects through the
Common Monitoring Model:
■ 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
JES Monitoring Console. The reference tables in Chapter 19, “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. Install and configure all the components in your deployment (Message Queue and other
components) according to instructions given in the Sun Java Enterprise System Installation
Guide.
2. Enable and configure the Monitoring Framework for all of your monitored components, as
described in the Sun Java Enterprise System Monitoring Guide.
3. 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.

Chapter 10 • Monitoring Broker Operations 209

Writing an Application to Monitor Brokers

Using the JES 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 broker’s
existing data monitoring infrastructure.

Writing an Application to Monitor Brokers

Message Queue provides a metrics monitoring capability by which the broker can write metrics
data into JMS messages, which it then sends to one of a number of metrics topic destinations,
depending on the type of metrics information contained in the message.

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.

There are five metrics topic destinations, whose names are shown in Table 10–6, along with the
type of metrics messages delivered to each destination.

TABLE 10–6 Metrics Topic Destinations

Topic Name Description

mq.metrics.broker Broker metrics

mq.metrics.jvm Java Virtual Machine metrics

mq.metrics.destination_list List of destinations and their types

mq.metrics.destination.queue.queueName Destination metrics for queue queueName

mq.metrics.destination.topic.topicName Destination metrics for topic topicName

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 Developer’s 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.

210 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Writing an Application to Monitor Brokers

2 Configure the broker’s 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 211 below.

4 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 broker’s 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.

Chapter 10 • Monitoring Broker Operations 211

Writing an Application to Monitor Brokers

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

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

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 18, “Metrics Reference.”

212 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 11
C H A P T E R 1 1

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 213
■ “Factors Affecting Performance” on page 216
■ “Adjusting Configuration To Improve Performance” on page 226

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 through
to 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 application’s general
performance requirements. If the benchmark testing meets these requirements, the

213
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 The number of message producers, or message consumers, or the
number of concurrent connections a system can support.
Message throughput The number of messages or message bytes that can be pumped
through a messaging system per second.
Latency The time it takes a particular message to be delivered from message
producer to message consumer.
Stability The overall availability of the message service or how gracefully it
degrades in cases of heavy load or failure.
Efficiency 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, there are several different aspects of performance. Which of them 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

214 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 About Performance

consumers (of a particular type) that consume the messages in the test suite’s 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 218), 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 11 • Analyzing and Tuning a Message Service 215

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.

Factors Affecting Performance

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.

216 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Factors Affecting Performance

Broker

2
Producing
Client
3 Data
Store
Client
Runtime 4

5
MyQDest
8 6 Consuming
Client
9 7
Client
10
Runtime

Payload messages
Control messages

FIGURE 11–1 Message Delivery Through a Message Queue Service

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

Chapter 11 • Analyzing and Tuning a Message Service 217

Factors Affecting Performance

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
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 219
■ “Use of Transactions” on page 219
■ “Acknowledgment Mode” on page 220
■ “Durable and Nondurable Subscriptions” on page 221

Other application design factors affecting performance are the following:

■ “Use of Selectors (Message Filtering)” on page 221
■ “Message Size” on page 222
■ “Message Body Type” on page 222

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 11–1 shows how the various application design factors generally affect messaging
performance. The table shows two scenarios—one high-reliability, low-performance, and one
high-performance, low-reliability—and the choices of application design factors that
characterize each. Between these extremes, there are many choices and tradeoffs that affect both
reliability and performance.

218 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Factors Affecting Performance

TABLE 11–1 Comparison of High-Reliability and High-Performance Scenarios

Application High-Reliability, High-Performance,

Design Factor Low-Performance Scenario Low-Reliability Scenario

Delivery mode Persistent messages Nonpersistent messages

Use of transactions Transacted sessions No transactions

Acknowledgment mode AUTO_ACKNOWLEDGE or DUPS_OK_ACKNOWLEDGE

CLIENT_ACKNOWLEDGE

Durable/nondurable subscriptions Durable subscriptions Nondurable subscriptions

Use of selectors Message filtering No message filtering

Message size Large number of small messages Small number of large messages

Message body type Complex body types 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 client’s 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:

Chapter 11 • Analyzing and Tuning a Message Service 219

Factors Affecting Performance

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

220 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Factors Affecting Performance

■ In AUTO_ACKNOWLEDGE and CLIENT_ACKNOWLEDGE modes, the client must wait until the
broker confirms that it has processed the client’s 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.

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.

Chapter 11 • Analyzing and Tuning a Message Service 221

Factors Affecting Performance

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.

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 223
■ “Operating System” on page 223

222 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Factors Affecting Performance

■ “Java Virtual Machine (JVM)” on page 223

■ “Connections” on page 223
■ “Broker Limits and Behaviors” on page 225
■ “Message Service Architecture” on page 225
■ “Data Store Performance” on page 226
■ “Client Runtime Configuration” on page 226

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 JVM’s 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.

Chapter 11 • Analyzing and Tuning a Message Service 223

Factors Affecting Performance

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

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 “Connection Services” on page 76.

The choice of protocols is based on application requirements (encrypted, accessible through a

firewall), but the choice affects overall performance.

HTTPS HTTP SSL TCP

SLOW FAST

FIGURE 11–2 Transport Protocol Speeds

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.

224 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Factors Affecting Performance

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

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 8, “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.

Chapter 11 • Analyzing and Tuning a Message Service 225

Adjusting Configuration To Improve Performance

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.
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 231 for more information on these features and the attributes used
to configure them.

Adjusting Configuration To Improve Performance

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, and
communication protocols.

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.

226 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Adjusting Configuration To Improve Performance

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 Window’s service, specify JVM arguments using the
-vmargs option to the imqsvcadmin install command. See “Service Administrator Utility”
on page 280 in Chapter 13, “Command Line Reference”
In any case, verify settings by checking the broker’s 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 protocol’s 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 229).
The protocol tuning properties are described in the following sections.

Chapter 11 • Analyzing and Tuning a Message Service 227

Adjusting Configuration To Improve Performance

nodelay
The nodelay property affects Nagle’s algorithm (the value of the TCP_NODELAY socket-level
option on TCP/IP) for the given protocol. Nagle’s 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 (Nagle’s 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 Nagle’s
algorithm is used, the broker delays several milliseconds before sending a response to the
consumer.

However, Nagle’s 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.

228 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Adjusting Configuration To Improve Performance

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 “Persistence Services” on page 80.

Broker Adjustments
The following sections describe adjustments you can make to broker properties to improve
performance.

Memory Management: Increasing Broker Stability Under Load

Memory management can be configured on a destination-by-destination basis or on a
systemwide level (for all destinations, collectively).

Using Physical Destination Limits

For information on physical destination limits, see Chapter 6, “Physical Destinations”

Chapter 11 • Analyzing and Tuning a Message Service 229

Adjusting Configuration To Improve Performance

Using Systemwide 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 in 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/unacknowledged messages. If additional messages are sent, they are rejected by the
broker. If a message is persistent then the producer will get an exception when it tries to send
the message. If the message is nonpersistent, the broker silently drops the message.

When an exception is returned in sending a message, the client should pause for a moment and
retry the send again. (Note that the exception will never be due to the broker’s failure to receive a
message; the only exceptions raised are those detected by the client on the sending side.)

Multiple Consumer Queue Performance

The efficiency with which multiple queue consumers process messages in a queue destination
depends on the following configurable queue destination attributes:
■ The number of active consumers (maxNumActiveConsumers)
■ The maximum number of messages that can be delivered to a consumer in a single batch
(consumerFlowLimit)

To achieve optimal message throughput there must be a sufficient number of active 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 general mechanism for balancing message delivery among multiple
consumers is described in the Message Queue Technical Overview.

If messages are accumulating in the queue, it is possible that there is an insufficient number of
active 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 active 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. In the extreme case, setting

230 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Adjusting Configuration To Improve Performance

consumerFlowLiimit to 1 configures the queue for “round-robin” delivery, in which single

messages are delivered, one to each consumer in rotation.

Client Runtime Message Flow Adjustments

This section discusses flow control behaviors that affect performance (see “Client Runtime
Configuration” on page 226). These behaviors are configured as attributes of connection factory
administered objects. For information on setting connection factory attributes, see Chapter 7,
“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 .

Chapter 11 • Analyzing and Tuning a Message Service 231

Adjusting Configuration To Improve Performance

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

232 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Adjusting Configuration To Improve Performance

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.

Chapter 11 • Analyzing and Tuning a Message Service 233

234
 12
C H A P T E R

Troubleshooting
1 2

This chapter explains how to understand and resolve the following problems:
■ “A Client Cannot Establish a Connection” on page 235
■ “Connection Throughput Is Too Slow” on page 239
■ “A Client Cannot Create a Message Producer” on page 241
■ “Message Production Is Delayed or Slowed” on page 242
■ “Messages Are Backlogged” on page 244
■ “Broker Throughput Is Sporadic” on page 248
■ “Messages Are Not Reaching Consumers” on page 249
■ “Dead Message Queue Contains Messages” on page 252

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.

235
A Client Cannot Establish a Connection

■ 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 broker’s 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.
To resolve the problem:
■ Start up the broker.
■ Fix the network connectivity 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 185.

236 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 A Client Cannot Establish a Connection

■ If the status of a connection service is shown as paused, resume the service (see “Pausing and
Resuming a Connection Service” on page 106).

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 77).
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 68.
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 12 • Troubleshooting 237

A Client Cannot Establish a Connection

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.

238 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Connection Throughput Is Too Slow

■ 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.
To resolve the problem:
■ 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 169).
■ 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 183).

Connection Throughput Is Too Slow

Symptoms:
■ Message throughput does not meet expectations.
■ The number of supported connections to a broker is not limited as described in “A Client
Cannot Establish a Connection” on page 235, but rather by message input/output rates.

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.

Chapter 12 • Troubleshooting 239

Connection Throughput Is Too Slow

■ 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 224).
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.
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 227.

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

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.
To resolve the problem:
■ Have application developers modify the application to use the message compression feature,
which is described in the Message Queue Developer’s 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 216 for other
possible bottlenecks and check for symptoms associated with the following problems:
■ “Message Production Is Delayed or Slowed” on page 242
■ “Messages Are Backlogged” on page 244
■ “Broker Throughput Is Sporadic” on page 248

To resolve the problem: Follow the problem resolution guidelines provided in the
troubleshooting sections listed above.

240 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 A Client Cannot Create a Message Producer

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.

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

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

Chapter 12 • Troubleshooting 241

Message Production Is Delayed or Slowed

Message Production Is Delayed or Slowed

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

242 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Message Production Is Delayed or Slowed

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 18, “Metrics
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.
In general, you should manage memory at the individual destination level, so that
brokerwide message limits are never reached. For more information, see “Broker
Adjustments” on page 229.
■ 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 15–1).

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 (see “Configuring a Persistent Data Store” on page 92). 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 factory’s imqAckTimeout attribute.
To confirm this cause of the problem: If the imqAckTimeout value is exceeded, the broker
returns the exception

Chapter 12 • Troubleshooting 243

Messages Are Backlogged

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

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

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.

244 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Messages Are Backlogged

■ 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 111).
■ Specify message limit and limit behavior attributes for the topic (see Table 15–1). 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 119).
■ 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 324).

Possible cause: Too few consumers are available to consume messages in a 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 “Multiple Consumer Queue Performance” on page 230).

Chapter 12 • Troubleshooting 245

Messages Are Backlogged

■ Specify message limit and limit behavior attributes for the queue (see Table 15–1). 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 119).
■ 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 324).

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 “Multiple Consumer
Queue Performance” on page 230).

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:

246 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Messages Are Backlogged

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

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

Chapter 12 • Troubleshooting 247

Broker Throughput Is Sporadic

Broker Throughput Is Sporadic

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.

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

248 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Messages Are Not Reaching Consumers

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.

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: Check the dead message queue, as described under
“Dead Message Queue Contains Messages” on page 252. Specifically, use the instructions under
“The number of messages, or their sizes, exceed destination limits.” Look for the
REMOVE_OLDEST or REMOVE_LOW_PRIORITY reason.
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 may be deleted.
To confirm this cause of the problem: Use the QBrowser demo application to look at the
contents of the dead message queue and see whether messages are timing out. For the QBrowser
demo’s platform-specific location, see Appendix A, “Platform-Specific Locations of Message
Queue Data” and look in the tables for “Example Applications and Locations.”
Here is an example invocation on the Windows platform:
cd \MessageQueue3\demo\applications\qbrowser java QBrowser

Chapter 12 • Troubleshooting 249

Messages Are Not Reaching Consumers

When the QBrowser main window appears, select the queue name mq.sys.dmq and then click
Browse. A list like the following appears:

Double-click any message to display details about that message:

250 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Messages Are Not Reaching Consumers

Note whether the JMS_SUN_DMQ_UNDELIVERED_REASON property for messages has the value
EXPIRED.
To resolve the problem: Contact the application developers and have them increase the
time-to-live value.

Possible cause: Clocks 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: 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 67.

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.

Chapter 12 • Troubleshooting 251

Dead Message Queue Contains Messages

Dead Message Queue Contains Messages

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.
■ Consumers are not receiving messages before they 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.
■ An unexpected broker error has occurred.

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 look at the contents of
the dead message queue. For the QBrowser demo’s platform-specific location, see Appendix A,
“Platform-Specific Locations of Message Queue Data” and look in the tables for “Example
Applications and Locations.”
Here is an example invocation on the Windows platform:
cd \MessageQueue3\demo\applications\qbrowser java QBrowser

252 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Dead Message Queue Contains Messages

When the QBrowser main window appears, select the queue name mq.sys.dmq and then click
Browse. A list like the one shown earlier under “Message timeout value is expiring” appears.
Double-click any message to display details about that message, as shown under “Message
timeout value is expiring.”
Note 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, note 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.
To confirm this cause of the problem: Using the QBrowser application, view the message details for
messages in the dead message queue. Check the value for JMS_SUN_DMQ_UNDELIVERED_REASON,
looking for messages with the reason 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 67.

Possible cause: Consumers are not receiving messages before they time out.
To verify this cause of the problem: Using the QBrowser application, view the message details for
messages in the dead message queue. Check the value for JMS_SUN_DMQ_UNDELIVERED_REASON,
looking for messages with the reason EXPIRED.
Check to see whether there any consumers on the destination. For example:
imqcmd query dst -t q -n MyDest
Check the value listed for Current Number of Active Consumers. If there are active consumers,
one of the following is true:
■ A consumer’s connection is paused.
■ The message timeout is too short for the speed at which the consumer executes.
To resolve the problem: Request that application developers increase message time-to-live
values.

Possible cause: There are too many producers for the number of consumers.
To confirm this cause of the problem: Using the QBrowser application, view the message details for
messages in the dead message queue. Check the value for JMS_SUN_DMQ_UNDELIVERED_REASON.
If the reason is REMOVE_OLDEST or REMOVE_LOW_PRIORITY, use the imqcmd query dst command

Chapter 12 • Troubleshooting 253

Dead Message Queue Contains Messages

to check the number of producers and consumers on the destination. If the number of
producers exceeds the number of consumers, production rate may be overwhelming
consumption rate.
To resolve the problem: Add more consumer clients or set the destination’s 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 consumerFlowLimit=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 destination’s 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 consumerFlowLimit=FLOW_CONTROL
Use metrics to examine the destination’s 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, using the
subsequent sections, consider and attempt to resolve each of the following possible factors:
■ 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 metrics to determine the rate of production and
consumption, as described above under “Producers are faster than consumers.”

254 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Dead Message Queue Contains Messages

To resolve the problem:

■ Set the destinations’ limit behavior to FLOW_CONTROL, using a command such as the
following:
imqcmd update dst -n myDst -t q -o consumerFlowLimit=FLOW_CONTROL
Use of flow control slows production to the rate of consumption and prevents the
accumulation of messages on the broker. 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
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 messages.

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 or client-based acknowledgment. If the

Chapter 12 • Troubleshooting 255

Dead Message Queue Contains Messages

application uses system-based acknowledgment, skip this section; if it uses client-based

acknowledgment (CLIENT_ACKNOWLEDGE), 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 consumers are inactive.

To confirm this cause of the problem: Look at the topic’s durable subscribers, using the following
command format:
imqcmd list dur -d topicName
To resolve the problem:
■ Purge the durable consumers using the imqcmd purge dur command.
■ Restart the consumer applications.

Possible cause: An unexpected broker error has occurred.

To confirm this cause of the problem: Use QBrowser to examine a message, as described earlier
under “Producers are faster than consumers.” If the value for
JMS_SUN_DMQ_UNDELIVERED_REASON is ERROR, a broker error occurred.
To resolve the problem:
■ Examine the broker log file to find the associated error.

256 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Dead Message Queue Contains Messages

■ Contact Sun Technical Support to report the broker problem.

Chapter 12 • Troubleshooting 257

258
P A R T I I I

Reference
■ Chapter 13, “Command Line Reference”
■ Chapter 14, “Broker Properties Reference”
■ Chapter 15, “Physical Destination Property Reference”
■ Chapter 16, “Administered Object Attribute Reference”
■ Chapter 17, “JMS Resource Adapter Property Reference”
■ Chapter 18, “Metrics Reference”
■ Chapter 19, “JES Monitoring Framework Reference”

259
260
 13
C H A P T E R 1 3

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 261
■ “Broker Utility” on page 262
■ “Command Utility” on page 266
■ “Object Manager Utility” on page 275
■ “Database Manager Utility” on page 277
■ “User Manager Utility” on page 278
■ “Service Administrator Utility” on page 280
■ “Key Tool Utility” on page 281

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)
■ imqsvcadmin (Service Administrator utility)
■ imqkeytool (Key Tool utility)

261
Broker 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 13–1 shows the options to the imqbrokerd command and the configuration properties, if
any, overridden by each option.

TABLE 13–1 Broker Utility Options

Option 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 broker’s 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

262 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Broker Utility

TABLE 13–1 Broker Utility Options (Continued)

Option Properties Overridden Description

-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 Set configuration property

configuration file
See Chapter 14, “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 broker’s 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 None Clear persistent messages from data store

-reset durables None Clear durable subscriptions from data store

1
Applies only to broker clusters

Chapter 13 • Command Line Reference 263

Broker Utility

TABLE 13–1 Broker Utility Options (Continued)

Option Properties Overridden Description

-backup fileName None Back up configuration change record to file1

See “Managing the Configuration Change
Record” on page 158 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 the Configuration Change
Record” on page 158 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 imq.persist.jdbc.user User name for JDBC-based persistent data store

-passfile filePath imq.passfile.enabled Location of password file

imq.passfile.dirpath
Sets the broker’s imq.passfile.enabled
imq.passfile.name
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 193 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 broker’s 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
Applies only to broker clusters
2
Requires user confirmation unless -force is also specified

264 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Broker Utility

TABLE 13–1 Broker Utility Options (Continued)

Option Properties Overridden Description

-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 imq.jmx.rmiregistry.start Start RMI registry at broker startup

-useRmiRegistry imq.jmx.rmiregistry.use Use external RMI registry

-rmiRegistryPort imq.jmx.rmiregistry.port Port number of RMI registry

-upgrade-store-nobackup None 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 imq.metrics.interval Logging interval for broker metrics, in seconds

-tty imq.log.console.output Log all messages to console

Sets the broker’s imq.log.console.output
property to ALL.
If not specified, only error and warning messages
will be logged.
2
Requires user confirmation unless -force is also specified

Chapter 13 • Command Line Reference 265

Command Utility

TABLE 13–1 Broker Utility Options (Continued)

Option Properties Overridden Description

-s | -silent imq.log.console.output Silent mode (no logging to console)

Sets the broker’s imq.log.console.output
property to NONE.

-version None Display version information3

-h | -help None Display usage help3

3
Any other options specified on the command line are ignored.

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). The possible subcommands are listed in
Table 13–2 and described in detail in the corresponding sections below. In all cases, if the
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 13–2 Command Utility Subcommands

“Broker Management” on page 268

shutdown bkr Shut down broker

restart bkr Restart broker

pause bkr Pause broker

quiesce bkr Quiesce broker

unquiesce bkr Unquiesce broker

resume bkr Resume broker

takeover bkr Initiate broker takeover

update bkr Set broker properties

reload cls Reload cluster configuration

query bkr List broker property values

list bkr List brokers in cluster

metrics bkr Display broker metrics

266 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Command Utility

TABLE 13–2 Command Utility Subcommands (Continued)

“Connection Service Management” on page

pause svc Pause connection service

resume svc Resume connection service

update svc Set connection service properties

list svc List connection services available on broker

query svc List connection service property values

metrics svc Display connection service metrics

“Connection Management” on page 271

list cxn List connections on broker

query cxn Display connection information

destroy cxn Destroy connection

“Physical Destination Management” on page 271

create dst Create physical destination

destroy dst Destroy physical destination

pause dst Pause message delivery for physical destination

resume dst Resume message delivery for physical destination

purge dst Purge all messages from physical destination

compact dst Compact physical destination

update dst Set physical destination properties

list dst List physical destinations

query dst List physical destination property values

metrics dst Display physical destination metrics

“Durable Subscription Management” on page 273

destroy dur Destroy durable subscription

purge dur Purge all messages for durable subscription

list dur List durable subscriptions for topic

“Transaction Management” on page 273

commit txn Commit transaction

rollback txn Roll back transaction

Chapter 13 • Command Line Reference 267

Command Utility

TABLE 13–2 Command Utility Subcommands (Continued)

list txn List transactions being tracked by broker

query txn Display transaction information

list dur List durable subscriptions for topic

“JMX Management” on page 274

list jmx List JMX service URLs of JMX connectors

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 13–3
to manage and control it.

TABLE 13–3 Command Utility Subcommands for Broker Management

Syntax Description

shutdown bkr [-b hostName:portNumber] Shut down broker

[-time nSeconds]
The -time option specifies the interval, in seconds, to wait
[-nofailover] 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 a high-availability 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.

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 102 for more
information.

quiesce bkr [-b hostName:portNumber] Quiesce broker

The broker will stop accepting new connections; existing
connections will continue to operate.

268 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Command Utility

TABLE 13–3 Command Utility Subcommands for Broker Management (Continued)

Syntax Description

unquiesce bkr [-b hostName:portNumber] Unquiesce broker

The broker will resume accepting new connections,
returning to normal operation.

resume bkr [-b hostName:portNumber] Resume broker

takeover bkr -n brokerID Initiate broker takeover

[-f]
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] Set broker properties

-o property1=value1
See Chapter 14, “Broker Properties Reference” for
[ [-o property2=value2] … ] information on broker properties.

reload cls 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 HA
clusters).

list bkr List brokers in cluster

1
Applies only to broker clusters

Chapter 13 • Command Line Reference 269

Command Utility

TABLE 13–3 Command Utility Subcommands for Broker Management (Continued)

Syntax Description

metrics bkr [-b hostName:portNumber] Display broker metrics

[-m metricType]
The -m option specifies the type of metrics to display:
[-int interval]
ttl: Messages and packets flowing into and out of the
[-msp numSamples]
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 13–4 lists the imqcmd subcommands for managing connection services.

TABLE 13–4 Command Utility Subcommands for Connection Service Management

Syntax Description

pause svc -n serviceName Pause connection service

[-b hostName:portNumber]
The admin connection service cannot be paused.

resume svc -n serviceName Resume connection service

[-b hostName:portNumber]

update svc -n serviceName Set connection service properties

[-b hostName:portNumber]
See “Connection Properties” on page 283 for information on
-o property1=value1 connection service properties.
[ [-o property2=value2] … ]

list svc [-b hostName:portNumber] List connection services available on broker

query svc -n serviceName List connection service property values

[-b hostName:portNumber]

270 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Command Utility

TABLE 13–4 Command Utility Subcommands for Connection Service Management (Continued)
Syntax Description

metrics svc -n serviceName Display connection service metrics

[-b hostName:portNumber]
The -m option specifies the type of metrics to display:
[-m metricType]
ttl: Messages and packets flowing into and out of the
[-int interval]
broker by way of the specified connection service
[-msp numSamples]
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 13–5 lists the imqcmd subcommands for managing connections.

TABLE 13–5 Command Utility Subcommands for Connection Service Management

Syntax Description

list cxn [-svn serviceName] List connections on broker

[-b hostName:portNumber]
Lists all connections on the broker to the specified
connection service. If no connection service is specified, all
connections are listed.

query cxn -n connectionID Display connection information

[-b hostName:portNumber]

destroy cxn -n connectionID Destroy connection

[-b hostName:portNumber]

Physical Destination Management

Table 13–6 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

Chapter 13 • Command Line Reference 271

Command Utility

TABLE 13–6 Command Utility Subcommands for Physical Destination Management

Syntax Description

create dst -t destType -n destName Create physical destination1

[ [-o property=value] … ]
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 dst -tdestType -n destName Destroy physical destination1

This operation cannot be applied to a system-created
destination, such as a dead message queue.

pause dst [-t destType -n destName] Pause message delivery for physical destination
[-pst pauseType]
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 Purge all messages from physical destination

compact dst [-t destType -n destName] 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 Set physical destination properties

-o property1=value1
See Chapter 15, “Physical Destination Property Reference”
[ [ -o property2=value2] … ] for information on physical destination properties.
1
Cannot be performed in a broker cluster whose master broker is temporarily unavailable

272 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Command Utility

TABLE 13–6 Command Utility Subcommands for Physical Destination Management (Continued)
Syntax Description

list dst [-t destType] List physical destinations

[-tmp]
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.

query dst -t destType -n destName List physical destination property values

metrics dst -t destType -n destName Display physical destination metrics

[-m metricType]
The -m option specifies the type of metrics to display:
[-int interval]
ttl: Messages and packets flowing into and out of the
[-msp numSamples]
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).

Durable Subscription Management

Table 13–7 lists the imqcmd subcommands for managing durable subscriptions.

TABLE 13–7 Command Utility Subcommands for Durable Subscription Management

Syntax Description

destroy dur -n subscriberName -c clientID Destroy durable subscription1

purge dur -n subscriberName -c clientID Purge all messages for durable subscription

list dur -d topicName List durable subscriptions for topic

1
Cannot be performed in a broker cluster whose master broker is temporarily unavailable

Transaction Management
Table 13–8 lists the imqcmd subcommands for managing transactions.

Chapter 13 • Command Line Reference 273

Command Utility

TABLE 13–8 Command Utility Subcommands for Transaction Management

Syntax Description

commit txn -n transactionID Commit transaction

rollback txn -n transactionID Roll back transaction

list txn List transactions being tracked by broker

query txn -n transactionID Display transaction information

JMX Management
The imqcmd subcommand shown in Table 13–9 is used for administrative support of Message
Queue client programs 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 administrative support of JMX clients.

TABLE 13–9 Command Utility Subcommand for JMX Management

Syntax Description

list jmx List JMX service URLs of JMX connectors

General Command Utility Options

The additional options listed in Table 13–10 can be applied to any subcommand of the imqcmd
command.

TABLE 13–10 General Command Utility Options

Option Description

-secure Use secure connection to broker with ssladmin connection service

-u userName 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 193 for more information.

274 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Object Manager Utility

TABLE 13–10 General Command Utility Options (Continued)

Option Description

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

-rtr numRetries Number of retries to attempt after a broker request times out
Default value: 5.

-javahome path Location of alternative Java runtime

Default behavior: Use runtime installed on system or bundled with Message
Queue.

-f Perform action without user confirmation

-s Silent mode (no output displayed)

-v Display version information1,2

-h,2 Display usage help1

-H Display expanded usage help, including attribute list and examples1,2

1
Any other options specified on the command line are ignored.
2
User name and password not needed

Object Manager Utility

The Object Manager utility (imqobjmgr) creates and manages Message Queue administered
objects. Table 13–11 lists the available subcommands.

TABLE 13–11 Object Manager Subcommands

Subcommand Description

add Add administered object to object store

delete Delete administered object from object store

list List administered objects in object store

query Display administered object information

update Modify administered object

Table 13–12 lists the options to the imqobjmgr command.

Chapter 13 • Command Line Reference 275

Object Manager Utility

TABLE 13–12 Object Manager Options

Option Description

-l lookupName JNDI lookup name of administered object

-j attribute=value Attributes of JNDI object store (see “Object Stores” on page 127)

-t objectType 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

-o attribute=value Attributes of administered object (see “Administered Object Attributes” on page 130
and Chapter 16, “Administered Object Attribute Reference”)

-r readOnlyState Is administered object read-only?

If true, client cannot modify object’s attributes.
Default value: false.

-i fileName Name of command file containing all or part of subcommand clause

-pre Preview results without performing command

This option is useful for checking the values of default attributes.

-javahome path Location of alternative Java runtime

Default behavior: Use runtime installed on system or bundled with Message Queue.

-f Perform action without user confirmation

-s Silent mode (no output displayed)

-v Display version information1

-h Display usage help1

-H Display expanded usage help, including attribute list and examples1

1
Any other options specified on the command line are ignored.

276 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Database Manager Utility

Database Manager Utility

The Database Manager utility (imqdbmgr) sets up the database schema for a JDBC-based
persistent data store. You can also use it to delete Message Queue database tables that have
become corrupted, change the data store, display information about the data store, convert a
standalone data store for high-availability (HA) use, or back up and restore an HA data store.
Table 13–13 lists the available subcommands.

TABLE 13–13 Database Manager Subcommands

Subcommand Description

create all Create new database and persistent store schema

Used on embedded database systems. The broker property
imq.persist.jdbc.vendorName.createdburl must be specified.

create tbl Create persistent store schema for existing database

Used on external database systems.
For brokers belonging to a high-availability cluster (imq.cluster.ha =
true), the schema created is for the cluster’s shared persistent data store,
according to the HA database vendor identified by the broker’s
imq.persist.jdbc.dbVendor property. If imq.cluster.ha = false, the
schema is for the individual broker’s standalone data store. Since the two
types of store can coexist in the same database, they are distinguished by
appending a suffix to all table names:
CclusterID: Shared store
SbrokerID: Standalone store

delete tbl Delete Message Queue database tables from current persistent store

delete oldtbl Delete Message Queue database tables from earlier-version persistent store
Used after the persistent 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 persistent store

upgrade hastore Upgrade standalone store to high-availability (HA) shared store

backup Back up JDBC-based store to backup files

restore Restore JDBC-based store from backup files

Chapter 13 • Command Line Reference 277

User Manager Utility

TABLE 13–13 Database Manager Subcommands (Continued)

Subcommand Description

remove bkr Remove broker from HA shared store

The broker must not be running.

reset lck Reset persistent store lock

Resets the lock so that the persistent store database can be used by other
processes.

Table 13–14 lists the options to the imqdbmgr command.

TABLE 13–14 Database Manager Options

Option Description

-b instanceName Instance name of broker

-Dproperty= value Set broker configuration property

See “Persistence Properties” on page 290 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 name User name for authentication

-passfile filePath Location of password file

See “Password Files” on page 193 for more information.

-n brokerID Broker identifier of broker to be removed from HA shared store

-dir dirPath Backup directory for backing up or restoring JDBC-based data store

-v Display version information1

-h Display usage help1

1
Any other options specified on the command line are ignored.

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.

278 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 User Manager Utility

Table 13–15 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 13–15 User Manager Subcommands

Syntax Description

add [-i instanceName] Add user and password to repository

-u userName -p password
The optional -g option specifies a group to which to assign
[-g group] this user:
admin
user
anonymous

delete [-i instanceName] Delete user from repository

-u userName

update [-i instanceName] Set user’s password or active (or both)

-u userName -p password
The -a option takes a boolean value specifying whether to
[-a activeStatus] make the user active (true) or inactive (false).
update [-i instanceName] Default value: true.
-u userName -a activeStatus
[-p password]

list [-i instanceName] Display user information

[-u userName]
If no user name is specified, all users in the repository are
listed.

In addition, the options listed in Table 13–16 can be applied to any subcommand of the
imqusermgr command.

TABLE 13–16 General User Manager Options

Option Description

-f Perform action without user confirmation

-s Silent mode (no output displayed)

-v Display version information1

-h Display usage help1

1
Any other options specified on the command line are ignored.

Chapter 13 • Command Line Reference 279

Service Administrator Utility

Service Administrator Utility

The Service Administrator utility (imqsvcadmin) installs a broker as a Windows service.
Table 13–17 lists the available subcommands.

TABLE 13–17 Service Administrator Subcommands

Subcommand Description

install Install service

remove Remove service

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 13–18).

Table 13–18 lists the options to the imqsvcadmin command.

TABLE 13–18 Service Administrator Options

Option Description

-javahome path Location of alternative Java runtime

Default behavior: Use runtime installed on system or bundled with Message
Queue.

-jrehome path Location of alternative Java Runtime Environment (JRE)

-vmargs arg1 [ [arg2] … ] 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 262 for information about broker command line
arguments.

-h Display usage help2

1
These arguments can also be specified in the Start Parameters field under the General tab in the service’s Properties window (reached
by way of the Services tool in the Windows Administrative Tools control panel).
2
Any other options specified on the command line are ignored.

280 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Key Tool Utility

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

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 may need to run the utility from the root user account.

Chapter 13 • Command Line Reference 281

282
 14
C H A P T E R 1 4

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 283
■ “Routing Properties” on page 286
■ “Persistence Properties” on page 290
■ “Security Properties” on page 293
■ “Monitoring Properties” on page 298
■ “Cluster Configuration Properties” on page 302
■ “JMX Properties” on page 304
■ “Alphabetical List of Broker Properties” on page 307

Connection Properties
Table 14–1 lists the broker properties related to connection services.

283
Connection Properties

TABLE 14–1 Broker Connection Properties

Property Type Default Value Description

imq.brokerid String None Broker identifier

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. No two running brokers may
have the same 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. This property
is usually unnecessary for an embedded database, which
stores data for only one broker instance.
Note – For high-availability brokers (imq.cluster.ha =
true), database table names use the
imq.cluster.clusterid property (see Table 14–10)
instead.

imq.service.activelist1 String jms,admin List of connection services to be activated at broker

startup, separated by commas
See Table 4–1 under “Connection Services” on page 76 for
the names of the available connection services.

imq.hostname String All available IP Default host name or IP address for all connection
addresses services

imq.portmapper.hostname String None Host name or IP address of Port Mapper

If specified, overrides imq.hostname. This might be
necessary, for instance, if the broker’s host computer has
more than one network interface card installed.

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 broker’s host computer has more than one network
interface card installed.
1
Must have the same value for all brokers in an HA cluster.
2
Can be used with imqcmd update bkr command
3
jms, ssljms, admin, and ssladmin services only; see Appendix C, “HTTP/HTTPS Support” for information on configuring the httpjms and httpsjms services

284 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Connection Properties

TABLE 14–1 Broker Connection Properties (Continued)

Property Type Default Value Description

imq.serviceName.protocolType.port3 Integer 0 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 Integer 50 Maximum number of pending Port Mapper requests in

operating system backlog

imq.serviceName.threadpool_model4 String dedicated 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.

imq.serviceName.min_threads Integer jms: 10 Minimum number of threads maintained in connection

ssljms: 10 service’s thread pool
httpjms: 10
When the number of available threads exceeds this
httpsjms: 10
threshold, threads will be shut down as they become free
admin: 4
until the minimum is reached.
ssladmin: 4
The default value varies by connection service, as shown.

imq.serviceName.max_threads Integer jms: 1000 Number of threads beyond which no new threads are
ssljms: 500 added to the thread pool for use by the named connection
httpjms: 500 service
httpsjms : 500
Must be greater than 0 and greater than the value of
admin: 10
imq.serviceName.min_threads.
ssladmin: 10
The default value varies by connection service, as shown.
3
jms, ssljms, admin, and ssladmin services only; see Appendix C, “HTTP/HTTPS Support” for information on configuring the httpjms and httpsjms services
4
jms and admin services only

Chapter 14 • Broker Properties Reference 285

Routing Properties

TABLE 14–1 Broker Connection Properties (Continued)

Property Type Default Value Description

imq.shared.connectionMonitor_limit5 Integer Solaris: 512 Maximum number of connections monitored by a

Linux: 512 distributor thread
Windows: 64
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.
5
Shared threading model only

Routing Properties
Table 14–2 lists the broker properties related to routing services. Properties that configure the
automatic creation of destinations are listed in Table 14–3.

TABLE 14–2 Broker Routing Properties

Property Type Default Value Description

imq.system.max_count1 Integer −1 Maximum number of messages held by broker

A value of −1 denotes an unlimited message count.

imq.system.max_size 1
String −1 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.
1
Can be used with imqcmd update bkr command

286 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Routing Properties

TABLE 14–2 Broker Routing Properties (Continued)

Property Type Default Value Description

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 Integer 60 Interval, in seconds, at which expired messages are reclaimed

imq.resourceState.threshold Integer green: 0 Percent utilization at which memory resource state is

yellow: 80 triggered (where resourceState is green, yellow, orange, or
orange: 90 red)
red: 98

imq.resourceState.count Integer green: 5000 Maximum number of incoming messages allowed in a batch
yellow: 500 before checking whether memory resource state threshold
orange: 50 has been reached (where resourceState is green, yellow,
red: 0 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).
1
Can be used with imqcmd update bkr command

TABLE 14–3 Broker Properties for Auto-Created Destinations

Property Type Default Value Description

1,2
imq.autocreate.queue Boolean true Allow auto-creation of queue destinations?

imq.autocreate.topic3 Boolean true Allow auto-creation of topic destinations?

1
Can be used with imqcmd update bkr command
2
Queue destinations only
3
Topic destinations only

Chapter 14 • Broker Properties Reference 287

Routing Properties

TABLE 14–3 Broker Properties for Auto-Created Destinations (Continued)

Property Type Default Value Description

imq.autocreate.destination.maxNumMsgs Integer 100000 Maximum number of unconsumed messages

A value of −1 denotes an unlimited number of
messages.

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.

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

288 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Routing Properties

TABLE 14–3 Broker Properties for Auto-Created Destinations (Continued)

Property Type Default Value Description

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.

imq.autocreate.queue.maxNumActiveConsumers2 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.

imq.autocreate.queue.maxNumBackupConsumers2 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.

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.
2
Queue destinations only
3
Topic destinations only

Chapter 14 • Broker Properties Reference 289

Persistence Properties

TABLE 14–3 Broker Properties for Auto-Created Destinations (Continued)

Property Type Default Value Description

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

imq.autocreate.queue.localDeliveryPreferred2 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.
2
Queue destinations only

Persistence Properties
Message Queue supports both file-based and JDBC-based models for persistent data storage.
The broker property imq.persist.store (Table 14–4) specifies which model to use. The
following sections describe the broker configuration properties for the two models.

TABLE 14–4 Global Broker Persistence Property

Property Type Default Value Description

imq.persist.store String file Model for persistent data storage:

file: File-based persistence
jdbc: JDBC-based persistence

Must be set to jdbc for high-availability brokers

(imq.cluster.ha = true).

290 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Persistence Properties

File-Based Persistence Properties

Table 14–5 lists the broker properties related to file-based persistence.

TABLE 14–5 Broker Properties for File-Based Persistence

Default
Property Type Value Description

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)

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

Chapter 14 • Broker Properties Reference 291

Persistence Properties

TABLE 14–5 Broker Properties for File-Based Persistence (Continued)

Default
Property Type Value Description

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.

JDBC-Based Persistence Properties

Table 14–6 lists the broker properties related to JDBC-based persistence. The
imq.persist.jdbc.dbVendor property identifies the database vendor being used for the
cluster’s persistent data store; all of the remaining properties are qualified by this vendor name.

TABLE 14–6 Broker Properties for JDBC-Based Persistence

Default
Property Type Value Description

imq.persist.jdbc.dbVendor String derby Name of database vendor for persistent data store:
hadb: HADB (Sun Microsystems, Inc.)
derby: Java DB (Derby, Apache Software
Foundation)
oracle: Oracle Real Application Cluster
(Oracle Corporation)
mysql: MySQL (MySQL AB)

imq.persist.jdbc.vendorName.driver String None Java class name of JDBC driver for connecting to
database from vendor vendorName

292 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Security Properties

TABLE 14–6 Broker Properties for JDBC-Based Persistence (Continued)

Default
Property Type Value Description

imq.persist.jdbc.vendorName.opendburl String None URL for connecting to existing database from

vendor vendorName

imq.persist.jdbc.vendorName.createdburl1 String None URL for creating new database from vendor
vendorName
Needed only if the database will be created using the
Message Queue Database Manager utility
(imqdbmgr).

imq.persist.jdbc.vendorName.closedburl1 String None URL for closing connection to database from

vendor vendorName

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 String None Password, if required, for connecting to database

from vendor vendorName

imq.persist.jdbc.vendorName.property.propName1 String None Vendor-specific property propName for database

from vendor vendorName
1
Optional
2
Should be used only in password files

Security Properties
Table 14–7 lists general broker properties related to security services.

Chapter 14 • Broker Properties Reference 293

Security Properties

TABLE 14–7 General Broker Security Properties

Property Type Default Value Description

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

imq.authentication.type String digest Password encoding method:

digest: MD5 (for file-based
authentication)
basic: Base-64 (for LDAP or
JAAS authentication)

imq.serviceName.authentication.type String None 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.client.response.timeout Integer 180 Interval, in seconds, to wait for

client response to authentication
requests

imq.accesscontrol.enabled Boolean true 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.

294 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Security Properties

TABLE 14–7 General Broker Security Properties (Continued)

Property Type Default Value Description

imq.serviceName.accesscontrol.enabled Boolean None 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,
“Platform-Specific Locations of
Message Queue Data”).

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,
“Platform-Specific Locations of
Message Queue Data”).

imq.keystore.file.dirpath String See Appendix A, Path to directory containing key

“Platform-Specific store file
Locations of Message Queue
Data”

imq.keystore.file.name String keystore Name of key store file

1
imq.keystore.password String None Password for key store file

imq.passfile.enabled Boolean false Obtain passwords from password

file?
1
Should be used only in password files

Chapter 14 • Broker Properties Reference 295

Security Properties

TABLE 14–7 General Broker Security Properties (Continued)

Property Type Default Value Description

imq.passfile.dirpath String See Appendix A, Path to directory containing

“Platform-Specific password file
Locations of Message Queue
Data”

imq.passfile.name String passfile Name of password file

imq.imqcmd.password String None Password for administrative user

The Command utility (imqcmd)
uses this password to authenticate
the user before executing a
command.

Table 14–8 lists broker properties related to LDAP-based user authentication.

TABLE 14–8 Broker Security Properties for LDAP Authentication

Property Type Default Value Description

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
…

296 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Security Properties

TABLE 14–8 Broker Security Properties for LDAP Authentication (Continued)

Property Type Default Value Description

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.

imq.user_repository.ldap.password1 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 None Directory base for LDAP user

entries

imq.user_repository.ldap.uidattr String None Provider-specific attribute

identifier for LDAP user name

imq.user_repository.ldap.usrfilter2 String None JNDI filter for LDAP user searches

imq.user_repository.ldap.grpsearch Boolean false Enable LDAP group searches?

Note – Message Queue does not
support nested groups.

imq.user_repository.ldap.grpbase String None Directory base for LDAP group

entries

imq.user_repository.ldap.gidattr String None Provider-specific attribute

identifier for LDAP group name

imq.user_repository.ldap.memattr String None Provider-specific attribute

identifier for user names in LDAP
group

imq.user_repository.ldap.grpfilter2 String None JNDI filter for LDAP group

searches
1
Should be used only in password files
2
Optional

Chapter 14 • Broker Properties Reference 297

Monitoring Properties

TABLE 14–8 Broker Security Properties for LDAP Authentication (Continued)

Property Type Default Value Description

imq.user_repository.ldap.timeout Integer 280 Time limit for LDAP searches, in

seconds

imq.user_repository.ldap.ssl.enabled Boolean false Use SSL when communicating

with LDAP server?

Monitoring Properties
Table 14–9 lists the broker properties related to monitoring services.

TABLE 14–9 Broker Monitoring Properties

Property Type Default Value Description

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.
1
Can be used with imqcmd update bkr command

298 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Monitoring Properties

TABLE 14–9 Broker Monitoring Properties (Continued)

Property Type Default Value Description

imq.log.console.stream String ERR Destination for console output:

OUT: stdout
ERR: stderr

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, “Platform-Specific Path to directory containing log file
Locations of Message Queue Data”

imq.log.file.filename String log.txt Name of log file

imq.log.file.output String ALL 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 −1 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).
1
Can be used with imqcmd update bkr command

Chapter 14 • Broker Properties Reference 299

Monitoring Properties

TABLE 14–9 Broker Monitoring Properties (Continued)

Property Type Default Value Description

imq.log.file.rolloversecs1 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 String imqbrokerd_${imq.instanceName} Identity string to be prefixed to all

messages logged to syslog

imq.log.syslog.logpid2 Boolean true Log broker process ID with message?

1
Can be used with imqcmd update bkr command
2
Solaris platform only

300 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Monitoring Properties

TABLE 14–9 Broker Monitoring Properties (Continued)

Property Type Default Value Description

imq.log.syslog.logconsole2 Boolean false Write messages to system console if

they cannot be sent to syslog?

imq.log.timezone String Local time zone Time zone for log time stamps
Possible values are the same as those
used by the method
java.util.TimeZone.getTimeZone.
Examples:
GMT
GMT−8:00
America/LosAngeles
Europe/Rome
Asia/Tokyo

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

imq.metrics.topic.persist Boolean false Are metrics messages sent to metric

topic destinations persistent?
2
Solaris platform only

Chapter 14 • Broker Properties Reference 301

Cluster Configuration Properties

TABLE 14–9 Broker Monitoring Properties (Continued)

Property Type Default Value Description

imq.metrics.topic.timetolive Integer 300 Lifetime, in seconds, of metrics

messages sent to metric topic
destinations

imq.primaryowner.name3 String System property user.name Name of primary system owner

(user who started the broker)

imq.primaryowner.contact3 String System property user.name Contact information for primary

(user who started the broker) system owner

imq.broker.adminDefinedRoles.count3 Integer None Number of defined roles

imq.broker.adminDefinedRoles.namen3 String Broker instance name Name of defined role n (zero-based)

Example: Stocks JMS Server
3
Used by JES Monitoring Framework

Cluster Configuration Properties

Table 14–10 lists the configuration properties related to broker clusters.

TABLE 14–10 Broker Properties for Cluster Configuration

Default
Property Type Value Description

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)

imq.cluster.ha Boolean false Is broker part of an HA cluster?

1
Must have the same value for all brokers in a cluster
2
Can be used with imqcmd update bkr command

302 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Cluster Configuration Properties

TABLE 14–10 Broker Properties for Cluster Configuration (Continued)

Default
Property Type Value Description

1,3
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

HA clusters; all brokers configured to use the cluster’s 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 14–1) for the
cluster connection service. This might be necessary, for
instance, if the broker’s host computer has more than one
interface card installed.

imq.cluster.port4 Integer 0 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
cluster’s master broker (if any) is running
The value has the form hostName:portNumber, where hostName
is the host name of the master broker’s host and portNumber is its
Port Mapper port number.
Example:
ctrlhost:7676

Note – HA clusters cannot have a master broker. If this property is

set for a broker belonging to an HA cluster, the broker will log a
fatal error and fail to start.
1
Must have the same value for all brokers in a cluster
3
Conventional clusters only
4
Can be specified independently for each broker in a cluster

Chapter 14 • Broker Properties Reference 303

JMX Properties

TABLE 14–10 Broker Properties for Cluster Configuration (Continued)

Default
Property Type Value Description

5,1
imq.cluster.clusterid String None Cluster identifier
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. No two running clusters may have the same
cluster identifier.
This string is appended to the names of all database tables in the
cluster’s shared persistent store.
Note – For brokers belonging to an HA cluster, this property is
used in database table names in place of imq.brokerid (see
Table 14–1).

imq.cluster.heartbeat.hostname5 String None Host name or IP address for heartbeat service

If specified, overrides imq.hostname (see Table 14–1) 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 Integer 2 Interval between heartbeats, in seconds

5
imq.cluster.heartbeat.threshold Integer 3 Number of missed heartbeat intervals after which to invoke
monitor service

imq.cluster.monitor.interval5 Integer 30 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 Integer 2 Number of missed monitor intervals after which to initiate

broker takeover
5
HA clusters only
1
Must have the same value for all brokers in a cluster

JMX Properties
The broker properties listed in Table 14–11 support the use of the Java Management Extensions
(JMX) application programming interface by Message Queue client programs to configure and
monitor Message Queue resources. None of these properties can be set from the command line
with the Command utility (imqcmd). Instead, they can either be set at broker startup with the -D
option of the Broker utility (imqbrokerd) or edited by hand in the broker's instance
configuration file (config.properties). In addition, some of these properties

304 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 JMX Properties

(imq.jmx.rmiregistry.start, imq.jmx.rmiregistry.use, imq.jmx.rmiregistry.port) can

be set with corresponding Broker utility options described in Table 13–1.

See Appendix D, “JMX Support” for further information on administrative support of JMX
clients.

TABLE 14–11 Broker Properties for JMX Support

Property Type Default Value Description

imq.jmx.connector.list String jmxrmi,ssljmxrmi Names of preconfigured JMX connectors,

separated by commas

imq.jmx.connector.activelist String jmxrmi Names of JMX connectors to be activated at

broker startup, separated by commas

imq.jmx.connector.connectorName.urlpath String See description urlPath component of JMX service URL for
connector connectorName
Useful in cases where the JMX service URL path
must be set explicitly (such as when a shared
external RMI registry is used).
Default value: If an RMI registry is used to
store the RMI stub for JMX connectors
(imq.jmx.registry.start or
imq.jmx.registry.use set to true):
/jndi/rmi://brokerHost:rmiPort
/brokerHost/brokerPort/connectorName
If an RMI registry is not used (the default case,
imq.jmx.registry.start and
imq.jmx.registry.use both false):
/stub/rmiStub
where rmiStub is an encoded and serialized
representation of the RMI stub itself

Chapter 14 • Broker Properties Reference 305

JMX Properties

TABLE 14–11 Broker Properties for JMX Support (Continued)

Property Type Default Value Description

imq.jmx.connector.connectorName.useSSL Boolean false Use Secure Socket Layer (SSL) for connector
connectorName?

imq.jmx.connector.connectorName.brokerHostTrusted Trust any certificate presented by broker for

connector connectorName?

Boolean false Applies only when

imq.jmx.connector.connectorName.useSSL
is true.
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.

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 it to store
the RMI stub for JMX connectors. Note that 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 to the Message Queue Broker utility
(imqbrokerd).

imq.jmx.rmiregistry.use Boolean false Use external RMI registry?

Applies only if imq.jmx.rmiregistry.start is
false.
If true, the broker will use an external RMI
registry at the port specified by
imq.jmx.rmiregistry.port to store the RMI
stub for JMX connectors. The external RMI
registry must already be running at broker
startup.
For convenience, this property can also be set at
broker startup with the -useRmiRegistry
option to the Message Queue Broker utility
(imqbrokerd).

306 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Alphabetical List of Broker Properties

TABLE 14–11 Broker Properties for JMX Support (Continued)

Property Type Default Value Description

imq.jmx.rmiregistry.port Integer 1099 Port number of RMI registry

Applies only if imq.jmx.rmiregistry.start or
imq.jmx.rmiregistry.use is true. JMX
connectors can then be configured to use the
RMI registry by including this port number in
the URL path of their JMX service URLs.
For convenience, this property can also be set at
broker startup with the -rmiRegistryPort
option to the Message Queue Broker utility
(imqbrokerd).

Alphabetical List of Broker Properties

“Alphabetical List of Broker Properties” on page 307 is an alphabetical list of broker
configuration properties, with cross-references to the relevant tables in this chapter.

TABLE 14–12 Alphabetical List of Broker Properties

Property Table

imq.accesscontrol.enabled Table 14–7

imq.accesscontrol.file.filename Table 14–7

imq.authentication.basic.user_repository Table 14–7

imq.authentication.client.response.timeout Table 14–7

imq.authentication.type Table 14–7

imq.autocreate.destination.isLocalOnly Table 14–3

imq.autocreate.destination.limitBehavior Table 14–3

imq.autocreate.destination.maxBytesPerMsg Table 14–3

imq.autocreate.destination.maxNumMsgs Table 14–3

imq.autocreate.destination.maxNumProducers Table 14–3

imq.autocreate.destination.maxTotalMsgBytes Table 14–3

imq.autocreate.destination.useDMQ Table 14–3

imq.autocreate.queue Table 14–3

imq.autocreate.queue.consumerFlowLimit Table 14–3

Chapter 14 • Broker Properties Reference 307

Alphabetical List of Broker Properties

TABLE 14–12 Alphabetical List of Broker Properties (Continued)

Property Table

imq.autocreate.queue.localDeliveryPreferred Table 14–3

imq.autocreate.queue.maxNumActiveConsumers Table 14–3

imq.autocreate.queue.maxNumBackupConsumers Table 14–3

imq.autocreate.topic Table 14–3

imq.autocreate.topic.consumerFlowLimit Table 14–3

imq.broker.adminDefinedRoles.count Table 14–9

imq.broker.adminDefinedRoles.namen Table 14–9

imq.brokerid Table 14–1

imq.cluster.brokerlist Table 14–10

imq.cluster.clusterid Table 14–10

imq.cluster.ha Table 14–10

imq.cluster.heartbeat.hostname Table 14–10

imq.cluster.heartbeat.interval Table 14–10

imq.cluster.heartbeat.port Table 14–10

imq.cluster.heartbeat.threshold Table 14–10

imq.cluster.hostname Table 14–10

imq.cluster.masterbroker Table 14–10

imq.cluster.monitor.interval Table 14–10

imq.cluster.monitor.threshold Table 14–10

imq.cluster.port Table 14–10

imq.cluster.transport Table 14–10

imq.cluster.url Table 14–10

imq.destination.DMQ.truncateBody Table 14–2

imq.destination.logDeadMsgs Table 14–9

imq.hostname Table 14–1

imq.imqcmd.password Table 14–7

imq.jmx.connector.activelist Table 14–11

imq.jmx.connector.connectorName.brokerHostTrusted Table 14–11

308 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Alphabetical List of Broker Properties

TABLE 14–12 Alphabetical List of Broker Properties (Continued)

Property Table

imq.jmx.connector.connectorName.urlpath Table 14–11

imq.jmx.connector.connectorName.useSSL Table 14–11

imq.jmx.connector.list Table 14–11

imq.jmx.rmiregistry.port Table 14–11

imq.jmx.rmiregistry.start Table 14–11

imq.jmx.rmiregistry.use Table 14–11

imq.keystore.file.dirpath Table 14–7

imq.keystore.file.name Table 14–7

imq.keystore.password Table 14–7

imq.keystore.propertyName Table 14–7

imq.log.console.output Table 14–9

imq.log.console.stream Table 14–9

imq.log.file.dirpath Table 14–9

imq.log.file.filename Table 14–9

imq.log.file.output Table 14–9

imq.log.file.rolloverbytes Table 14–9

imq.log.file.rolloversecs Table 14–9

imq.log.level Table 14–9

imq.log.syslog.facility Table 14–9

imq.log.syslog.identity Table 14–9

imq.log.syslog.logconsole Table 14–9

imq.log.syslog.logpid Table 14–9

imq.log.syslog.output Table 14–9

imq.log.timezone Table 14–9

imq.message.expiration.interval Table 14–2

imq.message.max_size Table 14–2

imq.metrics.enabled Table 14–9

imq.metrics.interval Table 14–9

Chapter 14 • Broker Properties Reference 309

Alphabetical List of Broker Properties

TABLE 14–12 Alphabetical List of Broker Properties (Continued)

Property Table

imq.metrics.topic.enabled Table 14–9

imq.metrics.topic.interval Table 14–9

imq.metrics.topic.persist Table 14–9

imq.metrics.topic.timetolive Table 14–9

imq.passfile.dirpath Table 14–7

imq.passfile.enabled Table 14–7

imq.passfile.name Table 14–7

imq.persist.file.destination.message.filepool.limit Table 14–5

imq.persist.file.message.cleanup Table 14–5

imq.persist.file.message.filepool.cleanratio Table 14–5

imq.persist.file.message.max_record_size Table 14–5

imq.persist.file.sync.enabled Table 14–5

imq.persist.file.transaction.memorymappedfile.enabled Table 14–5

imq.persist.jdbc.dbVendor Table 14–6

imq.persist.jdbc.vendorName.closedburl Table 14–6

imq.persist.jdbc.vendorName.createdburl Table 14–6

imq.persist.jdbc.vendorName.driver Table 14–6

imq.persist.jdbc.vendorName.needpassword Table 14–6

imq.persist.jdbc.vendorName.opendburl Table 14–6

imq.persist.jdbc.vendorName.password Table 14–6

imq.persist.jdbc.vendorName.property.propName Table 14–6

imq.persist.jdbc.vendorName.user Table 14–6

imq.persist.store Table 14–4

imq.ping.interval Table 14–1

imq.portmapper.backlog Table 14–1

imq.portmapper.hostname Table 14–1

imq.portmapper.port Table 14–1

imq.primaryowner.contact Table 14–9

310 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Alphabetical List of Broker Properties

TABLE 14–12 Alphabetical List of Broker Properties (Continued)

Property Table

imq.primaryowner.name Table 14–9

imq.resourceState.count Table 14–2

imq.resourceState.threshold Table 14–2

imq.service.activelist Table 14–1

imq.serviceName.accesscontrol.enabled Table 14–7

imq.serviceName.accesscontrol.file.filename Table 14–7

imq.serviceName.authentication.type Table 14–7

imq.serviceName.max_threads Table 14–1

imq.serviceName.min_threads Table 14–1

imq.serviceName.protocolType.hostname Table 14–1

imq.serviceName.protocolType.port Table 14–1

imq.serviceName.threadpool_model Table 14–1

imq.shared.connectionMonitor_limit Table 14–1

imq.system.max_count Table 14–2

imq.system.max_size Table 14–2

imq.transaction.autorollback Table 14–2

imq.user_repository.ldap.base Table 14–7

imq.user_repository.ldap.gidattr Table 14–7

imq.user_repository.ldap.grpbase Table 14–7

imq.user_repository.ldap.grpfilter Table 14–7

imq.user_repository.ldap.grpsearch Table 14–7

imq.user_repository.ldap.memattr Table 14–7

imq.user_repository.ldap.password Table 14–7

imq.user_repository.ldap.principal Table 14–7

imq.user_repository.ldap.propertyName Table 14–7

imq.user_repository.ldap.server Table 14–7

imq.user_repository.ldap.ssl.enabled Table 14–7

imq.user_repository.ldap.timeout Table 14–7

Chapter 14 • Broker Properties Reference 311

Alphabetical List of Broker Properties

TABLE 14–12 Alphabetical List of Broker Properties (Continued)

Property Table

imq.user_repository.ldap.uidattr Table 14–7

imq.user_repository.ldap.usrfilter Table 14–7

312 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 15
C H A P T E R 1 5

Physical Destination Property Reference

This chapter provides reference information about configuration properties for physical
destinations.

Physical Destination Properties

Table 15–1 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 broker’s instance configuration file (see Table 14–3).

TABLE 15–1 Physical Destination Properties

Property Type Default Value Description

maxNumMsgs1 Integer −1 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.

maxBytesPerMsg String −1 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)
1
In a cluster environment, applies to each individual instance of a destination rather than collectively to all instances in the cluster

313
Physical Destination Properties

TABLE 15–1 Physical Destination Properties (Continued)

Property Type Default Value Description

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

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

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.
1
In a cluster environment, applies to each individual instance of a destination rather than collectively to all instances in the cluster
2
Does not apply to dead message queue
3
Queue destinations only

314 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Physical Destination Properties

TABLE 15–1 Physical Destination Properties (Continued)

Property Type Default Value Description

consumerFlowLimit Integer 1000 Maximum number of messages delivered to 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.

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

localDeliveryPreferred2 ,3 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.
2
Does not apply to dead message queue
3
Queue destinations only

Chapter 15 • Physical Destination Property Reference 315

316
 16
C H A P T E R 1 6

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 317
■ “Destination Attributes” on page 325

Connection Factory Attributes

The attributes of a connection factory object are grouped into categories described in the
following sections below:
■ “Connection Handling” on page 317
■ “Client Identification” on page 321
■ “Reliability and Flow Control” on page 321
■ “Queue Browser and Server Sessions” on page 323
■ “Standard Message Properties” on page 324
■ “Message Header Overrides” on page 324

Connection Handling
Table 16–1 lists the connection factory attributes for connection handling.

317
Connection Factory Attributes

TABLE 16–1 Connection Factory Attributes for Connection Handling

Attribute Type Default Value Description

imqAddressList String An existing List of broker addresses

Message Queue 3.0
The list consists of one or more addresses, separated by
address, if any; if
commas. Each address specifies (or implies) the host name, port
none, the first
number, and connection service for a broker instance to which
entry in
the client can connect. Address syntax varies depending on the
Table 16–2
connection service and port assignment method; see below for
details.
Note – In a high-availability broker cluster, the value of this
attribute is updated dynamically as brokers enter and leave the
cluster, so that it always reflects the cluster’s 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 1 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 a high-availability 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.

318 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Connection Factory Attributes

TABLE 16–1 Connection Factory Attributes for Connection Handling (Continued)

Attribute Type Default Value Description

imqReconnectEnabled Boolean false Attempt to reestablish a lost connection?

Note – In the event of broker failure in a high-availability 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.

imqReconnectAttempts Integer 0 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.

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 16–2
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 16 • Administered Object Attribute Reference 319

Connection Factory Attributes

TABLE 16–2 Message Broker Addressing Schemes

Scheme Service Syntax Description

mq jms or [hostName][:portNumber][/serviceName] Assign port dynamically for jms or ssljms

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 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 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
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
rather than a randomly selected one: Message Queue tunnel servlet at the specified
URL. The broker must be configured to access
https://hostName:portNumber/contextRoot/tunnel?
the HTTPS tunnel servlet.
ServerName=hostName:instanceName

320 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Connection Factory Attributes

TABLE 16–3 Message Broker Address Examples

Service Broker Host Port Example Address

Not specified Not specified Not specified No address (mq://localHost:7676/jms)

Not specified Specified host Not specified myBkrHost (mq://myBkrHost:7676/jms)

Not specified Not specified Specified Port Mapper port 1012 (mq://localHost:1012/jms)

ssljms Local host Standard Port Mapper port mq://localHost:7676/ssljms

ssljms Specified host Standard Port Mapper port mq://myBkrHost:7676/ssljms

ssljms Specified host Specified Port Mapper port mq://myBkrHost:1012/ssljms

jms Local host Specified service port mqtcp://localhost:1032/jms

ssljms Specified host Specified service port mqssl://myBkrHost:1034/ssljms

httpjms Not applicable Not applicable http://websrvr1:8085/imq/tunnel

httpsjms Not applicable Not applicable https://websrvr2:8090/imq/tunnel

Client Identification
Table 16–4 lists the connection factory attributes for client identification.

TABLE 16–4 Connection Factory Attributes for Client Identification

Attribute Type Default Value Description

imqDefaultUsername String guest Default user name for authenticating with broker

imqDefaultPassword String guest Default password for authenticating with broker

imqConfiguredClientID String null Administratively configured client identifier

imqDisableSetClientID Boolean false Prevent client from changing client identifier using
setClientID method?

Reliability and Flow Control

Table 16–5 lists the connection factory attributes for reliability and flow control.

Chapter 16 • Administered Object Attribute Reference 321

Connection Factory Attributes

TABLE 16–5 Connection Factory Attributes for Reliability and Flow Control

Attribute Type Default Value Description

imqAckTimeout String 0 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 Boolean false Limit message flow at connection level?

imqConnectionFlowLimit Integer 1000 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.

322 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Connection Factory Attributes

TABLE 16–5 Connection Factory Attributes for Reliability and Flow Control (Continued)
Attribute Type Default Value Description

imqConsumerFlowLimit Integer 100 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 queue’s
own consumerFlowLimit attribute (see Chapter 15, “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 16–6 lists the connection factory attributes for queue browsing and server sessions.

TABLE 16–6 Connection Factory Attributes for Queue Browser and Server Sessions

Default
Attribute Type Value Description

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

Chapter 16 • Administered Object Attribute Reference 323

Connection Factory Attributes

TABLE 16–6 Connection Factory Attributes for Queue Browser and Server Sessions (Continued)
Default
Attribute Type Value Description

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 16–7 control whether the Message Queue
client runtime sets certain standard message properties defined in the Java Message Service
Specification.

TABLE 16–7 Connection Factory Attributes for Standard Message Properties

Property Type Default Value Description

imqSetJMSXUserID Boolean false Set JMSXUserID property (identity of user sending message) for
produced messages?

imqSetJMSXAppID Boolean false Set JMSXAppID property (identity of application sending

message) for produced messages?

imqSetJMSXProducerTXID Boolean false Set JMSXProducerTXID property (transaction identifier of

transaction within which message was produced) for produced
messages?

imqSetJMSXConsumerTXID Boolean false Set JMSXConsumerTXID property (transaction identifier of

transaction within which message was consumed) for
consumed messages?

imqSetJMSXRcvTimestamp Boolean false Set JMSXRcvTimestamp property (time message delivered to

consumer) for consumed messages?

Message Header Overrides

Table 16–8 lists the connection factory attributes for overriding JMS message header fields.

324 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Destination Attributes

TABLE 16–8 Connection Factory Attributes for Message Header Overrides

Attribute Type Default Value Description

imqOverrideJMSDeliveryMode Boolean false Allow client-set delivery mode to be

overridden?

imqJMSDeliveryMode Integer 2 Overriding value of delivery mode:

1 Nonpersistent
2 Persistent

imqOverrideJMSExpiration Boolean false Allow client-set expiration time to be

overridden?

imqJMSExpiration Long integer 0 Overriding value of expiration time, in

milliseconds
A value of 0 denotes an unlimited expiration
time (message never expires).

imqOverrideJMSPriority Boolean false Allow client-set priority level to be overridden?

imqJMSPriority Integer 4 (normal) Overriding value of priority level (0 to 9)

imqOverrideJMSHeadersToTemporaryDestinations Boolean false Apply overrides to temporary destinations?

Destination Attributes
Table 16–9 lists the attributes that can be set for a destination administered object.

TABLE 16–9 Destination Attributes

Attribute Type Default Value Description

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

Chapter 16 • Administered Object Attribute Reference 325

326
 17
C H A P T E R 1 7

JMS Resource Adapter Property Reference

This chapter describes the configuration properties of the Message Queue JMS Resource
Adapter (JMS RA), which enables you to integrate Sun JavaTM System 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 327) affects the
behavior of the Resource Adapter as a whole.
■ The ManagedConnectionFactory JavaBean (“ManagedConnectionFactory JavaBean” on
page 330) affects connections created by the Resource Adapter for use by message-driven
beans (MDBs).
■ The ActivationSpec JavaBean (“ActivationSpec JavaBean” on page 331) 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:

ResourceAdapter JavaBean
The ResourceAdapter configuration configures the default JMS Resource Adapter behavior.
Table 17–1 lists and describes the properties with which you can configure this JavaBean.

327
ResourceAdapter JavaBean

TABLE 17–1 Resource Adapter Properties

Property Type Default Value Description

addressList1 String mq://localhost:7676/jms Message service address for

connecting to Message Queue service
Equivalent to connectionURL (below).

connectionURL1 String mq://localhost:7676/jms Message service address for

connecting to the Message Queue
service
Equivalent to addressList(above).

brokerInstanceName String imqbroker Name of broker instance

brokerPort Integer 7676 Port number for connecting to broker

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 String guest Default user name for connecting to

Message Queue service

password2 String guest Default password for connecting to

Message Queue service

addressListBehavior String PRIORITY 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.

addressListIterations Integer 1 Number of times to iterate through

address list attempting to establish or
reestablish a connection

reconnectEnabled Boolean false Attempt to reestablish a lost

connection?
1
Exactly one of these properties must be specified
2
Required

328 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 ResourceAdapter JavaBean

TABLE 17–1 Resource Adapter Properties (Continued)

Property Type Default Value Description

reconnectAttempts Integer 6 Number of times to attempt

reconnection to each address in
address list before moving on to next

reconnectInterval Long integer 30000 Interval, in milliseconds, between

reconnection attempts

brokerEnableHA Boolean false Enable high availability?

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 (A–Z, a–z), numeric
digits (0–9), 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 a high-availability cluster, each
broker must have a unique broker
identifier.
The identifier may contain only
alphabetic letters (A–Z, a–z), numeric
digits (0–9), and the underscore
character (_).

Chapter 17 • JMS Resource Adapter Property Reference 329

ManagedConnectionFactory JavaBean

ManagedConnectionFactory JavaBean
A managed connection factory defines the connections that the Resource Adapter provides to a
message-driven bean. Table 17–2 shows the properties of the ManagedConnectionFactory
JavaBean; if set, these properties override the corresponding properties of the ResourceAdapter
JavaBean.

TABLE 17–2 Managed Connection Factory Properties

Property Type Default Value Description

addressList String Inherited from List of message service addresses for

ResourceAdapter JavaBean connecting to Message Queue service
(see Table 17–1)

userName1 String guest User name for connecting to Message

Queue service

password1 String guest Password for connecting to Message

Queue service

clientID String None Client identifier for connections to

Message Queue service

addressListBehavior String PRIORITY 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.

addressListIterations Integer 1 Number of times to iterate through

address list attempting to establish or
reestablish a connection

reconnectEnabled Boolean false Attempt to reestablish a lost

connection?

reconnectAttempts Integer 6 Number of times to attempt

reconnection to each address in
address list before moving on to next
1
Optional

330 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 ActivationSpec JavaBean

TABLE 17–2 Managed Connection Factory Properties (Continued)

Property Type Default Value Description

reconnectInterval Long integer 30000 Interval, in milliseconds, between

reconnection attempts

ActivationSpec JavaBean
Table 17–3 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 17–3 Activation Specification Properties

Property Type Default Value Description

addressList1,2 String Inherited from Message service address for

ResourceAdapter JavaBean connecting to Message Queue service

destination3 String None Name of destination from which to

consume messages
The value must be that of the
destinationName property for a
Message Queue destination
administered object.

destinationType3 String None Type of destination specified by

destination property:
javax.jms.Queue: Queue
destination
javax.jms.Topic: Topic
destination

messageSelector1,3 String None Message selector for filtering messages

delivered to consumer

subscriptionName3 String None Name for durable subscriptions

This property must be set if
subscriptionDurability is set to
Durable.
1
Optional
2
Property specific to Message Queue JMS Resource Adapter
3
Standard Enterprise JavaBean (EJB) and J2EE Connector Architecture (CA) property

Chapter 17 • JMS Resource Adapter Property Reference 331

ActivationSpec JavaBean

TABLE 17–3 Activation Specification Properties (Continued)

Property Type Default Value Description

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

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 6 Number of times to redeliver a

message when MDB throws an
exception during message delivery
3
Standard Enterprise JavaBean (EJB) and J2EE Connector Architecture (CA) property
1
Optional

332 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 ActivationSpec JavaBean

TABLE 17–3 Activation Specification Properties (Continued)

Property Type Default Value Description

sendUndeliverableMsgsToDMQ Boolean true 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.

Chapter 17 • JMS Resource Adapter Property Reference 333

334
 18
C H A P T E R

Metrics Reference
1 8

This chapter describes the metric information that a Message Queue message 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 203)
■ With the Command utility’s metrics bkr command (see “Broker Management” on
page 268)
■ In metrics messages sent to a metrics topic destination (see “Writing an Application to
Monitor Brokers” on page 210)

The tables in this chapter list the kinds of metric information available and the forms in which it
can be provided. For metrics provided through the Command utility’s metrics bkr command,
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. The chapter
consists of the following sections:
■ “JVM Metrics” on page 335
■ “Brokerwide Metrics” on page 336
■ “Connection Service Metrics” on page 338
■ “Physical Destination Metrics” on page 339

JVM Metrics
Table 18–1 shows the metric information that the broker reports for the broker process JVM
(Java Virtual Machine) heap.

335
Brokerwide Metrics

TABLE 18–1 JVM Metrics

metrics bkr
Metric Quantity Description Log File? Metric Type Metrics Topic

JVM heap: total memory Current total memory, in bytes Yes cxn mq.metrics.jvm

JVM heap: free memory Amount of memory currently available for use, in Yes cxn mq.metrics.jvm
bytes

JVM heap: max memory Maximum allowable heap size, in bytes Yes None mq.metrics.jvm

Brokerwide Metrics
Table 18–2 shows the brokerwide metric information that the broker reports.

TABLE 18–2 Brokerwide Metrics

metrics bkr
Metric Quantity Description Log File? Metric Type Metrics Topic

Connections

Num connections Total current number of connections for all Yes cxn mq.metrics.broker
connection services

Num threads Total current number of threads for all connection Yes cxn None
services

Min threads Total minimum number of threads for all connection Yes cxn None
services

Max threads Total maximum number of threads for all connection Yes cxn None
services

Stored Messages

Num messages Current number of payload messages stored in No None1 mq.metrics.broker

memory and persistent store

Total message bytes Total size in bytes of payload messages currently No None1 mq.metrics.broker
stored in memory and persistent store

Message Flow

Num messages in Cumulative number of payload messages received Yes ttl mq.metrics.broker
since broker started

Num messages out Cumulative number of payload messages sent since Yes ttl mq.metrics.broker
broker started
1
Use query bkr command instead

336 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Brokerwide Metrics

TABLE 18–2 Brokerwide Metrics (Continued)

metrics bkr
Metric Quantity Description Log File? Metric Type Metrics Topic

Rate messages in Current rate of flow of payload messages into broker Yes rts None

Rate messages out Current rate of flow of payload messages out of Yes rts None
broker

Message bytes in Cumulative size in bytes of payload messages Yes ttl mq.metrics.broker
received since broker started

Message bytes out Cumulative size in bytes of payload messages sent Yes ttl mq.metrics.broker
since broker started

Rate message bytes in Current rate of flow of payload message bytes into Yes rts None
broker

Rate message bytes out Current rate of flow of payload message bytes out of Yes rts None
broker

Num packets in Cumulative number of payload and control packets Yes ttl mq.metrics.broker
received since broker started

Num packets out Cumulative number of payload and control packets Yes ttl mq.metrics.broker
sent since broker started

Rate packets in Current rate of flow of payload and control packets Yes rts None
into broker

Rate packets out Current rate of flow of payload and control packets Yes rts None
out of broker

Packet bytes in Cumulative size in bytes of payload and control Yes ttl mq.metrics.broker
packets received since broker started

Packet bytes out Cumulative size in bytes of payload and control Yes ttl mq.metrics.broker
packets sent since broker started

Rate packet bytes in Current rate of flow of payload and control packet Yes rts None
bytes into broker

Rate packet bytes out Current rate of flow of payload and control packet Yes rts None
bytes out of broker

Destinations

Num destinations Current number of physical destinations No None mq.metrics.broker

Chapter 18 • Metrics Reference 337

Connection Service Metrics

Connection Service Metrics

Table 18–3 shows the metric information that the broker reports for individual connection
services.

TABLE 18–3 Connection Service Metrics

metrics svc
Metric Quantity Description Log File? Metric Type Metrics Topic

Connections

Num connections Current number of connections No cxn1 None

1
Num threads Current number of threads No cxn None

Min threads Minimum number of threads assigned to service No cxn None

Max threads Maximum number of threads assigned to service No cxn None

Message Flow

Num messages in Cumulative number of payload messages received No ttl None

through connection service since broker started

Num messages out Cumulative number of payload messages sent No ttl None
through connection service since broker started

Rate messages in Current rate of flow of payload messages into broker No rts None
through connection service

Rate messages out Current rate of flow of payload messages out of No rts None
broker through connection service

Message bytes in Cumulative size in bytes of payload messages No ttl None

received through connection service since broker
started

Message bytes out Cumulative size in bytes of payload messages sent No ttl None
through connection service since broker started

Rate message bytes in Current rate of flow of payload message bytes into No rts None
broker through connection service

Rate message bytes out Current rate of flow of payload message bytes out of No rts None
broker through connection service

Num packets in Cumulative number of payload and control packets No ttl None
received through connection service since broker
started

Num packets out Cumulative number of payload and control packets No ttl None
sent through connection service since broker started
1
Also available with query svc command

338 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Physical Destination Metrics

TABLE 18–3 Connection Service Metrics (Continued)

metrics svc
Metric Quantity Description Log File? Metric Type Metrics Topic

Rate packets in Current rate of flow of payload and control packets No rts None
into broker through connection service

Rate packets out Current rate of flow of payload and control packets No rts None
out of broker through connection service

Packet bytes in Cumulative size in bytes of payload and control No ttl None
packets received through connection service since
broker started

Packet bytes out Cumulative size in bytes of payload and control No ttl None
packets sent through connection service since broker
started

Rate packet bytes in Current rate of flow of payload and control packet No rts None
bytes into broker through connection service

Rate packet bytes out Current rate of flow of payload and control packet No rts None
bytes out of broker through connection service

Physical Destination Metrics

Table 18–4 shows the metric information that the broker reports for individual destinations.

TABLE 18–4 Physical Destination Metrics

metrics dst
Metric Quantity Description Log File? Metric Type Metrics Topic

Message Consumers

Num consumers Current number of No con mq.metrics.destination.queue.queueName

associated message mq.metrics.destination.topic.topicName
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.”

Chapter 18 • Metrics Reference 339

Physical Destination Metrics

TABLE 18–4 Physical Destination Metrics (Continued)

metrics dst
Metric Quantity Description Log File? Metric Type Metrics Topic

Peak num consumers Peak number of No con mq.metrics.destination.queue.queueName

associated message mq.metrics.destination.topic.topicName
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.”

Avg num consumers Average number of No con mq.metrics.destination.queue.queueName

associated message mq.metrics.destination.topic.topicName
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.”

Num active consumers Current number of No con mq.metrics.destination.queue.queueName

associated active message mq.metrics.destination.topic.topicName
consumers
For topic destinations,
this attribute includes
both nondurable and
(active and inactive)
durable subscribers and
is equivalent to “Num
consumers.”

340 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Physical Destination Metrics

TABLE 18–4 Physical Destination Metrics (Continued)

metrics dst
Metric Quantity Description Log File? Metric Type Metrics Topic

Peak num active consumers Peak number of No con mq.metrics.destination.queue.queueName

associated active message mq.metrics.destination.topic.topicName
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.”

Avg num active consumers Average number of No con mq.metrics.destination.queue.queueName

associated active message mq.metrics.destination.topic.topicName
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.”

Num backup consumers1 Current number of No con mq.metrics.destination.queue.queueName

associated backup mq.metrics.destination.topic.topicName
message consumers

Peak num backup consumers1 Peak number of No con mq.metrics.destination.queue.queueName

associated backup mq.metrics.destination.topic.topicName
message consumers since
broker started

Avg num backup consumers1 Average number of No con mq.metrics.destination.queue.queueName

associated backup mq.metrics.destination.topic.topicName
message consumers since
broker started

Stored Messages

Num messages Current number of No con mq.metrics.destination.queue.queueName

messages stored in ttl mq.metrics.destination.topic.topicName
memory and persistent rts2
store
1
Queue destinations only
2
Also available with query dst command

Chapter 18 • Metrics Reference 341

Physical Destination Metrics

TABLE 18–4 Physical Destination Metrics (Continued)

metrics dst
Metric Quantity Description Log File? Metric Type Metrics Topic

Peak num messages Peak number of messages No con mq.metrics.destination.queue.queueName

stored in memory and ttl mq.metrics.destination.topic.topicName
persistent store since rts
broker started

Avg num messages Average number of No con mq.metrics.destination.queue.queueName

messages stored in ttl mq.metrics.destination.topic.topicName
memory and persistent rts
store since broker started

Total message bytes Current total size in bytes No ttl mq.metrics.destination.queue.queueName

of messages stored in rts2 mq.metrics.destination.topic.topicName
memory and persistent
store

Peak total message bytes Peak total size in bytes of No ttl mq.metrics.destination.queue.queueName
messages stored in rts mq.metrics.destination.topic.topicName
memory and persistent
store since broker started

Avg total message bytes Average total size in bytes No ttl mq.metrics.destination.queue.queueName
of messages stored in rts mq.metrics.destination.topic.topicName
memory and persistent
store since broker started

Message Flow

Num messages in Cumulative number of No ttl mq.metrics.destination.queue.queueName

messages received since mq.metrics.destination.topic.topicName
broker started

Num messages out Cumulative number of No ttl mq.metrics.destination.queue.queueName

messages sent since mq.metrics.destination.topic.topicName
broker started

Msg bytes in Cumulative size in bytes No ttl mq.metrics.destination.queue.queueName

of messages received mq.metrics.destination.topic.topicName
since broker started

Msg bytes out Cumulative size in bytes No ttl mq.metrics.destination.queue.queueName

of messages sent since mq.metrics.destination.topic.topicName
broker started

Peak message bytes Size in bytes of largest No ttl mq.metrics.destination.queue.queueName

single message received rts mq.metrics.destination.topic.topicName
since broker started
2
Also available with query dst command

342 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Physical Destination Metrics

TABLE 18–4 Physical Destination Metrics (Continued)

metrics dst
Metric Quantity Description Log File? Metric Type Metrics Topic

Rate num messages in Current rate of flow of No rts None

messages received

Rate num messages out Current rate of flow of No rts None

messages sent

Rate msg bytes in Current rate of flow of No rts None

message bytes received

Rate msg bytes out Current rate of flow of No rts None

message bytes sent

Disk Utilization

Disk reserved3 Amount of disk space, in No dsk mq.metrics.destination.queue.queueName

bytes, reserved for mq.metrics.destination.topic.topicName
destination

Disk used3 Amount of disk space, in No dsk mq.metrics.destination.queue.queueName

bytes, currently in use by mq.metrics.destination.topic.topicName
destination

Disk utilization ratio3 Ratio of disk space in use No dsk mq.metrics.destination.queue.queueName

to disk space reserved for mq.metrics.destination.topic.topicName
destination
3
File-based persistence only

Chapter 18 • Metrics Reference 343

344
 19
C H A P T E R 1 9

JES Monitoring Framework Reference

This chapter describes the monitoring information items that Message Queue exposes through
the Sun JavaTM Enterprise System Monitoring Framework (JESMF), using the Monitoring
Framework’s Common Monitoring Model (CMM). It contains the following sections:
■ “Common Attributes” on page 345
■ “Message Queue Product Information” on page 346
■ “Broker Information” on page 346
■ “Port Mapper Information” on page 347
■ “Connection Service Information” on page 347
■ “Destination Information” on page 349
■ “Persistent Store Information” on page 350
■ “User Repository Information” on page 350

Common Attributes
The attributes listed in Table 19–1 are common to all (or almost all) CMM objects.

TABLE 19–1 JESMF Common Object Attributes

Attribute Description

Name Object name

Caption Short description

Description Full description

LastUpdateTime Time last updated

OperationalStatus Current status (for example, OK or DORMANT)

StatusDescriptions Description of status

345
Message Queue Product Information

TABLE 19–1 JESMF Common Object Attributes (Continued)

Attribute Description

OperationalStatusLastChange Time of last change in operational status

Message Queue Product Information

Table 19–2 shows attributes of the Message Queue product itself that can be accessed with
JESMF.

TABLE 19–2 JESMF-Accessible Message Queue Product Attributes

Attribute Description

ProductName Product name

ProductIdentifyingNumber Identifying number of product, in the form

urn:uuid:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Value changes for every version.

ProductVendor Vendor name

ProductVersion Version number

RevisionNumber Revision number

BuildNumber Build number

PatchID Patch identifier (if any)

CollectionID Identification key for installed product object

Differentiates among product installations; usually identifies the installation
location.

InstallDate Installation date

Broker Information
Table 19–3 shows the JESMF-accessible attributes pertaining to each broker instance.

TABLE 19–3 JESMF-Accessible Message Queue Broker Attributes

Attribute Description

PrimaryOwnerName Name of primary system owner (broker property imq.primaryowner.name;

see Table 14–9)

346 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Connection Service Information

TABLE 19–3 JESMF-Accessible Message Queue Broker Attributes (Continued)

Attribute Description

PrimaryOwnerContact Contact information for primary system owner (broker property

imq.primaryowner.contact; see Table 14–9)

Roles Array of strings denoting broker’s roles (taken from broker properties
imq.broker.adminDefinedRoles.namen; see Table 14–9)

StartupTime Time of last startup (date and time in milliseconds)

URL URL of Port Mapper

ConfigurationDirectory Broker instance directory (for example, /var/imq/instances/mybroker)

DirectoryName 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 19–4 provide information about a broker’s Port Mapper.

TABLE 19–4 JESMF-Accessible Message Queue Port Mapper Attributes

Attribute Description

LabeledURI URI for accessing Port Mapper, in the form

mq://hostName:portNumber

Secured Is Port Mapper access secure (SSL/TLS)?

Connection Service Information

Table 19–5 shows the JESMF-accessible attributes pertaining to each connection service.

Chapter 19 • JES Monitoring Framework Reference 347

Connection Service Information

TABLE 19–5 JESMF-Accessible Message Queue Connection Service Attributes

Attribute 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 Is connection service access secure (SSL/TLS)?

ConnectionsCount Current number of connections

NumConnectionsCreated Cumulative number of connections created since broker started

FailedConnectionsCount Cumulative number of connections rejected since broker started

CurrentNumberOfThreads Current number of threads actively handling connections

MinThreadPoolSize Minimum number of threads maintained in connection service’s thread

pool (broker property imq.serviceName.min_threads; see Table 14–1)

MaxThreadPoolSize 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 14–1)

NumProducers Current number of message producers

NumConsumers Current number of message consumers

NumMsgsIn Cumulative number of messages received since broker started

NumMsgsOut Cumulative number of messages sent since broker started

InBytesCount Cumulative size in bytes of messages received since broker started

OutBytesCount Cumulative size in bytes of messages sent since broker started

NumPktsIn Cumulative number of packets received since broker started

NumPktsOut Cumulative number of packets sent since broker started

PktBytesIn Cumulative size in bytes of packets received since broker started

PktBytesOut Cumulative size in bytes of packets sent since broker started

348 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Destination Information

Destination Information
Table 19–6 shows the JESMF-accessible attributes pertaining to each destination. Each of these
attributes corresponds to a Message Queue physical destination property; see Table 15–1 for
further information.

TABLE 19–6 JESMF-Accessible Message Queue Destination Attributes

Attribute Corresponding Property Description

Type Destination type (q = queue, t = topic)

MaxNumMsgs maxNumMsgs Maximum number of unconsumed

messages

MaxBytesPerMsg maxBytesPerMsg Maximum size, in bytes, of any single

message

MaxTotalMsgBytes maxTotalMsgBytes Maximum total memory, in bytes, for

unconsumed messages

LimitBehavior limitBehavior Broker behavior when memory-limit

threshold reached

MaxNumProducers1 maxNumProducers Maximum number of associated message

producers

MaxNumActiveConsumers2 maxNumActiveConsumers Maximum number of associated active

message consumers in load-balanced
delivery

MaxNumBackupConsumers2 maxNumBackupConsumers Maximum number of associated backup

message consumers in load-balanced
delivery

ConsumerFlowLimit consumerFlowLimit Maximum number of messages delivered

to consumer in a single batch

LocalOnly1 isLocalOnly Local delivery only?

LocalDeliveryPreferred1 ,2 localDeliveryPreferred Local delivery preferred?

1
UseDMQ useDMQ Send dead messages to dead message
queue?
1
Does not apply to dead message queue
2
Queue destinations only

Chapter 19 • JES Monitoring Framework Reference 349

Persistent Store Information

Persistent Store Information

The attributes shown in Table 19–7 pertain to the persistent data store.

TABLE 19–7 JESMF-Accessible Message Queue Persistent Store Attributes

Attribute Description

AccessInfo URL for accessing JDBC database

InfoFormat Format of AccessInfo attribute (URL)

JDBCDriver JDBC driver

UserName User name for authentication

User Repository Information

The attributes shown in Table 19–8 pertain to the LDAP user repository.

TABLE 19–8 JESMF-Accessible Message Queue User Repository Attributes

Attribute Description

AccessInfo URL for accessing LDAP server

InfoFormat Format of AccessInfo attribute (URL)

Base Root or base node for user lookup

GroupBase Root or base node for group lookup

UserName User name for authentication

350 Sun Java System Message Queue 4.1 Administration Guide • September 2007
P A R T I V

Appendixes
■ Appendix A, “Platform-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”

351
352
 A
A P P E N D I X A

Platform-Specific Locations of Message Queue

Data

Sun JavaTM System Message Queue data is stored in different locations on different operating
system platforms. The tables that follow show the location of various types of Message Queue
data on the following platforms:
■ “Solaris” on page 353
■ “Linux” on page 354
■ “Windows” on page 355

In the tables, instanceName denotes the name of the broker instance with which the data is
associated.

Solaris
Table A–1 shows the location of Message Queue data on the Solaris operating system. If you are
using Message Queue on Solaris with the standalone version of Sun Java System Application
Server, the directory structure is like that described under “Windows” on page 355.

TABLE A–1 Message Queue Data Locations on Solaris Platform

Data Category Location

Broker instance /var/imq/instances/instanceName/props/config.properties

configuration properties

Broker configuration file /usr/share/lib/imq/props/broker/

templates

Persistent store (messages, /var/imq/instances/instanceName/fs370

destinations, durable or a JDBC-accessible data store
subscriptions,
transactions)

353
Linux

TABLE A–1 Message Queue Data Locations on Solaris Platform (Continued)

Data Category Location

Broker instance log file /var/imq/instances/instanceName/log/

directory (default location)

Administered objects Local directory of your choice or an LDAP server

(object store)

Security: user repository /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 /etc/imq/passfile.sample

password file

Security: broker’s key store /etc/imq/

file location

JavaDoc API /usr/share/javadoc/imq/index.html

documentation

Example applications and /usr/demo/imq/

configurations

Java archive (.jar), Web /usr/share/lib/

archive (.war), and
Resource Adapter archive
(.rar) files

Linux
Table A–2 shows the location of Message Queue data on the Linux operating system.

TABLE A–2 Message Queue Data Locations on Linux Platform

Data Category Location

Broker instance /var/opt/sun/mq/instances/instanceName/props/config.properties

configuration properties

Broker configuration file /opt/sun/mq/private/share/lib/props/

templates

354 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Windows

TABLE A–2 Message Queue Data Locations on Linux Platform (Continued)

Data Category Location

Persistent store (messages, /var/opt/sun/mq/instances/instanceName/fs370/

destinations, durable or a JDBC-accessible data store
subscriptions,
transactions)

Broker instance log file /var/opt/sun/mq/instances/instanceName/log/

directory (default location)

Administered objects Local directory of your choice or an LDAP server

(object store)

Security: user repository /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)

Security: password file /var/opt/sun/mq/instances/instanceName/etc/

directory (default location)

Security: example /etc/opt/sun/mq/passfile.sample

password file

Security: broker’s key store /etc/opt/sun/mq/

file location

JavaDoc API /opt/sun/mq/javadoc/index.html

documentation

Example applications and /opt/sun/mq/examples/

configurations

Java archive (.jar), Web /opt/sun/mq/share/lib/

archive (.war), and
Resource Adapter archive
(.rar) files

Shared library (.so) files /opt/sun/mq/lib/

Windows
Table A–3 shows the location of Message Queue data on the Windows operating system. The
table also applies to the Solaris platform when Message Queue is bundled with the standalone
version of Sun Java System Application Server. That version of Application Server is bundled
with neither Solaris nor Sun Java Enterprise System. Use the pathnames in Table A–3, but
change the direction of the slash characters from the Windows backslash (\) to the Solaris
forward slash (/). See“Directory Variable Conventions” on page 25 for definitions of the
IMQ_HOME and IMQ_VARHOME directory variables.

Appendix A • Platform-Specific Locations of Message Queue Data 355

Windows

TABLE A–3 Message Queue Data Locations on Windows Platform

Data Category Location

Broker instance IMQ_VARHOME\instances\instanceName\props\config.properties

configuration properties

Broker configuration file IMQ_HOME\lib\props\broker\

templates

Persistent store (messages, IMQ_VARHOME\instances\instanceName\fs370\

destinations, durable or a JDBC-accessible data store
subscriptions,
transactions)

Broker instance log file IMQ_VARHOME\instances\instanceName\log\

directory (default location)

Administered objects Local directory of your choice or an LDAP server

(object store)

Security: user repository 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 IMQ_HOME\etc\passfile.sample

password file

Security: broker’s key store IMQ_HOME\etc\

file location

JavaDoc API IMQ_HOME\javadoc\index.html

documentation

Example applications and IMQ_HOME\demo\

configurations

Java archive (.jar), Web IMQ_HOME\lib\

archive (.war), and
Resource Adapter archive
(.rar) files

356 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 B
A P P E N D I X B

Stability of Message Queue Interfaces

Sun JavaTM System Message Queue uses many interfaces that can help administrators automate
tasks. This appendix classifies the interfaces according to their stability. The more stable an
interface is, the less likely it is to change in subsequent versions of the product.

Any interface that is not listed in this appendix is private and not for customer use.

Classification Scheme
Appendix B, “Stability of Message Queue Interfaces” describes the stability classification
scheme.

TABLE B–1 Interface Stability Classification Scheme

Classification Description

Private Not for direct use by customers. May change or be removed in any release.

Evolving For use by customers. Subject to incompatible change at a major (e.g. 3.0,
4.0) or minor (e.g. 3.1, 3.2) release. The changes will be made carefully and
slowly. Reasonable efforts will be made to ensure that all changes are
compatible but that is not guaranteed.

Stable For use by customers. Subject to incompatible change at a major (for

example, 3.0 or 4.0) release only.

Standard For use by customers. These interfaces are defined by a formal standard, and
controlled by a standards organization. Incompatible changes to these
interfaces are rare.

357
Interface Stability

TABLE B–1 Interface Stability Classification Scheme (Continued)

Classification Description

Unstable For use by customers. Subject to incompatible change at a major (e.g. 3.0,
4.0) or minor (e.g. 3.1, 3.2) release. Customers are advised that these
interfaces may be removed or changed substantially and in an incompatible
way in a future release. It is recommended that customers not create explicit
dependencies on unstable interfaces.

Interface Stability
Appendix B, “Stability of Message Queue Interfaces” lists the interfaces and their classifications.

TABLE B–2 Stability of Message Queue Interfaces

Interface Classification

Command Line Interfaces

imqbrokerd command line interface Evolving

imqadmin command line interface Unstable

imqcmd command line interface Evolving

imqdbmgr command line interface Unstable

imqkeytool command line interface Evolving

imqobjmgr command line interface Evolving

imqusermgr command line interface Unstable

Output from imqbrokerd, imqadmin, imqcmd, imqdbmgr, imqkeytool, imqobjmgr, Unstable

imqusermgr

Commands

imqobjmgr command file Evolving

imqbrokerd command Stable

imqadmin command Unstable

imqcmd command Stable

imqdbmgr command Unstable

imqkeytool command Stable

imqobjmgr command Stable

358 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Interface Stability

TABLE B–2 Stability of Message Queue Interfaces (Continued)

Interface Classification

imqusermgr command Unstable

APIs

JMS API (javax.jms) Standard

JAXM API (javax.xml) Standard

C-API Evolving

C-API environment variables Unstable

Message-based monitoring API Evolving

Administered Object API (com.sun.messaging) Evolving

.jar and .war Files

imq.jar location and name Stable

jms.jar location and name Evolving

imqbroker.jar location and name Private

imqutil.jar location and name Private

imqadmin.jar location and name Private

imqservlet.jar location and name Evolving

imqhttp.war location and name Evolving

imqhttps.war location and name Evolving

imqjmsra.rar location and name Evolving

imqxm.jar location and name Evolving

jaxm-api.jar location and name Evolving

saaj-api.jar location and name Evolving

saaj-impl.jar location and name Evolving

activation.jar location and name Evolving

mail.jar location and name Evolving

dom4j.jar location and name Private

fscontext.jar location and name Unstable

Files

Broker log file location and content format Unstable

Appendix B • Stability of Message Queue Interfaces 359

Interface Stability

TABLE B–2 Stability of Message Queue Interfaces (Continued)

Interface Classification

password file Unstable

accesscontrol.properties file Unstable

System Destinations

mq.sys.dmq destination Stable

mq.metrics.* destinations Evolving

Configuration Properties

Message Queue JMS Resource Adapter configuration properties Evolving

Message Queue JMS Resource Adapter JavaBean and ActivationSpec configuration Evolving
properties

Message Properties and Formats

Dead message queue message property, JMSXDeliveryCount Standard

Dead message queue message properties, JMS_SUN_* Evolving

Message Queue client message properties: JMS_SUN_* Evolving

JMS message format for metrics or monitoring messages Evolving

Miscellaneous

Message Queue JMS Resource Adapter package, com.sun.messaging.jms.ra Evolving

JDBC schema for storage of persistent messages Evolving

360 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 C
A P P E N D I X

HTTP/HTTPS Support
C

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 361
■ “Enabling HTTP/HTTPS Support” on page 362
■ “Troubleshooting” on page 377

HTTP/HTTPS Support Architecture

Message Queue’s support architecture is very similar for both HTTP and HTTPS support, as
shown in Figure C–1:
■ On the client side, an HTTP or HTTPS transport driver (part of the Message Queue client
runtime) encapsulates each message into an HTTP request and makes sure that these
requests are transmitted in the correct sequence.
■ If necessary, the client can use an HTTP proxy server to communicate with the broker. The
proxy’s address is specified using command line options when starting the client; see“Using
an HTTP Proxy” on page 376 for more information.
■ An HTTP or HTTPS tunnel servlet (both bundled with Message Queue) is loaded into an
application server or Web server on the broker side and used to pull payload messages from
client HTTP requests before forwarding them to the broker. The tunnel servlet also sends
broker messages back to the client in response to the client’s HTTP requests. A single tunnel
servlet can be used to access multiple brokers.

361
Enabling HTTP/HTTPS Support

■ On the broker side, the httpjms or httpsjms connection service unwraps and
demultiplexes incoming messages from the corresponding tunnel servlet.

Broker

httpjms/httpsjms
Connection
Services

JMS Client
TLS TCP
Message Queue
HTTP
Client Runtime
HTTP
Tunnel
Servlet
Firewall

HTTPS HTTPS
Tunnel
Servlet
HTTP
Proxy Web Server or
Application Server

FIGURE C–1 HTTP/HTTPS Support Architecture

The main difference between HTTP and HTTPS connections is that in the HTTPS case
(httpsjms connection service), the tunnel servlet has a secure connection to both the client
application and the broker. The secure connection to the broker is established by means of the
Secure Socket Layer (SSL) protocol. Message Queue’s SSL-enabled HTTPS tunnel servlet passes
a self-signed certificate to any broker requesting a connection. The broker uses the certificate to
establish an encrypted connection to the tunnel servlet. Once this connection is established, a
secure connection between the client application and the tunnel servlet can be negotiated by the
client application and the application server or Web server.

Enabling HTTP/HTTPS Support

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 servlet’s .war file to specify
the location and password of the certificate key store.

362 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Enabling HTTP/HTTPS Support

3. (HTTPS only) Validate the Web or application server’s self-signed certificate and install it in
the client application’s trust store.
4. (HTTP and HTTPS) Deploy the HTTP or HTTPS tunnel servlet.
5. (HTTP and HTTPS) Configure the broker’s 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 JavaTM System
Application Server as an example for purposes of illustration. If you are using a different
application server or Web server (such as Sun Java System Web Server), the procedures will be
substantially similar but may differ in detail; see your server product’s own documentation for
specifics.

Step 1 (HTTPS Only): Generating a Self-Signed

Certificate for the Tunnel Servlet
Message Queue’s SSL support is oriented toward securing on-the-wire data, on the assumption
that the client is communicating with a known and trusted server. Therefore, SSL is
implemented using only self-signed server certificates. Before establishing an HTTPS
connection, you must obtain such a certificate. (This step is not needed for ordinary,
non-secure HTTP connections.)

Run the Message Queue Key Tool utility (imqkeytool) to generate a self-signed certificate for
the tunnel servlet. (On UNIX systems, you may need to run the utility as the root user in order
to have permission to create the key store.) Enter the following at the command prompt:

imqkeytool -servlet keyStoreLocation

where keyStoreLocation is the location of Message Queue’s key store file.

The Key Tool utility prompts you for a key store password:

Enter keystore password:

After you have entered a valid password, the utility prompts you for identifying information
from which to construct an X.500 distinguished name. Table C–1 shows the prompts and the
values to be provided for each prompt. Values are case-insensitive and can include spaces.

Appendix C • HTTP/HTTPS Support 363

Enabling HTTP/HTTPS Support

TABLE C–1 Distinguished Name Information Required for a Self-Signed Certificate

Prompt X.500 Attribute Description Example

What is your first and last commonName (CN) Fully qualified name of server running mqserver.sun.com
name? the broker

What is the name of your organizationalUnit (OU) Name of department or division purchasing
organizational unit?

What is the name of your organizationName (ON) Name of larger organization, such as a Acme Widgets, Inc.
organization? company or government entity

What is the name of your city localityName (L) Name of city or locality San Francisco
or locality?

What is the name of your state stateName (ST) Full (unabbreviated) name of state or California
or province? province

What is the two-letter country (C) Standard two-letter country code US

country code for this unit?

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 Queue’s 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 370).

364 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Enabling HTTP/HTTPS Support

Step 2 (HTTPS Only): Specifying the Key Store Location

and Password
The tunnel servlet’s Web archive (.war) file includes a deployment descriptor, an XML file
containing the basic configuration information needed by the application server or Web server
to load and run the servlet. Before deploying the .war file for the HTTPS tunnel servlet, you
must edit the deployment descriptor to specify the location and password of the certificate key
store. (This step is not needed for ordinary, non-secure HTTP connections.)

▼ 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 servlet’s .war file varies, depending on your platform (see
Appendix A, “Platform-Specific Locations of Message Queue Data”):
Solaris: cp /usr/share/lib/imq/imqhttps.war /tmp
Linux: cp /opt/sun/mq/share/lib/imqhttps.war /tmp
Windows: cp IMQ_HOME\lib\imqhttps.war \tmp

2 Make the temporary directory your current directory.

cd /tmp

3 Extract the contents of the .war file.

jar xvf imqhttps.war

4 List the .war file’s deployment descriptor.

Enter the command
ls -l WEB-INF/web.xml
to confirm that the deployment descriptor file (WEB-INF/web.xml) was successfully extracted.

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

Enabling HTTP/HTTPS Support

</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

Server’s Self-Signed Certificate
In order for a client application to communicate with the Web or application server, you must
validate the server’s self-signed certificate and install it in the application’s trust store. The
following procedure shows how:

▼ To Validate and Install the Server’s Self-Signed Certificate

1 Validate the server’s certificate.

By default, the Sun Java System Application Server generates a self-signed certificate and stores
it in a key store file at the location
appServerRoot/glassfish/domains/domain1/config/keystore.jks
where appServerRoot is the root directory in which the Application Server is installed.

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

366 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Enabling HTTP/HTTPS Support

a. Make the directory containing the key store file your current directory.
For example, to use the Application Server’s default key store file (as shown above), navigate
to its directory with the command
cd appServerRoot/glassfish/domains/domain1/config
where appServerRoot is, again, the root directory in which the Application Server is
installed.

b. List the contents of the key store file.

The Key Tool utility’s -list option lists the contents of a specified key store file. For
example, the following command lists the Application Server’s default key store file
(keystore.jks):
keytool -list -keystore keystore.jks -v
The -v option tells the Key Tool utility to display certificate fingerprints in human-readable
form.

c. Enter the key store password.

The Key Tool utility prompts you for the key store file’s password:
Enter keystore password:
By default, the key store password is set to changeit; you can use the Key Tool utility’s
-storepasswd option to change it to something more secure. After you have entered a valid
password, the Key Tool utility will respond with output like the following:

Appendix C • HTTP/HTTPS Support 367

Enabling HTTP/HTTPS Support

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 certificate’s fingerprints.

Obtain the correct fingerprints for the Application Server’s self-signed certificate by
independent means (such as by telephone) and compare them with the fingerprints
displayed by the keytool -list command. Do not accept the certificate and install it in
your application’s trust store unless the fingerprints match.

2 Export the Application Server’s certificate to a certificate file.

Use the Key Tool utility’s -export option to export the certificate from the Application Server’s
key store to a separate certificate file, from which you can then import it into your application’s
trust store. For example, the following command exports the certificate shown above, whose
alias is slas, from the Application Server’s default key store (keystore.jks) to a certificate file
named slas.cer:
keytool -export -keystore keystore.jks -storepass changeit
-alias slas -file slas.cer
The Key Tool utility responds with the output

Certificate stored in file <slas.cer>

368 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Enabling HTTP/HTTPS Support

3 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 utility’s -printcert option lists the contents of a specified certificate file. For
example, the following command lists the certificate file slas.cer that was created in the
preceding step:
keytool -printcert -file slas.cer -v
Once again, the -v option tells the Key Tool utility to display the certificate’s fingerprints in
human-readable form. The resulting output looks like the following:

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 certificate’s contents.

Examine the output from the keytool -printcert command to make sure that the
certificate is correct.

4 Import the certificate into your application’s trust store.

The Key Tool utility’s -import option installs a certificate from a certificate file in a specified
trust store. For example, if your client application’s trust store is kept in the file
/local/tmp/imqhttps/appKeyStore, the following command will install the certificate from
the file slas.cer created above:
keytool -import -file slas.cer -keystore "/local/tmp/imqhttps/appKeyStore"

Appendix C • HTTP/HTTPS Support 369

Enabling HTTP/HTTPS Support

Step 4 (HTTP and HTTPS): Deploying the Tunnel

Servlet
You can deploy the HTTP or HTTPS tunnel servlet on Sun Java System Application Server
either from the command line or by using the Application Server’s Web-based administration
GUI. In either case, you must then modify the Application Server’s security policy file to grant
permissions for the tunnel servlet.

To deploy the tunnel servlet from the command line, use the deploy subcommand of the
Application Server administration utility (asadmin): for example,

asadmin deploy --user admin --passwordfile pfile.txt --force=true

/local/tmp/imqhttps/imqhttps.war

The procedure below shows how to use the Web-based GUI to deploy the servlet.

After deploying the tunnel servlet (whether from the command line or with the Web-based
GUI), proceed to “Modifying the Application Server’s Security Policy File” on page 371 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.

2 Specify the .war file location:

a. Enter the location of the tunnel servlet’s Web archive file (imqhttp.war or imqhttps.war) in
the File Path text field.
The file is located in the Message Queue installation directory containing .jar, .war, and
.rar files, depending on your operating system platform (see Appendix A,
“Platform-Specific Locations of Message Queue Data”).

b. Click the OK button.

370 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Enabling HTTP/HTTPS Support

3 Specify the context root directory:

a. Enter the /contextRoot portion of the tunnel servlet’s URL.

The URL has the form
http://hostName:portNumber/contextRoot/tunnel
or
https://hostName:portNumber/contextRoot/tunnel
For example, if the URL for the tunnel servlet is
http://hostName:portNumber/imq/tunnel
the value you enter would be
/imq

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.

4 Modify the server’s security policy file

Once you have deployed the HTTP or HTTPS tunnel servlet, you must grant it the appropriate
permissions by modifying the Application Server’s security policy file, as described in the next
procedure.

▼ Modifying the Application Server’s 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

Appendix C • HTTP/HTTPS Support 371

Enabling HTTP/HTTPS Support

where appServerRoot is the root directory in which Sun Java System 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";
};

3 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 C–2 shows broker configuration properties pertaining specifically to these two
connection services. Once reconfigured, the broker can be started normally, as described under
“Starting Brokers” on page 68.

TABLE C–2 Broker Configuration Properties for the httpjms and httpsjms Connection Services

Property Type Default Value Description

imq.httpjms.http.servletHost String localhost Host name or IP address of (local or remote) host

imq.httpsjms.https.servletHost running tunnel servlet

imq.httpjms.http.servletPort Integer httpjms: 7675 Port number of tunnel servlet

imq.httpsjms.https.servletPort httpsjms: 7674

imq.httpjms.http.pullPeriod Integer −1 Interval, in seconds, between client HTTP/HTTPS

imq.httpsjms.https.pullPeriod requests
If zero or negative, the client will keep one request
pending at all times.

imq.httpjms.http.connectionTimeout Integer 60 Tunnel servlet timeout interval

imq.httpsjms.https.connectionTimeout

▼ To Activate the httpjms or httpsjms Connection Service

1 Open the broker’s instance configuration file.

The instance configuration file is named config.properties and is located in a directory
identified by the name of the broker instance to which it belongs:

372 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Enabling HTTP/HTTPS Support

.../instances/instanceName/props/config.properties
(See Appendix A, “Platform-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

3 Set any other HTTP/HTTPS-related configuration properties as needed.

At startup, the broker looks for an application server or Web server and an HTTP or HTTPS
tunnel servlet running on its local host machine. If necessary, you can reconfigure the broker to
access a remote tunnel servlet instead, by setting the servletHost and servletPort properties
appropriately (see Table C–2): for example,
imq.httpjms.http.servletHost=helios
imq.httpjms.http.servletPort=7675
You can also improve performance by reconfiguring the connection service’s pullPeriod
property. This specifies the interval, in seconds, at which each client issues HTTP/HTTPS
requests to pull messages from the broker. With the default value of −1, the client will keep one
such request pending at all times, ready to pull messages as fast as possible. With a large number
of clients, this can cause a heavy drain on server resources, causing the server to become
unresponsive. Setting the pullPeriod property to a positive value configures the client’s
HTTP/HTTPS transport driver to wait that many seconds between pull requests, conserving
server resources at the expense of increased response times to clients.
The connectionTimeout property specifies the interval, in seconds, that the client runtime
waits for a response from the HTTP/HTTPS tunnel servlet before throwing an exception, as
well as the time the broker waits after communicating with the tunnel servlet before freeing a
connection. (A timeout is necessary in this case because the broker and the tunnel servlet have
no way of knowing if a client that is accessing the tunnel servlet has terminated abnormally.)

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.

Appendix C • HTTP/HTTPS Support 373

Enabling HTTP/HTTPS Support

Configuring the JSSE Libraries (HTTPS Only)

Beginning with Version 1.4 of the Java Development Kit, the JSSE libraries are bundled directly
with the JDK. If you are working with an earlier JDK version, you must configure these libraries
yourself. (This step is not needed for ordinary, non-secure HTTP connections, or if the JDK you
are using is Version 1.4 or higher.)

▼ To Configure the JSSE Libraries

1 Install the JSSE .jar files.

Copy the files
jsse.jar
jnet.jar
jcert.jar
to the directory

JRE_HOME/lib/ext

2 Add the JSSE security provider to the Java security file.

Add the line
security.provider.n=com.sun.net.ssl.internal.ssl.Provider
to the file

JRE_HOME/lib/security/java.security
where n is the next available priority number for a security provider package.

3 Set the client application’s java.protocol.handler.pkgs property.

In the command that launches the client application, use the -D option to specify the following
JSSE property:
java.protocol.handler.pkgs=com.sun.net.ssl.internal.www.protocol

Installing a Root Certificate (HTTPS Only)

If the root certificate of the certification authority (CA) that signed your application server’s (or
Web server’s) certificate is not in the trust store by default, or if you are using a proprietary
application server or Web server certificate, you must install the root certificate in the trust
store. (This step is not needed for ordinary, non-secure HTTP connections, or if the CA’s root
certificate is already in the trust store by default.)

374 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Enabling HTTP/HTTPS Support

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

2 Confirm that you trust the certificate.

Answer YES to the question Trust this certificate?

3 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 factory’s imqAddressList
attribute to the URL of the HTTP/HTTPS tunnel servlet. The URL has the form

http://hostName:portNumber/contextRoot/tunnel

or

https://hostName:portNumber/contextRoot/tunnel

where hostName:portNumber is the host name and port number of the application server or
Web server hosting the tunnel servlet and contextRoot is the context root directory you
specified when deploying the tunnel servlet on the server, as described above under “Step 4
(HTTP and HTTPS): Deploying the Tunnel Servlet” on page 370.

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

Appendix C • HTTP/HTTPS Support 375

Enabling HTTP/HTTPS Support

■ Use an API call to set the attributes of the connection factory after you create it
programmatically in client application code (see the Message Queue Developer’s Guide for
Java Clients).

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

EXAMPLE C–1 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

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 server’s host name and port number. You
can set these properties using the -D option to the command that launches the client
application.

376 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Troubleshooting

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 Start the tunnel servlet and the broker.

2 Use a browser to access the servlet manually through the tunnel servlet URL.

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

Appendix C • HTTP/HTTPS Support 377

378
 D
A P P E N D I X

JMX Support
D

Message Queue includes support for Java-based client programs to configure and monitor
Message Queue resources, such as message brokers, connections, and destinations,
programmatically by means of the Java Management Extensions (JMX) application
programming interface. Use of the JMX API from the client side is fully described in the
Message Queue Developer’s Guide for JMX Clients. This appendix describes the administrative
features provided to support such use.

Broker Properties for JMX Support

Broker configuration properties that support JMX are listed in Table 14–11. None of these
properties can be set from the command line with the Message Queue Command utility
(imqcmd). Instead, they can either be set at broker startup with the -D option of the Broker utility
(imqbrokerd) or edited by hand in the broker's instance configuration file
(config.properties). In addition, as described below, some of these properties can be set with
corresponding Broker utility options.

The imq.jmx.connector.list property defines a set of named JMX connectors to be created at

broker startup; imq.jmx.connector.activelist specifies which of these are to be activated.
Each named connector then has its own set of properties:

imq.jmx.connector.connectorName.urlpath
imq.jmx.connector.connectorName.useSSL
imq.jmx.connector.connectorName.brokerHostTrusted

By default, two JMX connectors are created, named jmxrmi and ssljmxrmi; the second is
configured to use Secure Socket Layer (SSL) encryption
(imq.jmx.connector.ssljmxrmi.useSSL = true), while the second is not
(imq.jmx.connector.jmxrmi.useSSL = false). By default, only the jmxrmi connector is
activated at broker startup; see“SSL Support for JMX Clients” on page 380, below, for
information on how to activate the ssljmxrmi connector for secure communications.

379
SSL Support for JMX Clients

Message Queue’s JMX connectors use remote method invocation (RMI) as the infrastructure
for communicating between client and server. The broker properties
imq.jmx.rmiregistry.start and imq.jmx.rmiregistry.use specify whether to start a local
RMI registry at broker startup or use an external registry. The imq.jmx.rmiregistry.port
property specifies the port number for the RMI registry. For convenience, these properties can
also be specified by using equivalent Broker utility (imqbrokerd) options at broker startup:
-startRmiRegistry, -useRmiRegistry, and -rmiRegistryPort, respectively (see Table 13–1).

The Command utility (imqcmd) subcommand list jmx displays a list of JMX service URLs of
JMX connectors created and started at broker startup. This information is needed by JMX
clients that do not use the Message Queue convenience class AdminConnectionFactory to
obtain their JMX connectors, and can also be used for managing or monitoring Message Queue
via a generic JMX browser such as the Java Monitoring and Management Console (jconsole).

SSL Support for JMX Clients

As mentioned above, a Message Queue message broker is configured by default for insecure
communication using the preconfigured JMX connector jmxrmi. Applications wishing to use
the Secure Socket Layer (SSL) for secure communication must activate the alternate, secure
JMX connector, ssljmxrmi, using the procedure shown below.

On the client side, the administrator connection factory (AdminConnectionFactory) must be

configured with a URL specifying ssljmxrmi as the preferred connector:

AdminConnectionFactory acf = new AdminConnectionFactory();

acf.setProperty(AdminConnectionConfiguration.imqAddress,
"mq://myhost:7676/ssljmxrmi");

If needed, use the system properties javax.net.ssl.trustStore and

javax.net.ssl.trustStorePassword to point the JMX client to the trust store.

Configuring JMX for SSL operation requires the following steps:

▼ Configuring JMX for SSL Operation

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

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

3 Add the ssljmxrmi connector to the list of JMX connectors to be activated at broker startup:
imq.jmx.connector.activelist=jmxrmi,ssljmxrmi

380 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 SSL Support for JMX Clients

4 Start the broker.

Use the Message Queue Broker utility (imqbrokerd, either passing it the key store password in a
password file or typing it from the command line when prompted.

5 Disable validation of certificates if necessary.

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.

Appendix D • JMX Support 381

382
 E
A P P E N D I X E

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 266 in “Command Utility” on page 266

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 query bkr
imqcmd pause bkr
imqcmd restart bkr
imqcmd resume bkr
imqcmd shutdown bkr -b myBroker:7676
imqcmd update bkr -o "imq.system.max_count=1000"
imqcmd reload cls

383
Service and Connection Management

Broker Configuration Properties (-o option)

“Broker Configuration Properties (-o option)” on page 384 lists frequently used broker
configuration properties. For a full list of broker configuration properties and their
descriptions, see Chapter 14, “Broker Properties Reference”

TABLE E–1 Broker Configuration Properties ( -o option)

Property Notes

imq.autocreate.queue

imq.autocreate.queue.maxNumActiveConsumers Specify −1 for unlimited

imq.autocreate.queue.maxNumBackupConsumers Specify −1 for unlimited

imq.autocreate.topic

imq.cluster.url

imq.destination.DMQ.truncateBody

imq.destination.logDeadMessages

imq.log.file.rolloverbytes Specify −1 for unlimited

imq.log.file.rolloversecs Specify −1 for unlimited

imq.log.level NONE
ERROR
WARNING
INFO

imq.message.max_size Specify −1 for unlimited

imq.portmapper.port

imq.system.max_count Specify −1 for unlimited

imq.system.max_size Specify −1 for unlimited

Service and Connection Management

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

384 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 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 list txn
imqcmd commit txn -n 1234567890
imqcmd query txn -n 1234567890
imqcmd rollback txn -n 1234567890

Destination Management
imqcmd create dst -n MyQueue -t q -o "maxNumMsgs=1000" -o "maxNumProducers=5"
imqcmd update dst -n MyTopic -t t -o "limitBehavior=FLOW_CONTROL| REMOVE_OLDEST|REJECT_NEWEST|REMOVE_LOW_PRIORITY"
imqcmd compact dst -n MyQueue -t q
imqcmd purge dst -n MyQueue -t q
imqcmd pause dst -n MyQueue -t q -pst PRODUCERS|CONSUMERS|ALL
imqcmd resume dst -n MyQueue -t q
imqcmd destroy dst -n MyQueue -t q
imqcmd query dst -n MyQueue -t q
imqcmd list dst -tmp

Destination Configuration Properties (-o option)

“Destination Configuration Properties (-o option)” on page 385 lists frequently used
destination configuration properties. For a full list of destination configuration properties and
their descriptions, see Chapter 15, “Physical Destination Property Reference”

TABLE E–2 Destination Configuration Properties (-o option)

Property Notes

consumerFlowLimit Specify −1 for unlimited

isLocalOnly (create only)

limitBehavior FLOW_CONTROL
REMOVE_OLDEST
REJECT_NEWEST
REMOVE_LOW_PRIORITY

Appendix E • Frequently Used Command Utility Commands 385

Metrics

TABLE E–2 Destination Configuration Properties (-o option) (Continued)

Property Notes

localDeliveryPreferred (queue only)

maxNumActiveConsumers (queue only) Specify −1 for unlimited

maxNumBackupConsumers (queue only) Specify −1 for unlimited

maxBytesPerMsg Specify −1 for unlimited

maxNumMsgs Specify −1 for unlimited

maxNumProducers Specify −1 for unlimited

maxTotalMsgBytes Specify −1 for unlimited

useDMQ

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

386 Sun Java System Message Queue 4.1 Administration Guide • September 2007
Index

A Administration Console
access control file starting, 40
location, 354, 355, 356 tutorial, 39
acknowledgeMode activation specification administration tasks
attribute, 332 development environment, 33-34
ActivationSpec JavaBean, 331 production environment, 34-35
addressList activation specification attribute, 331 administration tools, 36-37
addressList managed connection factory attribute, 330 Administration Console, 37
addressList Resource Adapter attribute, 328 command line utilities, 36
addressListBehavior managed connection factory administrator password, 170
attribute, 330 API documentation, 354, 355, 356
addressListBehavior Resource Adapter attribute, 328 attributes of physical destinations, 313-315
addressListIterations managed connection factory authentication
attribute, 330 See also access control
addressListIterations Resource Adapter attribute, 328 about, 85
admin connection service, 76 JAAS-based
ADMIN service type, 76 See JAAS-based authentication
admin user, 167 managing, 165-179
changing password, 170 authorization
administered objects See also access control
attributes (reference), 317 about, 85-86
deleting, 141 managing, 180-185
listing, 141-142 user groups, 85
managing, 127-145 auto-create physical destinations
object store access control, 86, 184
See object stores properties (table), 287-290
querying, 142 automatic reconnection, 132
required information, 137 limitations, 132
updating, 143 AUTOSTART property, 69
XA connection factory
See connection factory administered objects

387
Index

B brokers (Continued)
benchmarks, performance, 214-215 clusters
bottlenecks, performance, 218 See broker clusters
broker clusters commands for managing, 268-270
adding brokers to, 156 configuration files
architecture, 225 See configuration files
configuration change record, 148 displaying metrics, 270
configuration file, 150, 154, 155, 161, 302 httpjms connection service properties, 372
configuration properties, 149, 302-304 httpsjms connection service properties, 372
connecting conventional brokers, 154 instance configuration properties, 90
conventional, 147-148 instance name, 262
automatic reconnection in, 132 interconnected
high-availability (HA), 148-149 See broker clusters
automatic reconnection in, 132 limit behaviors, 78, 225
listing brokers, 105, 152-154, 269 listing, 105
master broker, 148 listing connection services, 107
pausing physical destinations in, 118 listing property values, 269
performance effect of, 225 logging
purging physical destinations in, 119 See Logger
reasons for using, 225 managing, 97-114
reloading configuration, 269 memory management, 78, 225
secure interbroker connections (SSL), 155 message capacity, 78, 103, 286
broker components message flow control
connection services, 75, 76 See message flow control
monitoring services, 75, 86-88 metrics
persistence services, 75, 80-83 See broker metrics
routing services, 75, 78 pausing, 102, 268
security services, 75, 83-86 permissions required for starting, 68
broker metrics properties (reference), 283, 313
Logger properties, 87, 203, 301 querying, 104
metric quantities (table), 336-337 quiescing, 101, 268
metrics messages, 88 recovery from failure, 80
reporting interval, Logger, 265 removing, 72-73
using broker log files, 203 restarting, 80, 101, 268
using imqcmd, 207, 208 restarting automatically, 69
using message-based monitoring, 210 resuming, 102, 269
broker monitoring service, properties, 298-302 running as Windows service, 70-72
broker responses, wait period for client, 322 setting properties, 269
brokers shutting down, 100, 268
access control startup with SSL, 189
See authorization takeover, 269
auto-create physical destination properties, 287-290 unquiescing, 102, 269
clock synchronization, 67-68 updating properties of, 103
clustering, 154 viewing information about, 104-105

388 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Index

brokers (Continued) command options, as configuration overrides, 74

viewing metric information, 105 compacting
file-based data store, 81
physical destinations, 123
config.properties file, 90, 156, 158, 372
C configuration change record, 148
certificates, 185-191 backing up, 158
self-signed, 363 restoring, 158
client applications configuration files, 89
example, 354, 355, 356 broker (figure), 89
factors affecting performance, 218-222 cluster, 150, 154, 155, 161, 302
client identifier (ClientID), 133-135 default, 89
in destroying durable subscription, 112 installation, 89
client runtime instance, 90, 149, 353, 354, 356
configuration of, 226 location, 353, 354, 356
message flow tuning, 231 template location, 353, 354, 356
clientID activation specification attribute, 332 templates, 353, 354, 356
clientID managed connection factory attribute, 330
connection factories, adding administered objects
clients
for, 139
clock synchronization, 67-68
connection factory administered objects
starting, 73-74
application server support attributes, 324
clock synchronization, 67-68
attributes, 130-137
cluster configuration file, 150, 154, 155, 161, 302
client identification attributes, 133-135
cluster configuration properties, 149, 302
connection handling attributes, 130-133
cluster connection service, 149, 155, 185
host name or IP address for, 150, 303 JMS properties support attributes, 136
network transport for, 150, 303 overriding message header fields, 136
port number for, 150, 303 queue browser behavior attributes, 136, 323-324
cluster identifier, 151, 304 reliability and flow control attributes, 135
clustering brokers, 154 standard message properties, 324
clusters, See broker clusters connection service metrics
command files, 143-145 metric quantities, 338-339
command line syntax, 261 using imqcmd metrics, 207
command line utilities using imqcmd query, 208
about, 36 connection services
basic syntax, 261 access control for, 84, 294
displaying version, 99, 168-169, 275 activated at startup, 284
help, 99, 169, 275 admin, 76
imqbrokerd, See, imqbrokerd command, 36 cluster, 149, 150, 155, 303
imqcmd, See, imqcmd command, 36 See cluster connection service
imqdbmgr See, imqdbmgr command, 36 commands for managing, 270-271
imqkeytool, See, imqkeytool command, 36 displaying metrics, 271
imqobjmgr, See, imqobjmgr command, 36 HTTP
imqsvcadmin, See, imqsvcadmin command, 36 See HTTP connections
imqusermgr, See, imqusermgr command, 36 httpjms, 76

389
Index

connection services (Continued) D

HTTPS data store
See HTTPS connections about, 80
httpsjms, 76 compacting, 81
See httpsjms connection service configuring, 92
jms, 76 contents of, 92
listing, 107 flat-file, 81-82
listing available, 270 JDBC-compliant, 82-83
listing property values, 270 location, 353, 355, 356
pausing, 106, 270 performance effect of, 226
Port Mapper resetting, 263
See Port Mapper synchronizing to disk, 92
properties, 284-286 dead message queue, 124-126, 349
protocol type, 76 configuring use of, 124
querying, 108 logging, 87, 125-126
resuming, 106, 270 managing, 124-125
service type, 76 truncating message bodies, 125
SSL-based, 187 variant treatment of physical destination
ssladmin, 76 properties, 125
See ssladmin connection service dead messages
ssljms, 76 See also dead message queue
See ssljms connection service logging, 87
thread allocation, 107 default.properties file, 89
thread pool management, 77 deleting, broker instance, 72-73
updating, 107, 270 delivery modes, performance effect of, 219
viewing information about, 107-109 destination activation specification attribute, 331
viewing metric information, 108 destination administered objects, attributes, 137
connection services, broker, 75, 76 destination metrics
connections metric quantities, 339-343
automatic reconnection using imqcmd metrics, 205, 207-208
See automatic reconnection using imqcmd query, 208
commands for managing, 271 using message-based monitoring, 210
destroying, 111, 271 destinations, adding administered objects for, 139-141
failover destinationType activation specification attribute, 331,
See automatic reconnection 332
limited by file descriptor limits, 68 destroying
listing, 109, 271 connections, 111, 271
performance effect of, 223-225 durable subscriptions, 273
querying, 110, 113, 271 physical destinations, 117, 272
connectionURL Resource Adapter attribute, 328 development environment administration tasks, 33-34
consumerFlowLimit destination property, 315, 349 directory lookup for clusters (Linux), 154
consumerFlowLimit property, 135 directory variables
customAcknowledgeMode activation specification IMQ_HOME, 25
attribute, 332 IMQ_JAVAHOME, 26

390 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Index

directory variables (Continued) H

IMQ_VARHOME, 26 hardware, performance effect of, 223
disk utilization by physical destinations, 123-124 help (command line), 99, 169, 275
displaying product version, 99, 168-169, 275 hosts file (Linux), 154
distributed transactions, XA resource manager, 112 HTTP
durable subscriptions connection service
commands for managing, 273 See httpjms connection service
destroying, 112, 273 proxy, 361
support architecture, 361-362
listing, 111, 273
transport driver, 361
managing, 111
HTTP connections
performance effect of, 221
request interval, 372
purging messages for, 273 support for, 361
tunnel servlet
See HTTP tunnel servlet
HTTP protocol type, 76
E HTTP tunnel servlet
encryption about, 361
about, 83, 86 deploying, 370-372
Key Tool and, 86 httpjms connection service, 76
SSL-based services, 185-193 configuring broker for, 372-373
endpointExceptionRedeliveryAttempts activation HTTPS
specification attribute, 332, 333 connection service
environment variables, See directory variables See httpsjms connection service
/etc/hosts file (Linux), 154 support architecture, 361-362
example applications, 354, 355, 356 HTTPS connections
multiple brokers, for, 376
request interval, 372
support for, 361
F tunnel servlet
file-based persistence, 81-82 See HTTPS tunnel servlet
file descriptor limits, 68 HTTPS protocol type, 76
connection limits and, 68 HTTPS tunnel servlet
file synchronization about, 361
deploying, 370-372
imq.persist.file.sync.enabled option, 292
httpsjms connection service, 76, 185
with Sun Cluster, 292
configuring broker for, 372-373
firewalls, 361 setting up, 362-376
flow control, See message flow control
fragmentation of messages, 81

I
imq.accesscontrol.enabled property, 84, 294
G imq.accesscontrol.file.filename property, 84, 295
guest user, 167 imq.admin.tcp.port property, 195

391
Index

imq.authentication.basic.user_repository property, 85, imq.cluster.monitor.threshold property, 152, 304

294 imq.cluster.port property, 150, 303
imq.authentication.client.response.timeout imq.cluster.transport property, 150, 156, 303
property, 85, 294 imq.cluster.url property, 103, 150, 155, 156, 158, 302
imq.authentication.type property, 85, 294 imq.destination.DMQ.truncateBody property, 79, 103,
imq.autocreate.destination.isLocalOnly property, 290 125, 287
imq.autocreate.destination.limitBehavior imq.destination.logDeadMsgs property, 87, 103, 298
property, 288 IMQ_HOME directory variable, 25
imq.autocreate.destination.maxBytesPerMsg imq.hostname property, 77, 284
property, 288 imq.httpjms.http.connectionTimeout property, 372
imq.autocreate.destination.maxCount property, 288 imq.httpjms.http.pullPeriod property, 372
imq.autocreate.destination.maxNumMsgs imq.httpjms.http.servletHost property, 372
property, 288 imq.httpjms.http.servletPort property, 372
imq.autocreate.destination.maxNumProducers imq.httpsjms.https.connectionTimeout property, 372
property, 289 imq.httpsjms.https.pullPeriod property, 372
imq.autocreate.destination.maxTotalMsgBytes imq.httpsjms.https.servletHost property, 372
property, 288, 290 imq.httpsjms.https.servletPort property, 372
imq.autocreate.destination.useDMQ property, 124 imq.imqcmd.password property, 85, 195, 296
imq.autocreate.queue.consumerFlowLimit IMQ_JAVAHOME directory variable, 26
property, 289 imq.jms.tcp.port property, 195
imq.autocreate.queue.localDeliveryPreferred imq.jmx.connector.activelist property, 305
property, 290 imq.jmx.connector.connectorName.brokerHostTrusted
imq.autocreate.queue.maxNumActiveConsumers property, 306
property, 103, 289 imq.jmx.connector.connectorName.urlpath
imq.autocreate.queue.maxNumBackupConsumers property, 305
property, 103, 289 imq.jmx.connector.connectorName.useSSL
imq.autocreate.queue property, 103, 287 property, 306
imq.autocreate.topic property, 103, 287 imq.jmx.connector.list property, 305
imq.broker.adminDefinedRoles.count property, 302, imq.jmx.rmiregistry.port property, 307
308 imq.jmx.rmiregistry.start property, 306
imq.broker.adminDefinedRoles.namen property, 302, imq.jmx.rmiregistry.use property, 306
308, 347 imq.keystore.file.dirpath property, 187, 295
imq.brokerid property, 83, 284 imq.keystore.file.name property, 187, 295
imq.cluster.brokerlist property, 154, 155, 156, 157, 303 imq.keystore.password property, 86, 195, 295
imq.cluster.clusterid property, 151, 304 imq.log.console.output property, 87, 299
imq.cluster.ha, 302 imq.log.console.stream property, 87, 299
imq.cluster.ha property, 150 imq.log.file.dirpath property, 87, 299
imq.cluster.heartbeat.hostname property, 152, 304 imq.log.file.filename property, 87, 299
imq.cluster.heartbeat.interval property, 152, 304 imq.log.file.output property, 87, 299
imq.cluster.heartbeat.port property, 152, 304 imq.log.file.rolloverbytes property, 87, 103, 299
imq.cluster.heartbeat.threshold property, 152, 304 imq.log.file.rolloversecs property, 87, 103, 300
imq.cluster.hostname property, 150, 303 imq.log.level property, 87, 103, 298
imq.cluster.masterbroker property, 150, 156, 158, 303 imq.log.syslog.facility property, 300
imq.cluster.monitor.interval property, 152, 304 imq.log.syslog.identity property, 300

392 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Index

imq.log.syslog.logconsole property, 301 imq.persist.jdbc.vendorName.user property, 83

imq.log.syslog.logpid property, 300 imq.persist.jdbc.vendorNameuser property, 293
imq.log.syslog.output property, 87, 300 imq.persist.store property, 80, 93, 290
imq.log.timezone property, 301 imq.ping.interval property, 78, 286
imq.message.expiration.interval property, 78, 287 imq.portmapper.backlog property, 77, 285
imq.message.max_size property, 78, 103, 287 imq.portmapper.hostname property, 77, 284
imq.metrics.enabled property, 87, 301 imq.portmapper.port property, 77, 103, 284
imq.metrics.interval property, 87, 301 imq.primaryowner.contact property, 302, 310, 347
imq.metrics.topic.enabled property, 88, 301 imq.primaryowner.name property, 302, 311, 346
imq.metrics.topic.interval property, 88, 301 imq.protocol.protocolType.inbufsz, 227
imq.metrics.topic.persist property, 88, 301 imq.protocol.protocolType.nodelay, 227
imq.metrics.topic.timetolive property, 88, 302 imq.protocol.protocolType.outbufsz, 227
imq.passfile.dirpath property, 85, 296 imq.resource_state.count property, 287
imq.passfile.enabled property, 85, 295 imq.resource_state.threshold property, 287
imq.passfile.name property, 85, 296 imq.resourceState.count property, 79
imq.persist.file.destination.message.filepool.limit imq.service.activelist property, 76, 284
property, 82, 291 imq.service_name.accesscontrol.file.filename
imq.persist.file.message.cleanup property, 82, 292 property, 295
imq.persist.file.message.filepool.cleanratio imq.service_name.authentication.type property, 294
property, 82, 291 imq.service_name.max_threads property, 285, 348
imq.persist.file.message.max_record_size imq.service_name.min_threads property, 285, 348
property, 291 imq.service_name.protocol_type.hostname
imq.persist.file.message.vrfile.max_record_size property, 284
property, 82 imq.service_name.protocol_type.port property, 285
imq.persist.file.sync.enabled property, 82, 292 imq.service_name.threadpool_model property, 285
imq.persist.file.sync property, 92 imq.serviceName.accesscontrol.enabled property, 84,
imq.persist.file.transaction.memorymappedfile.enabled 295
property, 220, 292 imq.serviceName.accesscontrol.file.filename
imq.persist.jdbc.dbVendor property, 83, 292 property, 84
imq.persist.jdbc.password property, 195 imq.serviceName.authentication.type property, 85
imq.persist.jdbc.vendorName.closedburl property, 83, imq.serviceName.max_threads property, 78
293 imq.serviceName.min_threads property, 78
imq.persist.jdbc.vendorName.createdburl property, 83, imq.serviceName.protocolType.hostname property, 77
293 imq.serviceName.protocolType.port property, 77
imq.persist.jdbc.vendorName.driver property, 83, 292 imq.serviceName.threadpool_model property, 78
imq.persist.jdbc.vendorName.needpassword imq.shared.connectionMonitor_limit property, 78,
property, 83, 293 286
imq.persist.jdbc.vendorName.opendburl property, 83, imq.ssladmin.tls.port property, 195
293 imq.ssljms.tls.port property, 195
imq.persist.jdbc.vendorName.password property, 83, imq.system.max_count property, 78, 103, 286
293 imq.system.max_size property, 78, 103, 286
imq.persist.jdbc.vendorName.property.propName, 83 imq.transaction.autorollback property, 287
imq.persist.jdbc.vendorName.property.propName imq.user_repository.ldap.base property, 297
property, 293 imq.user_repository.ldap.gidattr property, 297

393
Index

imq.user_repository.ldap.grpbase property, 297 imqcmd command (Continued)

imq.user_repository.ldap.grpfilter property, 297 physical destination subcommands (table), 116
imq.user_repository.ldap.grpsearch property, 297 reference, 266
imq.user_repository.ldap.memattr property, 297 secure connection to broker, 190-191, 274
imq.user_repository.ldap.password property, 85, 195, transaction management, 112
297 usage help, 99
imq.user_repository.ldap.principal property, 85, 297 imqConfiguredClientID attribute, 134, 321
imq.user_repository.ldap.property_name imqConnectionFlowCount attribute, 135, 322
property, 297 imqConnectionFlowLimit attribute, 135, 322
imq.user_repository.ldap.server property, 85, 296 imqConnectionFlowLimitEnabled attribute, 135, 322
imq.user_repository.ldap.ssl.enabled property, 298 imqConsumerFlowLimit attribute, 135, 323
imq.user_repository.ldap.timeout property, 298 imqConsumerFlowThreshold attribute, 135, 323
imq.user_repository.ldap.uidattr property, 297 imqdbmgr command
imq.user_repository.ldap.usrfilter property, 297 about, 36
IMQ_VARHOME directory variable, 26 in password file, 194
imqAckTimeout attribute, 135, 322
options, 278
imqAddressList attribute, 131, 132, 318
reference, 277
dynamically updated in high-availability
imqDefaultPassword attribute, 133, 134, 321
clusters, 132, 133, 318
imqDefaultUsername attribute, 133, 134, 321
imqAddressListBehavior attribute, 131, 132, 318
imqDestinationDescription attribute, 137, 325
imqAddressListIterations attribute, 131, 132, 318
imqDestinationName attribute, 137, 325
imqbrokerd command, 68
imqDisableSetClientID attribute, 321
about, 36
imqFlowControlLimit attribute, 323
backing up configuration change record, 158
clearing the data store, 92 imqJMSDeliveryMode attribute, 325
configuration file (Solaris, Linux), 69, 73 imqJMSExpiration attribute, 325
connecting brokers, 155 imqJMSPriority attribute, 137, 325
in password file, 194 imqkeytool command
options, 262-266 about, 36
passing arguments to, 91 command syntax, 186
reference, 262 reference, 281
removing a broker, 72-73 using, 186
removing a broker from a cluster, 157 imqLoadMaxToServerSession attribute, 136, 324
restoring configuration change record, 158 imqobjmgr command
setting logging properties, 201 about, 36
imqbrokerd.conf file, 73 options, 275
imqcmd command reference, 275
about, 36 subcommands, 275
dependent on master broker, 148 imqOverrideJMSDeliveryMode attribute, 325
displaying version, 99 imqOverrideJMSExpiration attribute, 325
general options, 274 imqOverrideJMSHeadersToTemporaryDestinations
in password file, 194 attribute, 137, 325
metrics monitoring, 204-209 imqOverrideJMSPriority attribute, 137, 325
physical destination management, 116 imqPingInterval attribute, 133

394 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Index

imqQueueBrowserMax MessagesPerRetrieve JAAS-based authentication (Continued)

attribute, 136, 323 JMX clients and, 175
imqQueueBrowserRetrieveTimeout attribute, 136, 323 login module, 175
imqReconnectAttempts attribute, 132, 319 setting up, 177-179
imqReconnectEnabled attribute, 132, 319 Java Management Extensions (JMX), administrative
imqReconnectInterval attribute, 132, 319 support for, 379-381
imqSetJMSXAppID attribute, 324 Java Management Extensions (JMX), commands for
imqSetJMSXConsumerTXID attribute, 324 managing, 274
imqSetJMSXProducerTXID attribute, 324 java.naming.factory.initial attribute, 128, 129
imqSetJMSXRcvTimestamp attribute, 324 java.naming.provider.url attribute, 128, 129
imqSetJMSXUserID attribute, 324 java.naming.security.authentication attribute, 129
imqSSLIsHostTrusted attribute, 319 java.naming.security.credentials attribute, 128
imqsvcadmin command java.naming.security.principal attribute, 128
about, 36 Java runtime
options, 280 for Windows service, 71-72
reference, 280 specifying path to, 264, 275, 276, 280
subcommands, 280 Java Virtual Machine, See JVM
imqusermgr command, 167-172 javahome option, 71
about, 36 JCA (J2EE connector architecture), 327
displaying version, 168-169 JDBC-based persistence
general options, 279-280 about, 82-83
general options (table), 168 setting up, 92-94
options, 279
tuning for performance, 229
passwords, 169
JDBC support
reference, 278
about, 82-83
subcommands, 279
configuring, 92
subcommands (table), 168
JDBC support, driver, 292
usage help, 169
JES Monitoring Framework (JESMF), 209-210,
user names, 169
345-350
install.properties file, 89
instance configuration files, See configuration files brokers, 346-347
instance directory common attributes, 345-346
and file-based data store, 92 connection services, 347-348
removing, 73 destinations, 349
isLocalOnly destination property, 315, 349 Message Queue product, 346
persistent data store, 350
Port Mapper, 347
user repository, 350
J JESMF, See JES Monitoring Framework
J2EE connector architecture (JCA), 327 jms connection service, 76
JAAS-based authentication, 174-179 JMSDeliveryMode message header field, 136
configuration file, 175 JMSExpiration message header field, 136
configuration file for, 176 JMSPriority message header field, 136
JAAS API, 174 JMSXAppID message property, 136
JAAS client, 175 JMSXConsumerTXID message property, 136

395
Index

JMSXProducerTXID message property, 136 load-balanced queue delivery, tuning for

JMSXRcvTimestamp message property, 136 performance, 230-231
JMSXUserID message property, 136 localDeliveryPreferred destination property, 315, 349
JMX, See Java Management Extensions log files
JMX connectors, listing, 274 changing default location, 200
JNDI changing default name, 200
lookup, 53 dead message logging, 203-204
lookup name, 137, 138 default location, 354, 355, 356
object store, 36, 127 names, 200
object store attributes, 128-129, 138 reporting metrics, 203
jrehome option, 71 rollover criteria, 87, 202, 299
JVM rollover frequency, 201
metrics setting properties, 201
See JVM metrics Logger
performance effect of, 223 about, 87-88
tuning for performance, 226-227 changing configuration, 201
JVM metrics dead message format, 204
metric quantities, 335-336 levels, 87, 199, 265, 298
using broker log files, 203 message format, 199
using imqcmd metrics, 206 metrics information, 301
using message-based monitoring, 210 output channels, 87, 199, 201-202
redirecting log messages, 202
rollover criteria, 202
setting properties, 201
K writing to console, 87, 266, 299
key pairs logging, See Logger
generating, 187, 364 loopback address, 154
regenerating, 188
key store, 187, 364
file, 187
Key Tool, 86 M
keytool command ManagedConnectionFactory JavaBean, 330
command syntax, 363 master broker
using, 363 configuration change record, 148
defined, 148
management, 158
specifying, 150
L unavailable, 148
LDAP server maxBytesPerMsg destination property, 313, 349
as user repository, 172-174 maxNumActiveConsumers destination property, 314,
object store attributes, 128 349
limit behaviors maxNumBackupConsumers destination
broker, 78 property, 314, 349
physical destinations, 314 maxNumMsgs destination property, 313, 349
limitBehavior destination property, 314, 349 maxNumProducers destination property, 314, 349

396 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Index

maxTotalMsgBytes destination property, 314, 349 metrics (Continued)

MDBs, See message-driven beans topic destinations, 88, 210
memory management metrics data
for broker, 78 broker
tuning for performance, 229-230 See broker metrics
message-driven beans physical destination
Resource Adapter configuration for, 327, 331 See physical destination metrics
message expiration, clock synchronization and, 67 using broker log files, 203
message flow control using imqcmd metrics, 206
attributes, 135 using message-based monitoring API, 210-211
broker, 78 metrics messages
limits, 231-233 about, 210
metering, 231 type, 88, 210
performance effect of, 231 metrics monitoring tools
tuning for performance, 231 compared, 197-199
message header overrides, 136-137 message-based monitoring API, 210-212
message service architecture, 225 Message Queue Command Utility
message service performance, 222-226 (imqcmd), 204-209
messages Message Queue log files, 203
body type and performance, 222 monitoring, See performance monitoring
broker limits on, 78, 103, 286 monitoring services, broker, 75, 86-88
destination limits on, 288, 314
flow control
See message flow control
fragmentation, 81 N
metrics messages NORMAL service type, 76
See metrics messages nsswitch.conf file (Linux), 154
pausing flow of, 117
persistence of, 80
purging from a physical destination, 272
reclamation of expired, 78, 287 O
reliable delivery of, 135 object stores, 127-130
size, and performance, 222 file-system, 129-130
messageSelector activation specification attribute, 331 file-system store attributes, 129-130
metric information initial context, 128
brokers, 105 LDAP server, 127-129
connection services, 108 LDAP server attributes, 128
physical destinations, 121 location, 128
metrics locations, 354, 355, 356
about, 87 security, 128
data operating system
See metrics data performance effect of, 223
messages tuning Solaris performance, 226
See metrics messages Oracle, 93, 95

397
Index

overrides performance (Continued)

for message header, 136-137 tuning
on command line, 74 See performance tuning
performance factors
acknowledgment mode, 220
broker limit behaviors, 225
P connections, 223-225
password file data store, 226
broker configuration properties, 85, 296 delivery mode, 219
command line option, 264 durable subscriptions, 221
location, 195, 354, 355, 356 file synchronization, 292
permissions, 194 hardware, 223
using, 193-195
JVM, 223
password managed connection factory attribute, 330
message body type, 222
password Resource Adapter attribute, 328
message flow control, 231
passwords
message service architecture, 225
administrator, 170, 195
message size, 222
default, 321
operating system, 223
encoding of, 294
selectors, 221
format, 169
transactions, 219-220
JDBC, 195
transport protocols, 224-225
LDAP, 195
performance monitoring
password file
See password file JES Monitoring Framework (JESMF)
SSL key store, 187, 195 See JES Monitoring Framework
pausing metrics data
brokers, 102, 268 See metrics data
connection services, 106, 270 tools
physical destinations, 117, 272 See metrics monitoring tools
performance performance tuning
about, 213-216 broker adjustments, 229-231
baseline patterns, 215-216 client runtime adjustments, 231-233
benchmarks, 214-215 process overview, 213-214
bottlenecks, 218 system adjustments, 226-229
factors affecting permissions
See performance factors access control file, 86
indicators, 214 admin service, 85
measures of, 214 computing, 182-183
monitoring data store, 81
See performance monitoring embedded database, 94
optimizing password file, 194
See performance tuning user repository, 168, 278
reliability tradeoffs, 218 persistence
troubleshooting, 235 about, 80

398 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Index

persistence (Continued) Port Mapper

data store about, 76
See data store port assignment for, 262
file-based, 81-82 precedence (of configuration properties), 89
JDBC producers
See JDBC persistence destination limits on, 289, 314
JDBC-based production environment
See JDBC-based persistence administration tasks, 34-35
options (figure), 80 maintaining, 35
setting up, 34-35
properties, 291-292
properties
security for, 94
auto-create, 287-290
persistence services, broker, 75, 80-83
broker instance configuration, 90
physical destinations broker monitoring service, 298-302
auto-created, 184 cluster configuration, 302-304
batching messages for delivery, 289, 315 connection services, 284-286
commands for managing, 271-273 httpjms connection service, 372
compacting, 123 httpsjms connection service, 372
compacting file-based data store, 272 JDBC-related, 90, 292-293
creating, 116, 272 Logger, 298-302
destroying, 117, 272 persistence, 291-292
disk utilization, 123-124 physical destinations
displaying metrics, 273 See physical destinations, properties of
getting information about, 273 routine services, 286-287
limit behaviors, 314 security, 294-296, 296-298
listing, 120, 273 syntax, 91
managing, 115-126 protocol types
metrics HTTP, 76
See physical destination metrics HTTPS, 76
pausing, 117, 272 TCP, 76
properties of, 313-315 TLS, 76
purging, 119 protocols, See transport protocols
purging messages from, 272 purging physical destinations, 119
querying, 120
restricted scope in cluster, 290, 315
resuming, 118, 272 Q
temporary, 120 querying
types, 271 broker clusters, 152-154
updating attributes, 272 brokers, 104
updating properties, 119-120 connection services, 108
using dead message queue, 124 physical destinations, 120
viewing information about, 120-122 queue load-balanced delivery
viewing metric information, 121 properties, 289, 314
PointBase, 93 queues, auto-created, 287

399
Index

quiescing brokers, 101, 268 security manager

about, 83
properties, 294-296, 296-298
security services, broker, 75, 83-86
R selectors
reconnectAttempts managed connection factory about, 221
attribute, 330 performance effect of, 221
reconnectAttempts Resource Adapter attribute, 329 self-signed certificates, 185-191, 363
reconnectEnabled managed connection factory sendUndeliverableMsgsToDMQ activation
attribute, 330 specification attribute, 333
reconnectEnabled Resource Adapter attribute, 328 service (Windows)
reconnectInterval managed connection factory Java runtime for, 71-72
attribute, 331 reconfiguring, 70
reconnectInterval Resource Adapter attribute, 329 removing broker, 73
reconnection, automatic, See automatic reconnection running broker as, 70-72
reliable delivery, 135 startup parameters for, 72
performance tradeoffs, 218 troubleshooting startup, 72
removing, brokers, 72-73 service types
Resource Adapter, 327 ADMIN, 76
reconnection, 328, 329, 330 NORMAL, 76
ResourceAdapter JavaBean, 327 shutting down brokers, 100, 268
RESTART property, 69 as Windows service, 73
restarting brokers, 101, 268 Simple Network Time Protocol (SNTP), 67
resuming SSL
brokers, 102, 269 about, 86
connection services, 106, 270 SSL
physical destinations, 118, 272 broker clusters, 155
routine services, properties, 286-287 SSL
routing services, broker, 75, 78 connection services
See SSL-based connection services
SSL, enabling, 188
SSL
S encryption and, 185-193
Secure Socket Layer standard, See SSL SSL-based connection services
security setting up, 185-193
authentication starting up, 189
See authentication ssladmin connection service, 76, 185
authorization ssljms connection service, 76, 185
See authorization starting
encryption clients, 73-74
See encryption SSL-based connection services, 189
manager startup parameters for broker Windows service, 72
See security manager subscriptionDurability activation specification
object store, for, 128 attribute, 331, 332

400 Sun Java System Message Queue 4.1 Administration Guide • September 2007
 Index

subscriptionName activation specification U

attribute, 331, 332 ulimit command, 68
Sun Cluster, configuration for, 292 unquiescing brokers, 102, 269
synchronizing updating
clocks, 67-68 brokers, 103
memory to disk, 92 connection services, 107, 270
syntax for all commands, 261-262 usage help, 99, 169, 275
syslog, 87, 202 useDMQ destination property, 315, 349
system clock synchronization, 67-68 useDMQ property, 124
user groups
default, 85
deleting assignment, 166
T predefined, 166
TCP protocol type, 76 user names, 321
temporary physical destinations, 120 default, 167
thread pool management format, 169
about, 77 user repository
dedicated threads, 77 about, 84
shared threads, 77 activating and deactivating users, 170-171
time synchronization service, 67 changing passwords, 170
time-to-live, See message expiration deleting users, 170
TLS protocol type, 76 flat-file, 166-172
tools, administration, See administration tools initial entries, 167
topics, auto-created, 287 LDAP, 172-174
transactions location, 354, 355, 356
commands for managing, 273-274 platform dependence, 278
committing, 274 populating, 169
displaying information about, 274 user groups, 166-167
listing, 274 userName managed connection factory attribute, 330
managing, 112-114 userName Resource Adapter attribute, 328
performance effect of, 219-220
rolling back, 113, 274
transport protocols
performance effect of, 224-225 V
protocol types version, displaying, 99, 168-169, 275
See protocol types
relative speeds, 224
tuning for performance, 227-229
troubleshooting, 235 W
Windows service startup, 72 W32Time service, 68
tunnel servlet connection, 377 Windows service, See service (Windows)
tutorial, 39 write operations (for file based store), 92

401
Index

X
xntpd daemon, 67

402 Sun Java System Message Queue 4.1 Administration Guide • September 2007