|
| |
| Sun Java System Message Queue 3 2005Q1 Administration Guide | |
Chapter 14
Broker Properties ReferenceThis chapter lists and describes the broker configuration properties. The first section is an alphabetical list of all broker properties, with a reference to the section that contains a full description. All other sections group a set of broker properties by function and provide full descriptions of the properties.
This chapter contains the following sections:
In the description tables, properties are marked if you can set them by using the imqcmd update bkr command.
Alphabetical List of PropertiesTable 14-1 is an alphabetical list of broker instance properties. Use it to determine the category of any property, and then use the category description to find a full property description elsewhere in this chapter.
In the table, the left column alphabetically lists each property. The right column shows the category to which the property belongs and provides a cross-reference to the appropriate section.
Connection Service PropertiesTable 14-2 lists the Connection Service properties. The first column lists the property names. For each property name, the second column describes the property, the third column specifies its type, and the fourth column gives its default value.
Table 14-2 Connection Service Properties
Property Name
Description
Type
Default
imq.service.activelist
A list of connection services, by name, separated by commas, to be made active at broker startup. Supported services are: jms, ssljms, httpjms, httpsjms, admin, ssladmin.
list
jms,admin
imq.ping.interval
The period, in seconds, between successive attempts of the broker to ping the Message Queue client runtime across a connection.
integer
120
imq.hostname
The host (hostname or IP address) to which all connection services bind if there is more than one host available (for example, if there is more than one network interface card in a computer).
string
All available
IP addressesimq.portmapper.port1
The broker’s primary port—the port at which the Port Mapper resides. If you are running more than one broker instance on a host, each must be assigned a unique Port Mapper port.
integer
7676
imq.portmapper.hostname
The host (hostname or IP address) to which the Port Mapper binds if there is more than one host available (for example, if there is more than one network interface card in a computer).
string
Inherited from
imq.hostnameimq.portmapper.backlog
The maximum number of concurrent requests that the Port Mapper can handle before rejecting requests. The property sets the number of requests that can be stored in the operating system backlog waiting to be handled by the Port Mapper.
integer
50
imq.service_name.
protocol_type2.portFor jms, ssljms, admin, and ssladmin services only, the port number for the named connection service.
To configure the httpjms and httpsjms connection services, see Appendix C, "HTTP/HTTPS Support."
integer
0 (zero)
The port is
dynamically
allocated by the
Port Mapper.imq.service_name.
protocol_type2.hostnameFor jms, ssljms, admin, and ssladmin services only, the host (hostname or IP address) to which the named connection service binds if there is more than one host available (for example, if there is more than one network interface card in a computer).
string
Inherited from
imq.hostnameimq.service_name.
min_threadsThe number of threads, which once reached, are maintained in the thread pool for use by the named connection service.
The default value varies by connection service.
integer
10 (jms)
10 (ssljms)
10 (httpjms)
10 (httpsjms)
4 (admin)
4 (ssladmin)
imq.service_name.
max_threadsThe number of threads beyond which no new threads are added to the thread pool for use by the named connection service. The number must be greater than zero and greater in value than the value of min_threads.
The default value varies by connection service.
integer
1000 (jms)
500 (ssljms)
500 (httpjms)
500 (httpsjms)
10 (admin)
10 (ssladmin)
imq.service_name.
threadpool_modelA string specifying whether threads are dedicated to connections (dedicated) or shared by connections as needed (shared) for the named connection service. Shared model (thread pool management) increases the number of connections supported by a broker, but is implemented only for the jms and admin connection services.
The default value varies by connection service.
string
dedicated (jms)
dedicated (ssljms)
dedicated (httpjms)
dedicated (httpsjms)
dedicated (admin)
dedicated (ssladmin)
imq.shared.
connectionMonitor_limitFor shared thread pool model only, the maximum number of connections that can be monitored by a distributor thread. (The system allocates enough distributor threads to monitor all connections.) The smaller this value, the faster the system can assign active connections to threads. A value of -1 means no limit.
The default value varies by operating system.
integer
512 (Solaris & Linux)
64 (Windows)
1This property can be used with the imqcmd update bkr command.
Message Router PropertiesTable 14-3 lists the Message Router properties. The first column lists the property names. For each property name, the second column describes the property, the third column specifies its type, and the fourth column gives its default value.
The auto-create properties that configure the message server’s ability to automatically create destinations are listed in Table 14-4.
Table 14-3 Message Router Properties
Property Name
Description
Type
Default
imq.destination.
DMQ.truncateBody1A boolean value specifying whether the broker removes the body of a message before storing it in the dead message queue. A value of true causes the broker to save just the message header and property data. A value of false causes the broker to save the header and body.
boolean
false
imq.message.
expiration.intervalThe interval, in seconds, at which reclamation of expired messages occurs.
integer
60
imq.system.max_count1
The maximum number of messages held by the broker. Additional messages will be rejected. A value of -1 means no limit.
integer
-1
imq.system.max_size1
The maximum total size (in bytes, Kbytes, or Mbytes) of messages held by the broker. Additional messages will be rejected. A value of -1 means no limit.
byte string2
-1
imq.message.max_size1
The maximum allowed size (in bytes, Kbytes, or Mbytes) of a message body. Any message larger than this will be rejected. A value of -1 means no limit.
byte string2
70m
imq.resource_state.
thresholdThe percent memory utilization at which each memory resource state is triggered. The resource state can have the values green, yellow, orange, and red.
integer
(percent)0 (green)
80 (yellow)
90(orange)
98 (red)
imq.resource_state.count
The maximum number of incoming messages allowed in a batch before system memory is checked to see whether a new memory threshold has been reached. This limit throttles back message producers as system memory becomes increasingly scarce.
integer
(percent)5000 (green)
500 (yellow)
50(orange)
0 (red)
imq.transaction.
autorollbackA boolean value specifying whether distributed transactions left in a PREPARED state are automatically rolled back when a broker is started up. If false, you must manually commit or roll back transactions using imqcmd (see Managing Transactions).
boolean
false
1This property can be used with the imqcmd update bkr command.
2A value that is typed as a byte string can be expressed in bytes, Kbytes, and Mbytes: For example: 1000 means 1000 bytes; 7500b means 7500 bytes; 77k means 77 kilobytes (77 x 1024 = 78848 bytes); 17m means 17 megabytes (17 x 1024 x 1024 = 17825792 bytes)
Table 14-4 lists the properties that the broker uses when automatically creating destinations.
Table 14-4 Auto-create Configuration Properties
Property Name
Description
Type
Default
imq.autocreate.destination.
isLocalOnly(Applies only to broker clusters.) A boolean value specifying that a destination is not replicated on other brokers, and is therefore limited to delivering messages only to local consumers (consumers connected to the broker on which the destination is created). This attribute cannot be updated once the destination has been created.
boolean
false
imq.autocreate.destination.
limitBehaviorA string specifying how the broker responds when a memory-limit threshold is reached. Values are:
- FLOW_CONTROL — Slows down producers.
- REMOVE_OLDEST — Throws out oldest messages.
- REMOVE_LOW_PRIORITY — Throws out lowest priority messages according to age of the messages.
- REJECT_NEWEST — Rejects the newest messages. The producing client gets an exception for rejection of persistent messages only. To use this limit behavior with non-persistent messages, set the imqAckOnProduce connection factory attribute.
If you set this property to REMOVE_OLDEST or REMOVE_LOW_PRIORITY and set imq.autocreate.destination.useDMQ to true, the broker moves excess messages to the dead message queue.
string
REJECT
NEWESTimq.autocreate.destination.
maxBytesPerMsgThe maximum size (in bytes) of any single message allowed in an auto-created destination. A value of -1 indicates that message size is unlimited.
byte string1
10k
imq.autocreate.destination.
maxNumMsgsThe maximum number of unconsumed messages allowed in an auto-created destination. A value of -1 indicates that the number is unlimited.
integer
100,000
imq.autocreate.destination.
maxNumProducersThe maximum number of producers allowed for the destination. When this limit is reached, no new producers can be created. A value of -1 indicates that number of producers is unlimited.
integer
100
imq.autocreate.destination.
maxTotalMsgBytesThe maximum total amount of memory (in bytes) allowed for unconsumed messages in the destination. A value of -1 indicates that memory is unlimited.
byte string2
10m
imq.autocreate.destination.
useDMQA boolean value specifying whether the broker moves dead messages for auto-created destinations to the dead message queue.
boolean
true
imq.autocreate.queue2
A boolean value specifying whether a broker is allowed to auto-create a queue destination.
boolean
true
imq.autocreate.queue.
consumerFlowLimitThe maximum number of messages that will be delivered to a 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 commences. This limit can be overridden by a lower value set for the destination’s consumers on their respective connections. A value of -1 means an unlimited number.
integer
1000
imq.autocreate.queue.
localDeliveryPreferred(Applies only to load-balanced queue delivery in broker clusters.) A boolean value specifying that messages be delivered to remote consumers only if there are no consumers on the local broker. Requires that the auto-created destination not be restricted to local-only delivery (isLocalOnly = false).
boolean
false
imq.autocreate.queue.
maxNumActiveConsumersThe maximum number of consumers that can be active in load-balanced delivery from an auto-created queue destination. A value of -1 means an unlimited number.
integer
1
imq.autocreate.queue.
maxNumBackupConsumersThe maximum number of backup consumers that can take the place of active consumers if any fail during load-balanced delivery from an auto-created queue destination. A value of -1 means an unlimited number.
integer
0 (zero)
imq.autocreate.topic
A boolean value specifying whether a broker is allowed to auto-create a topic destination.
boolean
true
imq.autocreate.topic.
consumerFlowLimitThe maximum number of messages that will be delivered to a consumer in a single batch. A value of -1 means an unlimited number.
integer
1000
1A value that is typed as a byte string can be expressed in bytes, Kbytes, and Mbytes: For example: 1000 means 1000 bytes; 7500b means 7500 bytes; 77k means 77 kilobytes (77 x 1024 = 78848 bytes); 17m means 17 megabytes (17 x 1024 x 1024 = 17825792 bytes)
2This property can be used with imqcmd update bkr.
Persistence Manager PropertiesTo configure the persistence features of the broker, you must specify the value for imq.persist.store, or accept the default value.
The properties that support file-based persistence and JDBC-based persistence are described in the next sections.
File-Based Persistence
Table 14-6 lists the properties that support file-based persistence. The first column lists the property names. For each property name, the second column describes the property, the third column specifies its type, and the fourth column gives its default value.
Table 14-6 Properties for File-Based Persistence
Property Name
Description
Type
Default
imq.persist.file.sync.
enabledA boolean value specifying whether persistence operations synchronize in-memory state with the physical storage device. If this property is set to true, data loss due to system crash is eliminated, but at the expense of performance of persistence operations.
If you are running Sun Cluster and the Sun Cluster Data Service for Message Queue, set this property to true for brokers on all cluster nodes.
boolean
false
imq.persist.file.message.
max_record_sizeFor built-in, file-based persistence, the maximum size of a message that will be added to the message storage file, rather than being stored in a separate file.
byte string1
1m
imq.persist.file.
destination.message.
filepool.limitFor built-in, file-based persistence, the maximum number of free files available for reuse in the destination file pool. The larger the number the faster the broker can process persistent data. Free files in excess of this value will be deleted. The broker will create and delete additional files, in excess of this limit, as needed.
integer
100
imq.persist.file.message.
filepool.cleanratioFor built-in, file-based persistence, the percentage of free files in destination file pools that are maintained in a clean state (truncated to zero). The higher this value, the more overhead required to clean files during operation, but the less disk space required for the file pool.
integer
0 (zero)
imq.persist.file.
message.cleanupFor built-in, file-based persistence, a boolean value specifying whether or not the broker cleans up free files in destination file pools on shutdown. A value of false speeds up broker shutdown, but requires more disk space for the file store.
boolean
false
1A value that is typed as a byte string can be expressed in bytes, Kbytes, and Mbytes. Examples: 1000 means 1000 bytes; 7500b means 7500 bytes; 77k means 77 kilobytes (77 x 1024 = 78848 bytes); 17m means 17 megabytes (17 x 1024 x 1024 = 17825792 bytes)
JDBC-Based Persistence
Table 14-7 contains the properties that support JDBC-based persistence. The table lists the properties, describes them, and then gives examples of how you would configure use with the PointBase product.
Security Manager PropertiesTable 14-8 lists the Security Manager properties. The first column lists the property names. For each property name, the second column describes the property, the third column specifies its type, and the fourth column gives its default value.
If you are using SSL, refer to the keystore configuration properties listed in Table 14-9, which follows.
Table 14-8 Security Manager Properties
Property Name
Description
Type
Default
imq.accesscontrol.
enabledA boolean value specifying whether to set access control for all connection services supported by a broker. Indicates whether system will check if an authenticated user has permission to use a connection service or to perform specific Message Queue operations with respect to specific destinations, as specified in the access control properties file.
boolean
true
imq.accesscontrol.file.
filenameThe name of an access control properties file for all connection services supported by a broker instance. The file name specifies a relative file path to the access control directory (see Appendix A, "Operating System-Specific Locations of Message Queue Data").
string
accesscontrol.
propertiesimq.audit.enabled
A boolean value specifying whether to start audit logging (Enterprise Edition only) to the broker log file.
boolean
false
imq.authentication.
basic.user_repositoryA string specifying (for base 64 coding) the type of user repository used for authentication, either file-based (file) or LDAP (ldap).
string
file
imq.authentication.
client.response.timeoutThe interval, in seconds, for the system to wait for a client to respond to an authentication request from the broker.
integer
180
imq.authentication.type
A string specifying whether the password should be passed in base 64 coding (basic) or as an MD5 digest (digest). Sets encoding for all connection services supported by a broker.
string
digest
imq.imqcmd.password
The password of an administrative user. The imqcmd command utility uses this password to authenticate the user of a command before performing an operation.
string
None
imq.keystore.property_name
For SSL-based services, a string specifying security properties relating to the SSL keystore. See Table 14-9
string
None
imq.passfile.dirpath
The path to the directory containing the passfile (depends on operating system).
string
See Appendix A
imq.passfile.enabled
A boolean value specifying whether user passwords (for SSL, LDAP, JDBC™) for secure communications are specified in a passfile.
boolean
false
imq.passfile.name
The name of the passfile.
string
passfile
imq.service_name.
accesscontrol.enabledA boolean value specifying whether to set access control for named connection service, overriding broker-wide setting. Indicates whether system will check if an authenticated user has permission to use the named connection service or to perform specific Message Queue operations with respect to specific destinations, as specified in the access control properties file.
boolean
Inherited from the system-wide property imq.
accesscontrol.
enabled.imq.service_name.
accesscontrol.file.
filenameThe name of an access control properties file for a named connection service of a broker instance. The file name specifies a relative file path to the access control directory (see Appendix A, "Operating System-Specific Locations of Message Queue Data").
The default value is inherited from the system-wide property imq.accesscontrol.file.filename
string
See description
imq.service_name.
authentication.typeA string specifying whether the password should be passed in base 64 coding (basic) or as an MD5 digest (digest). Sets encoding for named connection service, overriding any broker-wide setting.
The default value is inherited from the system-wide property imq.authentication.type.
string
See description
imq.user_repository.
ldap.baseThe directory base for user entries.
string
None
imq.user_repository.
ldap.gidattrThe provider-specific attribute identifier whose value is a group name.
string
None
imq.user_repository.
ldap.grpbaseThe directory base for group entries.
string
None
imq.user_repository.
ldap.grpfiltlerA JNDI search filter (a search query expressed as a logical expression). By specifying a search filter for groups, the broker can narrow the scope of a search and thus make it more efficient. For more information, see the JNDI tutorial at the following location.
http://java.sun.com/products/jndi/tutorial
This property does not have to be set.
string
None
imq.user_repository.
ldap.grpsearchA boolean value specifying whether to enable group searches. Consult the documentation provided by your LDAP provider to determine whether you can associate users into groups.
Note that nested groups are not supported in Message Queue.
boolean
false
imq.user_repository.
ldap.memattrThe attribute identifier in a group entry whose values are the distinguished names of the group’s members.
string
None
imq.user_repository.
ldap.passwordThe password associated with the distinguished name used by the broker.
Specify this property only in a passfile.
If the directory server allows anonymous searches, no password is needed.
string
None
imq.user_repository.
ldap.principalThe distinguished name that the broker uses to bind to the directory server for a search. If the directory server allows anonymous searches, this property does not need to be assigned a value.
string
None
imq.user_repository.
ldap.property_nameTo be supplied
To be supplied
To be supplied
imq.user_repository.
ldap.serverThe host:port for the LDAP server, where host specifies the fully qualified DNS name of the host running the directory server and port specifies the port number that the directory server is using for communications.
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 begins with ldap://.
Use this format even if you use SSL and have set the property imq.user_repository.ldap.ssl.enabled to true. You do not need to specify “ldaps” in the address.
string
None
imq.user_repository.
ldap.ssl.enabledA boolean value specifying whether the broker should use the SSL protocol when talking to an LDAP server.
boolean
false
imq.user_repository.
ldap.timeoutThe time limit for a search, in seconds.
integer
280
imq.user_repository.
ldap.uidattrThe provider-specific attribute identifier whose value uniquely identifies a user. For example: uid, cn, etc.
string
None
imq.user_repository.
ldap.usrfilterA JNDI search filter (a search query expressed as a logical expression). By specifying a search filter for users, the broker can narrow the scope of a search and thus make it more efficient. For more information, see the JNDI tutorial at the following location: http://java.sun.com/products/jndi/tutorial.
This property does not have to be set.
string
None
The configurable properties for the Message Queue keystore are shown in Table 14-9. Use these properties with SSL.
Table 14-9 Keystore Properties
Property Name
Description
Type
Default
imq.keystore.file.dirpath
For SSL-based services, the path to the directory containing the keystore file. Default: see Appendix A, "Operating System-Specific Locations of Message Queue Data."
string
None
imq.keystore.file.name
For SSL-based services: the name of the keystore file.
string
keystore
imq.keystore.password
For SSL-based services: the keystore password.
Specify this property only in a passfile.
string
None
Monitoring and Logging PropertiesTable 14-10 lists the properties related to monitoring and logging. The first column lists the property names. For each property name, the second column describes the property, the third column specifies its type, and the fourth column gives its default value.
Table 14-10 Monitoring Service Properties
Property Name
Description
Type
Default
imq.destination.logDeadMsgs1
A boolean value specifying whether the broker logs the following types of events:
boolean
false
imq.log.console.output
A string specifying the categories of logging information that are written to the console. The value can be one of the following:
string
ERROR|WARNING
imq.log.console.stream
A string specifying whether console output is written to stdout (OUT) or stderr (ERR).
string
ERR
imq.log.file.dirpath
The path to the directory containing the log file (depends on operating system).
string
See Appendix A
imq.log.file.filename
The name of the log file.
string
log.txt
imq.log.file.output
The categories of logging information to be written to the console. The value can be one of the following:
string
ALL
imq.log.file.rolloverbytes1
The size, in bytes, of the log file at which output rolls over to a new log file. A value of -1 disables rollover based on file size.
integer
-1
imq.log.file.rolloversecs1
The age of the log file, in seconds, at which output rolls over to a new log file. A value of -1 disables rollover based on file age.
integer
604800
(one week)imq.log.level1
A string specifying the logger level: the categories of output that can be written to an output channel. Includes the specified category and all higher level categories as well. Values, from high to low, are: ERROR, WARNING, INFO.
string
INFO
imq.log.syslog.facility
(Solaris only) A string specifying what syslog facility the Message Queue broker should log as. Values mirror those listed in the syslog(3C) man page. Appropriate values for use with Message Queue are: LOG_USER, LOG_DAEMON, and LOG_LOCAL0 through LOG_LOCAL7.
string
LOG_DAEMON
imq.log.syslog.identity
(Solaris only) The identity string that should be added to the front of every message logged to syslog.
The default value is imqbrokerd_${imq.instanceName}
string
See the description
imq.log.syslog.logconsole
(Solaris only) A boolean value specifying whether to write messages to the system console if they cannot be sent to syslog.
boolean
false
imq.log.syslog.logpid
(Solaris only) A boolean value specifying (true/false) whether to log the broker process ID with the message or not.
boolean
true
imq.log.syslog.output
(Solaris only) A string specifying the categories of logging information that are written to syslogd(1M). The value can be one of the following:
string
ERROR
imq.log.timezone
A string representing the time zone for log time stamps. The identifiers are the same as those used by java.util.TimeZone.getTimeZone(). For example: GMT, America/LosAngeles, Europe/Rome, Asia/Tokyo.
string
Local time zone
imq.metrics.enabled
A boolean value specifying whether metrics information is being written to the logger. Does not affect production of metrics messages (see imq.metrics.topic.enabled).
boolean
true
imq.metrics.interval
If metrics logging is enabled (imq.metrics.enabled=true), the time interval, in seconds, at which metrics information is written to the logger. Does not affect time interval for production of metrics messages (see imq.metrics.topic.interval).
A value of -1 means never.
integer
-1
imq.metrics.topic.enabled
A boolean value specifying whether metrics message production is enabled. If false, an attempt to subscribe to a metric topic destination will throw a client-side exception.
boolean
true
imq.metrics.topic.interval
The time interval, in seconds, at which metrics messages are produced (sent to metric topic destinations).
integer
60
imq.metrics.topic.persist
A boolean value specifying whether metrics messages are persistent.
boolean
false
imq.metrics.topic.timetolive
The lifetime, in seconds, of metrics messages sent to metric topic destinations.
integer
300
1This property can be used with imqcmd update bkr.
Cluster Configuration PropertiesTable 14-11 summarizes the configuration properties related to broker clusters.
Table 14-11 Cluster Configuration Properties
Property Name
Description
Type
Default
imq.cluster.brokerlist
A comma-separated list of host:port entries identifying all the brokers in the cluster, where host is the host name of a broker and port is its Port Mapper port number.
Example:
host1:3000,host2:8000,ctrlhost
Must have the same value for all brokers in a cluster.
string
None
imq.cluster.masterbroker
The host name and port number of the cluster’s master broker, if any.
The value has the form host:port, where host is the host name of the master broker and port is its Port Mapper port number.
Example:
ctrlhost:7676
Must have the same value for all brokers in a cluster.
string
None
imq.cluster.url1
The URL of the 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)
Must have the same value for all brokers in a cluster.
string
None
imq.cluster.hostname
The host name or IP address to which the cluster connection service (used for internal communication between brokers in the cluster) binds if more than one host is available: for example, if there is more than one network interface card in a computer.
Can be specified independently for each broker in a cluster.
string
Inherited from the value of imq.hostname (see Table 14-2)
imq.cluster.port
The port number for the cluster connection service.
Can be specified independently for each broker in a cluster.
integer
0 (dynamically allocated.)
imq.cluster.transport
The network transport protocol used by the cluster connection service. For secure, encrypted message delivery between brokers, set this property to ssl.
Must have the same value for all brokers in a cluster.
string
tcp
1This property can be used with imqcmd update bkr.