Sun GlassFish Message Queue 4.4 Administration Guide

Chapter 17 Broker Properties Reference

This chapter provides reference information about configuration properties for a message broker. It consists of the following sections:

Connection Properties

Table 17–1 lists the broker properties related to connection services.

Table 17–1 Broker Connection Properties

Property 

Type 

Default Value 

Description 

imq.brokerid

String 

None 

Broker identifier 

For brokers using a shared JDBC-based data store, this string is appended to the names of all database tables to identify each table with a particular broker. 

Must be a unique alphanumeric string of no more than n - 13 characters, where n is the maximum table name length allowed by the database.

This property is unnecessary for an embedded database or a standalone database which stores data for only one broker instance.  


Note –

For enhanced broker clusters (imq.cluster.ha = true), database table names also use the imq.cluster.clusterid property (see Table 17–12).


imq.service.activelist [Must have the same value for all brokers in an enhanced cluster. ]

String 

jms,admin

List of connection services to be activated at broker startup, separated by commas

See Table 6–1 under Configuring Connection Services for the names of the available connection services.

imq.hostname

String 

All available IP addresses

Default host name or IP address for all connection 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.port [Can be used with imqcmd update bkr command]

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.hostname [jms, ssljms, admin, and ssladmin services only; see Appendix C, HTTP/HTTPS Support for information on configuring the httpjms and httpsjms services]

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.

imq.serviceName.protocolType.port

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_model [jms and admin services only]

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: 10ssljms: 10httpjms: 10 httpsjms: 10 admin: 4ssladmin: 4

Minimum number of threads maintained in connection service’s thread pool 

When the number of available threads exceeds this threshold, threads will be shut down as they become free until the minimum is reached.  

The default value varies by connection service, as shown.  

imq.serviceName.max_threads

Integer 

jms: 1000ssljms: 500httpjms: 500httpsjms : 500admin: 10ssladmin: 10

Number of threads beyond which no new threads are added to the thread pool for use by the named connection service 

Must be greater than 0 and greater than the value of imq.serviceName.min_threads.

The default value varies by connection service, as shown.  

imq.shared.connectionMonitor_limit [Shared threading model only]

Integer 

Solaris: 512Linux: 512Windows: 64

Maximum number of connections monitored by a distributor thread 

The system allocates enough distributor threads to monitor all connections. The smaller the value of this property, the faster threads can be assigned to active connections. A value of -1 denotes an unlimited number of connections per thread.

The default value varies by operating-system platform, as shown.  

imq.ping.interval

Integer 

120

Interval, in seconds, at which to test connection between client and broker 

A value of 0 or -1 disables periodic testing of the connection.

Routing and Delivery Properties

Table 17–2 lists the broker properties related to routing and delivery services. Properties that configure the automatic creation of destinations are listed in Table 17–3.

Table 17–2 Broker Routing and Delivery Properties

Property 

Type 

Default Value 

Description 

imq.system.max_count [Can be used with imqcmd update bkr command]

Integer 

-1

Maximum number of messages held by broker 

A value of -1 denotes an unlimited message count.

imq.system.max_size

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.

     

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_size

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: 0yellow: 80orange: 90red: 98

Percent utilization at which memory resource state is triggered (where resourceState is green, yellow, orange, or red)

imq.resourceState.count

Integer 

green: 5000yellow: 500orange: 50red: 0

Maximum number of incoming messages allowed in a batch before checking whether memory resource state threshold has been reached (where resourceState is green, yellow, orange , or red)

This limit throttles back message producers as system memory becomes increasingly scarce.  

imq.destination.DMQ.truncateBody

Boolean 

false

Remove message body before storing in dead message queue?  

If true, only the message header and property data will be saved.

imq.transaction.autorollback

Boolean 

false

Automatically roll back distributed transactions left in prepared state at broker startup?  

If false, transactions must be manually committed or rolled back using the Command utility (imqcmd).

imq.transaction.producer.maxNumMsgs

Integer 

1000

The maximum number of messages that a producer can process in a single transaction. It is recommended that the value be less than 5000 to prevent the exhausting of resources. 

imq.transaction.consumer.maxNumMsgs

Integer 

100

The maximum number of messages that a consumer can process in a single transaction. It is recommended that the value be less than 1000 to prevent the exhausting of resources. 

Table 17–3 Broker Properties for Auto-Created Destinations

Property 

Type 

Default Value 

Description 

imq.autocreate.queue [Can be used with imqcmd update bkr command] , [Queue destinations only]

Boolean 

true

Allow auto-creation of queue destinations?  

imq.autocreate.topic [Topic destinations only]

Boolean 

true

Allow auto-creation of topic destinations? 

imq.autocreate.reaptime

Integer 

120 seconds 

The delay, in seconds. before which auto-created destinations are removed from the system when they no longer have consumers nor contain messages, . A smaller value means that memory reclamation takes place more often. 

imq.autocreate.destination.maxNumMsgs

Integer 

100000

Maximum number of unconsumed messages 

A value of -1 denotes an unlimited number of messages.


Note –

When flow control is in effect (imq.autocreate.destination.limitBehavior = FLOW_CONTROL), it is possible for the specified message limit to be exceeded because the broker cannot react quickly enough to stop the flow of incoming messages. In such cases, the value specified for imq.autocreate.destination.maxNumMsgs serves as merely a hint for the broker rather than a strictly enforced limit. However, if the number of unconsumed messages would exceed imq.system.max_count, the broker generates a ResourceAllocationException indicating that the destination is full and rejecting new messages.


imq.autocreate.destination.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


When FLOW_CONTROL is specified, it is still possible for the number of messages to exceed imq.system.max_count. In this situation, the broker generates a ResourceAllocationException indicating that the destination is full and rejecting new messages.

     

If the value is REMOVE_OLDEST or REMOVE_LOW_PRIORITY and the imq.autocreate.destination.useDMQ property is true, excess messages are moved to the dead message queue.

imq.autocreate.destination.maxNumProducers

Integer 

100

Maximum number of message producers for destination

When this limit is reached, no new producers can be created. A value of -1 denotes an unlimited number of producers.

imq.autocreate.queue.maxNumActiveConsumers

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

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

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

Integer 

1000

Maximum number of messages delivered to topic consumer in a single batch

A value of -1 denotes an unlimited number of consumers.

imq.autocreate.destination.isLocalOnly

Boolean 

false

Local delivery only?  

This property applies only to destinations in broker clusters, and cannot be changed once the destination has been created. If true, the destination is not replicated on other brokers and is limited to delivering messages only to local consumers (those connected to the broker on which the destination is created).

imq.autocreate.queue.localDeliveryPreferred

Boolean 

false

Local delivery preferred?  

This property applies only to load-balanced queue delivery in broker clusters. If true, messages will be delivered to remote consumers only if there are no consumers on the local broker; the destination must not be restricted to local-only delivery (imq.autocreate.destination.isLocalOnly must be false).

imq.autocreate.destination.useDMQ

Boolean 

true

Send dead messages to dead message queue?  

If false, dead messages will simply be discarded.

validateXMLSchemaEnabled

Boolean 

false

XML schema validation is enabled? 

If set to false or not set, then XML schema validation is not enabled for the destination.

XMLSchemaURIList

String 

null 

Space separated list of XML schema document (XSD) URI strings  

The URIs point to the location of one or more XSDs to use for XML schema validation, if enabled.  

Use double quotes around this value if multiple URIs are specified. 

Example: 

http://foo/flap.xsd http://test.com/test.xsd

If this property is not set or null and XML validation is enabled, XML validation is performed using a DTD specified in the XML document. 

reloadXMLSchemaOnFailure

Boolean 

false

Reload XML schema on failure enabled? 

If set to false or not set, then the schema is not reloaded if validation fails. 

Persistence Properties

Message Queue supports both file-based and JDBC-based persistence modules. The broker property imq.persist.store (Table 17–4) specifies which module to use. The following sections describe the broker configuration properties for the two modules.

Table 17–4 Global Broker Persistence Property

Property 

Type 

Default Value 

Description 

imq.persist.store

String 

file

Module used for persistent data storage:  

    file: File-based persistence


    jdbc: JDBC-based persistence


Must be set to jdbc for enhanced broker clusters (imq.cluster.ha = true).

File-Based Persistence Properties

Table 17–5 lists the broker properties related to file-based persistence.

Table 17–5 Broker Properties for File-Based Persistence

Property 

Type 

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

imq.persist.file.message.cleanup

Boolean 

false

Clean up files in free file pools on shutdown?  

Setting this property to true saves disk space for the file store, but slows broker shutdown.

imq.persist.file.sync.enabled

Boolean 

false

Synchronize in-memory state with physical storage device? 

Setting this property to true eliminates data loss due to system crashes, but at a cost in performance.


Note –

If running Sun Cluster and the Sun Cluster Data Service for Message Queue, set this property to true for brokers on all cluster nodes.


imq.persist.file.transaction.memorymappedfile.enabled

Boolean 

true

Use memory-mapped file to store transaction data?  

Setting this property to true improves performance at the cost of increased memory usage. Set to false for file systems that do not support memory-mapped files.

File-Based Persistence Properties for Transaction Logging

Table 17–6 lists the file-based persistence properties for the transaction logging mechanism introduced in Message Queue 4.4 Update 1.

Table 17–6 Broker Properties for File-Based Persistence Using the Transaction Logging Mechanism

Property 

Type 

Default Value 

Description 

imq.persist.file.newTxnLog.enabled

Boolean 

false

Enables the transaction logging mechanism introduced in Message Queue 4.4 Update 1. For information about this mechanism, see Optimizing File-Based Transaction Persistence.

imq.persist.file.txnLog.groupCommit

Boolean 

false

This property is applicable only if imq.persist.file.newTxnLog.enabled is true.

Can improve performance if imq.persist.file.sync.enabled is true and the number of concurrent transactions being processed is high:

  • If true, write operations to the transaction log are not handled by individual connection threads; instead, writes from connection threads are added to a transaction queue. The connection threads then wait until they are notified that the transactions have been logged. A separate thread periodically drains the transaction queue and writes it to the transaction log. When possible, this thread groups together multiple active transactions and writes them to the transaction log in a single operation. After the write completes, waiting client threads are notified.

  • If false, write operations to the transaction log are handled by individual connection threads. Only one thread at a time is able to write to the log.

imq.persist.file.txnLog.logNonTransactedMsgSend

Boolean 

false

This property is applicable only if imq.persist.file.newTxnLog.enabled is true.

Overrides the behavior for persisting non-transacted messages (as defined by the imq.persist.file.sync.enabled property):

  • If true, non-transacted messages are written to the transaction log before they are written to the persistent store.

  • If false, non-transacted messages are written directly to the persistent store.

imq.persist.file.txnLog.logNonTransactedMsgAck

Boolean 

false

This property is applicable only if imq.persist.file.newTxnLog.enabled is true.

Overrides the behavior for persisting non-transacted message acknowledgements (as defined by the imq.persist.file.sync.enabled property):

  • If true, acknowledgements of non-transacted messages are written to the transaction log before they are written to the persistent store.

  • If false, acknowledgements of non-transacted messages are written directly to the persistent store.

JDBC-Based Persistence Properties

Table 17–7 lists the broker properties related to JDBC-based persistence. The first of these properties, imq.persist.jdbc.dbVendor, identifies the database vendor being used for the broker’s persistent data store; all of the remaining properties are qualified by this vendor name.

Table 17–7 Broker Properties for JDBC-Based Persistence

Property 

Type 

Default Value 

Description 

imq.persist.jdbc.dbVendor

String 

None 

Name of database vendor for persistent data store:  

    hadb: HADB (Sun Microsystems, Inc.)


    derby: Java DB (Sun Microsystems, Inc.)


    oracle: Oracle (Oracle Corporation)


    mysql: MySQL (Sun Microsystems, Inc.)


    postgresql: postgreSQL


imq.persist.jdbc.connection.limit

Integer 

5

The maximum number of connections that can be opened to the database. 

imq.persist.jdbc.vendorName.driver

String 

per vendor 

Java class name of JDBC driver, if needed, for connecting to database from vendor vendorName

imq.persist.jdbc.vendorName.opendburl

String 

None 

URL for connecting to existing database from vendor vendorName

Applicable when driver is used to connect to database. 

imq.persist.jdbc.vendorName.createdburl [Optional]

String 

None 

URL for creating new database from vendor vendorName

Applies for embedded database, such as Java DB. 

imq.persist.jdbc.vendorName.closedburl

String 

None 

URL for closing connection to database from vendor vendorName

Applies for some embedded databases, such as Java DB. 

imq.persist.jdbc.vendorName.user

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

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.password, [Should be used only in password files]

String 

None 

Password, if required, for connecting to database from vendor vendorName

imq.persist.jdbc.vendorName.property.propName

String 

None 

Vendor-specific property propName for database from vendor vendorName

imq.persist.jdbc.vendorName.tableoption

String 

None 

Vendor-specific options passed to the database when creating the table schema. 

Security Properties

Table 17–8 lists broker properties related to security services: authentication, authorization, and encryption. Table 17–9 lists broker properties related specifically to LDAP-based authentication, and Table 17–10 lists broker properties related specifically to JAAS-based authentication.

Table 17–8 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.

imq.accesscontrol.type

String 

file

Specifies the access control type 

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, Distribution-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, Distribution-Specific Locations of Message Queue Data).

imq.accesscontrol.file.url

String 

Not set 

The location, as a URL, of the access control file. 

imq.serviceName.accesscontrol.file.url

String 

None 

The location, as a URL, of the access control file for connection service 

If specified, overrides imq.accesscontrol.file.url for the designated connection service.

imq.keystore.file.dirpath

String 

See Appendix A, Distribution-Specific Locations of Message Queue Data

Path to directory containing key store file 

imq.keystore.file.name

String 

keystore

Name of key store file 

imq.keystore.password [To be used only in password files]

String 

None 

Password for key store file 

imq.passfile.enabled

Boolean 

false

Obtain passwords from password file?  

imq.passfile.dirpath

String 

See Appendix A, Distribution-Specific Locations of Message Queue Data

Path to directory containing password file 

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.

imq.audit.enabled

Boolean 

false

Is audit logging to broker log file enabled? 

imq.audit.bsm.disabled

Boolean 

true

Is audit logging to the Solaris BSM audit log disabled? 

Table 17–9 lists broker properties related to LDAP-based user authentication.

Table 17–9 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



     

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.password [Should be used only in password files]

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

String 

None 

When set to a value of dn, specifies that DN username format is used for authentication (for example: uid=mquser,ou=People,dc=red,dc=sun,dc=com).

Also, the broker extracts the value of the imq.user.repository.lpdap.uidatr attribute from the DN username, and uses this value as the user name in access control operations.

If not set, then normal username format is used. 

imq.user_repository.ldap.usrfilter [Optional]

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

String 

None 

JNDI filter for LDAP group searches

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?

Table 17–10 lists broker properties related to JAAS-based user authentication.

Table 17–10 Broker Security Properties for JAAS Authentication

Property 

Type 

Default Value 

Description 

imq.user_repository.jaas.name

String 

None 

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

imq.user_repository.jaas.userPrincipalClass

String 

None 

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

imq.user_repository.jaas.groupPrincipalClass

String 

None 

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

Monitoring Properties

Table 17–11 lists the broker properties related to monitoring services.

Table 17–11 Broker Monitoring Properties

Property 

Type 

Default Value 

Description 

imq.log.level [Can be used with imqcmd update bkr command]

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

Boolean 

false

Log information about dead messages?  

If true, the following events will be logged:

  • A destination is full, having reached its maximum size or message count.

  • The broker discards a message for a reason other than an administrative command or delivery acknowledgment.

  • The broker moves a message to the dead message queue.

imq.log.console.stream

String 

ERR

Destination for console output:  

    OUT: stdout


    ERR: stderr


imq.log.console.output

String 

ERROR|WARNING

Categories of logging information to write to console:  

    NONE


    ERROR


    WARNING


    INFO


    ALL


The ERROR, WARNING, and INFO categories do not include those above them, so each must be specified explicitly if desired. Any combination of categories can be specified, separated by vertical bars (|).

imq.log.file.dirpath

String 

See Appendix A, Distribution-Specific Locations of Message Queue Data

Path to directory containing log file 

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

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

imq.log.file.rolloversecs

Integer 

604800 (one week)

Age of file, in seconds, at which output rolls over to a new log file 

A value of -1 denotes an unlimited number of seconds (no rollover based on file age).

imq.log.syslog.output [Solaris platform only]

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

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

String 

imqbrokerd_${imq.instanceName}

Identity string to be prefixed to all messages logged to syslog

imq.log.syslog.logpid

Boolean 

true

Log broker process ID with message?  

imq.log.syslog.logconsole

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?  

imq.metrics.topic.timetolive

Integer 

300

Lifetime, in seconds, of metrics messages sent to metric topic destinations 

imq.primaryowner.name [Used by JES Monitoring Framework]

String 

System property user.name (user who started the broker)

Name of primary system owner 

imq.primaryowner.contact

String 

System property user.name (user who started the broker)

Contact information for primary system owner 

imq.broker.adminDefinedRoles.count

Integer 

None 

Number of defined roles 

imq.broker.adminDefinedRoles.nameN

String 

Broker instance name 

Name of defined role N (where N ranges from 0 to .count-1)

Example:


...name0=Stocks JMS Server
...name1=JMS provider for appserver

Cluster Configuration Properties

Table 17–12 lists the configuration properties related to broker clusters.

Table 17–12 Broker Properties for Cluster Configuration

Property 

Type 

Default Value 

Description 

imq.cluster.url [Must have the same value for all brokers in a cluster] , [Can be used with imqcmd update bkr command]

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 a high-availability cluster?  

imq.cluster.brokerlist, [Conventional clusters only]

String 

None 

List of broker addresses belonging to cluster 

The list consists of one or more addresses, separated by commas. Each address specifies the host name and Port Mapper port number of a broker in the cluster, in the form hostName:portNumber.

Example:

    host1:3000,host2:8000,ctrlhost



Note –

If set, this property is ignored (and a warning logged) for high-availability clusters; all brokers configured to use the cluster’s shared persistent store are automatically recognized as members of the cluster.


imq.cluster.hostname [Can be specified independently for each broker in a cluster]

String 

None 

Host name or IP address for cluster connection service

If specified, overrides imq.hostname (see Table 17–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.port

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

String 

tcp

Network transport protocol for cluster connection service

For secure, encrypted message delivery between brokers, set this property to ssl.

imq.cluster.masterbroker,

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 –

enhanced clusters cannot have a master broker. If this property is set for a broker belonging to an enhanced cluster, the broker will log a warning message and ignore the property.


imq.cluster.clusterid [enhanced clusters only] ,

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 a high-availability cluster, this property is used in database table names in place of imq.brokerid (see Table 17–1).


imq.cluster.heartbeat.hostname

String 

None 

Host name or IP address for heartbeat service

If specified, overrides imq.hostname (see Table 17–1) for the heartbeat service.

imq.cluster.heartbeat.port

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

Integer 

Interval between heartbeats, in seconds 

imq.cluster.heartbeat.threshold

Integer 

Number of missed heartbeat intervals after which to invoke monitor service 

imq.cluster.monitor.interval

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

Integer 

Number of missed monitor intervals after which to initiate broker takeover 

Bridge Properties

Table 17–13 lists broker properties related to the bridge service manager. Table 17–14 lists broker properties related specifically to the JMS bridge service, and Table 17–15 lists broker properties related specifically to the STOMP bridge service.

Table 17–13 Broker Properties for the Bridge Service Manager

Property 

Type 

Default Value 

Description 

imq.bridge.enabled

Boolean 

false

Is the bridge service enabled on this broker? 

imq.bridge.activelist

String 

None 

List of bridges that will be loaded on broker startup. 

The list consists of one or more bridge names, separated by commas. All bridge names for a broker must be unique. 

imq.bridge.admin.user

String 

None 

The Message Queue broker administrative user to be used by the bridge service manager and individual bridges to create ADMIN connections to the broker. For JMS bridges, this user is also used to access the JMS bridge's built-in DMQ destination. 

imq.bridge.admin.password

String 

None 

The password for the imq.bridge.admin.user user.

Table 17–14 Broker Properties for a JMS Bridge Service

Property 

Type 

Default Value 

Description 

imq.bridge.name.type

String 

None 

The bridge type of the bridge named name. For JMS bridges, specify a value of JMS or jms.

imq.bridge.name.xmlurl

String 

None 

The URL where the XML configuration file for the JMS bridge name is stored.

Examples:

    http://webserver/imq/jmsbridge1.config.xml


    (for a file on a Web server)


     
    

    file:/net/fileserver/imq/jmsbridge1.config.xml


    (for a file on a shared drive)


imq.bridge.name.autostart

Boolean 

true

Should the JMS bridge name be automatically started when the broker is started?

imq.bridge.name.logfile.limit

Integer 

0

The approximate maximum number of bytes the JMS bridge name writes to any one log file.

A value of 0 (zero) indicates that there is no maximum limit.

imq.bridge.name.logfile.count

Integer 

1

The number of log files the JMS bridge name cycles through.

imq.bridge.tm.props

imq.bridge.name.tm.props

String 

None 

Each of these properties specifies a list of key-value pairs for the built-in transaction coordinator for the JMS bridge name.

The list consists of one or more key=value pairs separated by commas.

When the imq.persist.store is file, the built-in transaction coordinator supports these keys: txlogSize, txlogSync, and txlogMmap.

If the same key appears in both properties, the value specified in imq.bridge.name.tm.props takes precedence.

Table 17–15 Broker Properties for the STOMP Bridge Service

Property 

Type 

Default Value 

Description 

imq.bridge.stomp.tcp.enabled

Boolean 

true

Does the STOMP bridge accept TCP connections? 

imq.bridge.stomp.tcp.port

Integer 

7672

The port on which the STOMP bridge listens for TCP connections, provided that imq.bridge.stomp.tcp.enabled is true.

imq.bridge.stomp.tls.enabled

Boolean 

false

Does the STOMP bridge accept SSL/TLS connections? 

If true, a keystore must be created using the imqkeytool utility before starting the broker.

imq.bridge.stomp.tls.port

Integer 

7673

The port on which the STOMP bridge listens for SSL/TLS connections, provided that imq.bridge.stomp.tls.enabled is true.

imq.bridge.stomp.tls.requireClientAuth

Boolean 

false

Do SSL/TLS connections require client authentication? 

imq.bridge.stomp.consumerFlowLimit

Integer 

1000

The maximum number of unacknowledged messages that the STOMP bridge will deliver on a transacted STOMP subscription. The STOMP client must then acknowledge the messages and commit the transaction. 

imq.bridge.stomp.messageTransformer

String 

None 

The fully qualified class name of a class that extends the Message Queue bridge MessageTransformer abstract class by implementing the transform() method. Place this class under the IMQ_HOME/lib/ext. directory

imq.bridge.stomp.logfile.limit

Integer 

0

The approximate maximum number of bytes the STOMP bridge writes to any one log file. 

A value of 0 (zero) indicates that there is no maximum limit.

imq.bridge.stomp.logfile.count

Integer 

1

The number of log files the STOMP bridge cycles through. 

JMX Properties

The broker properties listed in Table 17–16 support the use of the Java Management Extensions (JMX) application programming interface by Java applications. The JMX API is used to configure and monitor broker resources.

These JMX-related properties can be set in the broker's instance configuration file (config.properties) or at broker startup with the -D option of the Broker utility (imqbrokerd). None of these properties can be set dynamically with the Command utility (imqcmd).

In addition, some of these properties (imq.jmx.rmiregistry.start, imq.jmx.rmiregistry.use, imq.jmx.rmiregistry.port) can be set with corresponding Broker utilityimqbrokerd options described in Table 16–1.

See Appendix D, JMX Support for further information on administrative support of JMX clients.

Table 17–16 Broker Properties for JMX Support

Property 

Type 

Default Value 

Description 

imq.jmx.connector.activelist

String 

jmxrmi

Names of JMX connectors to be activated at broker startup, separated by commas

imq.jmx.connector.RMIconnectorName.urlpath

String 

Shown in next column 

urlpath component of JMX service URL for connector connectorName

Useful in cases where an RMI registry is being used and the JMX service URL path must be set explicitly (such as when a shared external RMI registry is used). See The JMX Service URL.

Default:

   /jndi/rmi://brokerHost:rmiPort
      /brokerHost/brokerPort/connectorName

imq.jmx.connector.RMIconnectorName.port

Integer 

None: the port is dynamically allocated 

Port number of JMX connector 

Used to specify a static/known JMX connector port, typically in cases where a JMX client is accessing the broker's MBean server through a firewall. See JMX Connections Through a Firewall.

imq.jmx.connector.RMIconnectorName.useSSL

Boolean 

false

Use Secure Socket Layer (SSL) for connector connectorName?

This property is set to true for the ssljmxrmi connector.

imq.jmx.connector.RMIconnectorName.brokerHostTrusted

Boolean 

false

Trust any certificate presented by broker for connector connectorName?

Applies only when imq.jmx.connector.connectorName.useSSL is true.

If false, the JMX client runtime will validate all certificates presented to it. Validation will fail if the signer of the certificate is not in the client's trust store.

If true, validation of certificates is skipped. This can be useful, for instance, during software testing when a self-signed certificate is used.

imq.jmx.rmiregistry.start

Boolean 

false

Start RMI registry at broker startup?

If true, the broker will start an RMI registry at the port specified by imq.jmx.rmiregistry.port and use the regsitry to store the JMX connector stub. (The value of imq.jmx.rmiregistry.use is ignored in this case.)

For convenience, this property can also be set at broker startup with the -startRmiRegistry option ofimqbrokerd.

imq.jmx.rmiregistry.use

Boolean 

false

Use an existing RMI registry?

Applies only if imq.jmx.rmiregistry.start is false.

If true, the broker will use an existing RMI registry on the local host at the port specified by imq.jmx.rmiregistry.port to store the JMX connector stub. The existing RMI registry must already be running at broker startup.

For convenience, this property can also be set at broker startup with the -useRmiRegistry option ofimqbrokerd.

imq.jmx.rmiregistry.port

Integer 

1099

Port number of RMI registry

Applies only if imq.jmx.rmiregistry.start is true or imq.jmx.rmiregistry.use is true.

This port number will be included in the URL path of the JMX service URL.  

For convenience, this property can also be set at broker startup with the -rmiRegistryPort option of imqbrokerd.

Alphabetical List of Broker Properties

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

Table 17–17 Alphabetical List of Broker Properties

Property 

Table 

imq.accesscontrol.enabled

Table 17–8

imq.accesscontrol.type

Table 17–8

imq.accesscontrol.file.filename

Table 17–8

imq.audit.bsm.disabled

Table 17–8

imq.audit.enabled

Table 17–8

imq.authentication.basic.user_repository

Table 17–8

imq.authentication.client.response.timeout

Table 17–8

imq.authentication.type

Table 17–8

imq.autocreate.destination.isLocalOnly

Table 17–3

imq.autocreate.destination.limitBehavior

Table 17–3

imq.autocreate.destination.maxBytesPerMsg

Table 17–3

imq.autocreate.destination.maxNumMsgs

Table 17–3

imq.autocreate.destination.maxNumProducers

Table 17–3

imq.autocreate.destination.maxTotalMsgBytes

Table 17–3

imq.autocreate.destination.useDMQ

Table 17–3

imq.autocreate.queue

Table 17–3

imq.autocreate.queue.consumerFlowLimit

Table 17–3

imq.autocreate.queue.localDeliveryPreferred

Table 17–3

imq.autocreate.queue.maxNumActiveConsumers

Table 17–3

imq.autocreate.queue.maxNumBackupConsumers

Table 17–3

imq.autocreate.reaptime

Table 17–3

imq.autocreate.topic

Table 17–3

imq.autocreate.topic.consumerFlowLimit

Table 17–3

imq.broker.adminDefinedRoles.count

Table 17–11

imq.broker.adminDefinedRoles.namen

Table 17–11

imq.brokerid

Table 17–1

imq.bridge.activelist

Table 17–13

imq.bridge.admin.password

Table 17–13

imq.bridge.admin.user

Table 17–13

imq.bridge.enabled

Table 17–13

imq.bridge.name.autostart

Table 17–14

imq.bridge.name.logfile.count

Table 17–14

imq.bridge.name.logfile.limit

Table 17–14

imq.bridge.name.tm.props

Table 17–14

imq.bridge.name.type

Table 17–14

imq.bridge.name.xmlurl

Table 17–14

imq.bridge.stomp.consumerFlowLimit

Table 17–15

imq.bridge.stomp.logfile.count

Table 17–15

imq.bridge.stomp.logfile.limit

Table 17–15

imq.bridge.stomp.messageTransformer

Table 17–15

imq.bridge.stomp.tcp.enabled

Table 17–15

imq.bridge.stomp.tcp.port

Table 17–15

imq.bridge.stomp.tls.enabled

Table 17–15

imq.bridge.stomp.tls.port

Table 17–15

imq.bridge.stomp.tls.requireClientAuth

Table 17–15

imq.bridge.tm.props

Table 17–14

imq.cluster.brokerlist

Table 17–12

imq.cluster.clusterid

Table 17–12

imq.cluster.ha

Table 17–12

imq.cluster.heartbeat.hostname

Table 17–12

imq.cluster.heartbeat.interval

Table 17–12

imq.cluster.heartbeat.port

Table 17–12

imq.cluster.heartbeat.threshold

Table 17–12

imq.cluster.hostname

Table 17–12

imq.cluster.masterbroker

Table 17–12

imq.cluster.monitor.interval

Table 17–12

imq.cluster.monitor.threshold

Table 17–12

imq.cluster.port

Table 17–12

imq.cluster.transport

Table 17–12

imq.cluster.url

Table 17–12

imq.destination.DMQ.truncateBody

Table 17–2

imq.destination.logDeadMsgs

Table 17–11

imq.hostname

Table 17–1

imq.imqcmd.password

Table 17–8

imq.jmx.connector.activelist

Table 17–16

imq.jmx.connector.RMIconnectorName.brokerHostTrusted

Table 17–16

imq.jmx.connector.RMIconnectorName.port

Table 17–16

imq.jmx.connector.RMIconnectorName.urlpath

Table 17–16

imq.jmx.connector.RMIconnectorName.useSSL

Table 17–16

imq.jmx.rmiregistry.port

Table 17–16

imq.jmx.rmiregistry.start

Table 17–16

imq.jmx.rmiregistry.use

Table 17–16

imq.keystore.file.dirpath

Table 17–8

imq.keystore.file.name

Table 17–8

imq.keystore.password

Table 17–8

imq.keystore.propertyName

Table 17–8

imq.log.console.output

Table 17–11

imq.log.console.stream

Table 17–11

imq.log.file.dirpath

Table 17–11

imq.log.file.filename

Table 17–11

imq.log.file.output

Table 17–11

imq.log.file.rolloverbytes

Table 17–11

imq.log.file.rolloversecs

Table 17–11

imq.log.level

Table 17–11

imq.log.syslog.facility

Table 17–11

imq.log.syslog.identity

Table 17–11

imq.log.syslog.logconsole

Table 17–11

imq.log.syslog.logpid

Table 17–11

imq.log.syslog.output

Table 17–11

imq.log.timezone

Table 17–11

imq.message.expiration.interval

Table 17–2

imq.message.max_size

Table 17–2

imq.metrics.enabled

Table 17–11

imq.metrics.interval

Table 17–11

imq.metrics.topic.enabled

Table 17–11

imq.metrics.topic.interval

Table 17–11

imq.metrics.topic.persist

Table 17–11

imq.metrics.topic.timetolive

Table 17–11

imq.passfile.dirpath

Table 17–8

imq.passfile.enabled

Table 17–8

imq.passfile.name

Table 17–8

imq.persist.file.destination.message.filepool.limit

Table 17–5

imq.persist.file.message.cleanup

Table 17–5

imq.persist.file.message.filepool.cleanratio

Table 17–5

imq.persist.file.message.max_record_size

Table 17–5

imq.persist.file.sync.enabled

Table 17–5

imq.persist.file.transaction.memorymappedfile.enabled

Table 17–5

imq.persist.jdbc.dbVendor

Table 17–7

imq.persist.jdbc.vendorName.closedburl

Table 17–7

imq.persist.jdbc.vendorName.createdburl

Table 17–7

imq.persist.jdbc.vendorName.driver

Table 17–7

imq.persist.jdbc.vendorName.needpassword

Table 17–7

imq.persist.jdbc.vendorName.opendburl

Table 17–7

imq.persist.jdbc.vendorName.password

Table 17–7

imq.persist.jdbc.vendorName.property.propName

Table 17–7

imq.persist.jdbc.vendorName.user

Table 17–7

imq.persist.store

Table 17–4

imq.ping.interval

Table 17–1

imq.portmapper.backlog

Table 17–1

imq.portmapper.hostname

Table 17–1

imq.portmapper.port

Table 17–1

imq.primaryowner.contact

Table 17–11

imq.primaryowner.name

Table 17–11

imq.resourceState.count

Table 17–2

imq.resourceState.threshold

Table 17–2

imq.service.activelist

Table 17–1

imq.serviceName.accesscontrol.enabled

Table 17–8

imq.serviceName.accesscontrol.file.filename

Table 17–8

imq.serviceName.authentication.type

Table 17–8

imq.serviceName.max_threads

Table 17–1

imq.serviceName.min_threads

Table 17–1

imq.serviceName.protocolType.hostname

Table 17–1

imq.serviceName.protocolType.port

Table 17–1

imq.serviceName.threadpool_model

Table 17–1

imq.shared.connectionMonitor_limit

Table 17–1

imq.system.max_count

Table 17–2

imq.system.max_size

Table 17–2

imq.transaction.autorollback

Table 17–2

imq.user_repository.ldap.base

Table 17–9

imq.user_repository.ldap.gidattr

Table 17–9

imq.user_repository.ldap.grpbase

Table 17–9

imq.user_repository.ldap.grpfilter

Table 17–9

imq.user_repository.ldap.grpsearch

Table 17–9

imq.user_repository.ldap.memattr

Table 17–9

imq.user_repository.ldap.password

Table 17–9

imq.user_repository.ldap.principal

Table 17–9

imq.user_repository.ldap.propertyName

Table 17–9

imq.user_repository.ldap.server

Table 17–9

imq.user_repository.ldap.ssl.enabled

Table 17–9

imq.user_repository.ldap.timeout

Table 17–9

imq.user_repository.ldap.uidattr

Table 17–9

imq.user_repository.ldap.usrfilter

Table 17–9

imq.user_repository.jaas.name

Table 17–10

imq.user_repository.jaas.userPrincipalClass

Table 17–10

imq.user_repository.jaas.groupPrincipalClass

Table 17–10