This topic contains sections marked as revised for this release

WebSphere Message Brokers
File: an09140_
Writer: Bill Oppenheimer

Reference topic

This build: July 31, 2007 21:33:39

mqsichangeproperties command

Supported platforms

  • Windows systems.
  • Linux and UNIX systems.
  • z/OS. Run this command by customizing and submitting the BIPCHPR utility; see Contents of the broker PDSE.

Purpose

Use the mqsichangeproperties command to change properties that relate to inter-broker communications and the HTTP listener component, which includes the HTTP and HTTPS (SSL) support for the HTTPInput and HTTPReply nodes.

Usage notes

  • Before you run this command, ensure that the broker is running.
  • If you change any value, stop and restart the broker for the change to take effect.

Syntax

Parameters

BrokerName
(Required) The name of the broker to modify. This parameter must be the first parameter.
Start of change-b ComponentNameEnd of change
Start of change(Required) The name of the component.End of change
Start of change-e ExecutionGroupLabelEnd of change
Start of change(Required) The label of the execution group for which settings are to be viewed or changed.

The special name AllExecutionGroups is allowed, and is used to view settings for the Connector object name; this allows you to view broker-wide settings that affect all execution groups.

End of change

Start of changeYou must select one, and only one, option from -e and -b.End of change

-o ObjectName
(Required) The name of the object for which you want to change the properties.
Start of changeThe values:
  • Axis2Manager, HTTPConnector, and HTTPSConnector are accepted for all execution groups.
  • HTTPConnector, and HTTPSConnector are allowed if you select the value AllExecutionGroups for ExecutionGroupLabel.
End of change
-c ConfigurableService
Start of change(Required) The type of configurable service type, such as JMSProviders, JDBCProviders, and SecurityProfiles. Use the mqsireportproperties command to view the list of valid values.End of change
-n PropertyName
(Required) The name of the property to be changed.
For a JMSProvider resource, valid property names are:
  • jarsURL
  • nativeLibs
Start of changeFor a JDBCProviders resource, valid property names are:
  • databaseType
  • databaseVersion
  • type4DriverClassName
  • connectionUrlFormat
  • connectionUrlFormat Attr1-5
  • databaseName
  • description
  • jarsURL
  • portNumber
  • serverName
  • securityIdentity
End of change
Start of changeFor a SecurityProfiles resource, valid property names are:
  • authentication = {NONE, LDAP,TFIM}
  • authenticationConfig = string
  • mapping = {NONE, TFIM}
  • mappingConfig = string
  • authorization = {NONE, LDAP, TFIM}
  • authorizationConfig = string
  • propagation = {TRUE, FALSE}
End of change
-v PropertyValue
(Required) The value that is assigned to the property that is specified by the -n parameter. You can specify more than one property name and corresponding value using commas as separators; for example, -n Name1, Name2 -v Value1, Value2.

For example, if you set the -c parameter to JMSProviders, and the -n parameter to jarsURL, the expected value is a URL that specifies the file location of the JMS provider JAR files, while omitting the file:// of the URL.

Start of changeIf you set the -c parameter to SecurityProfiles, and the -n parameter to authentication, the property value can be NONE, LDAP, TFIM, or a user-defined value to specify an alternative.End of change

Start of changeIf you set the -c parameter to SecurityProfiles, and the -n parameter to authenticationConfig, the expected property value is a provider-specific configuration string.End of change

Start of changeIf you set the -c parameter to SecurityProfiles, and the -n parameter to mapping, the property value can be NONE, TFIM, or a user-defined value to specify an alternative.End of change

Start of changeIf you set the -c parameter to SecurityProfiles, and the -n parameter to mappingConfig, the expected property value is a provider-specific configuration string.End of change

Start of changeIf you set the -c parameter to SecurityProfiles, and the -n parameter to authorization, the property value can be NONE, LDAP, TFIM, or a user-defined value to specify an alternative.End of change

Start of changeIf you set the -c parameter to SecurityProfiles, and the -n parameter to authorizationConfig, the expected value is a provider-specific configuration string.End of change

Start of changeIf you set the -c parameter to SecurityProfiles, and the -n parameter to propagation, the property value can be either TRUE or FALSE.End of change

For Inter-broker communications, the following ObjectName value is available:
  • DynamicSubscriptionEngine
For the HttpListener component, which includes the HTTPInput and HTTPReply nodes, the following ObjectName values are available:
  • HTTPListener for controlling the HTTPListener process.
  • HTTPConnector for controlling HTTP communication with the HTTPInput and HTTPReply nodes.
  • HTTPSConnector for controlling HTTPS communication with the HTTPInput and HTTPReply nodes.
Httplistener is required when using the HTTP ObjectName settings.
For compatibility mode with previous versions the following ObjectName value is available:
  • ComIbmXmlParserFactory

HttpListener component parameter values

Valid property names for the HttpListener component are listed below:
httpDispatchThreads
The value is the number of threads that the broker dedicates to managing HTTP tunneling clients.
  • Value type - Integer
  • Initial value -32
httpProtocolTimeout
The value is the number of milliseconds in the HTTP protocol timeout interval. You can change this value to update the amount of time a broker is to wait for the next event during any phase of the HTTP tunneling protocol. A value of 0 causes the broker to wait indefinitely.
  • Value type - Integer
  • Initial value -10000
maxKeepAliveRequests
The value is the maximum number of HTTP requests that can be pipelined until the connection is closed by the server. Setting the attribute to 1 disables HTTP/1.0 keep-alive, as well as HTTP/1.1 keep-alive and pipelining. Setting the value to -1 allows an unlimited amount of pipelined or keep-alive HTTP requests.
  • Value type - Integer
  • Initial value -100
maxThreads
The value is the maximum number of request processing threads to be created by this Connector. This value, therefore, determines the maximum number of simultaneous requests that can be handled.
  • Value type - Integer
  • Initial value -200
Valid property names for the HTTPListener ObjectName:
enableSSLConnector
A boolean value which can be used to enable or disable the HTTPS (SSL) connector. This must be set to “true� before the http listener will listen for inbound SSL connections.
  • Value type - Boolean
  • Initial value - false
Valid property names for the HTTPConnector ObjectName:
address
For servers with more than one IP address, this value specifies which address is used for listening on the specified port. By default, this port is used on all IP addresses associated with the server. If specified, only one address can be used.
  • Value type - string
  • Initial value - null
port
The TCP port number on which this Connector creates a server socket and awaits incoming connections.
  • Value type - integer
  • Initial value - 7080
Valid property names for the HTTPSConnector ObjectName:
address
For servers with more than one IP address, this value specifies which address is used for listening on the specified port. By default, this port is used on all IP addresses associated with the server. If specified, only one address can be used.
  • Value type - string
  • Initial value - null
port
The TCP port number on which this Connector creates a server socket and awaits incoming connections.
  • Value type - integer
  • Initial value - 7083
algorithm
The certificate encoding algorithm to be used.
  • Value type - string
  • Initial value -
    • Solaris platform HP-UX platform SunX509 on Solaris and HPUX
    • AIX platform z/OS platform Linux platform Windows platform IbmX509 on other platforms (AIX, z/OS, Linux, Windows)
clientAuth
Set to true if the SSL stack requires a valid certificate chain from the client before accepting a connection. A false value (which is the default) does not require a certificate chain unless the client requests a resource protected by a security constraint that uses CLIENT-CERT authentication.
  • Value type - string
  • Initial value - false
keystoreFile
The path to the keystore file where the server certificate, which is to be loaded, has been stored. By default the http listener will expect a file called .keystore in the home directory of the user who started the broker.
  • Value type - string
  • Initial value - default value (described above)
keystorePass
The password used to access the server certificate from the specified keystore file.
  • Value type - string
  • Initial value - changeit
keystoreType
The type of keystore file to be used for the server certificate.
  • Value type - string
  • Initial value - JKS
sslProtocol
The version of the SSL protocol to use.
  • Value type - string
  • Initial value - SSLv3
ciphers
A comma separated list of the encryption ciphers that may be used. If not specified (the default), then any available cipher may be used.
  • Value type - string
  • Initial value - null
The possible values for keystoreType, sslProtocol, and ciphers are JSSE-implementation specific, and these values should be found in the JSSE provider documentation.

Inter-broker communications parameter values

Valid property names for inter-broker communications are listed below:
brokerInputQueues
Specifies the maximum number of dispatch queues which are to be used when processing messages from an interbroker connection. Increasing the value might increase the rate at which messages can be transmitted across an interbroker connection:
  • Value type - Integer
  • Initial value - 1
brokerInputQueueLength
Defines the maximum number of messages that can be stored in each input queue; the higher the value, the higher the number of input messages that can be stored in each input queue. Note that the higher the value of this property, the larger the amount of memory that the broker requires for each queue:
  • Value type - Integer
  • Initial value - 99
brokerPingInterval
Time in milliseconds between broker initiated ping messages on broker-broker connections. Ping messages ensure that the communications are still open between both sides of the connection, and are generated internally. If the value is 0, the broker does not initiate pings.
  • Value type - Integer
  • Initial value - 5000
clientPingInterval
Time in milliseconds between broker initiated ping messages on broker-client connections. Ping messages ensure that the communications are still open between both sides of the connection, and are generated internally. If the value is 0, the broker does not initiate pings.
  • Value type - Integer
  • Initial value - 30000
clonedPubSubBrokerList
The list of brokers in which <brokername> registers to be a clone.
This list takes the format BrokerName1,BrokerQMName1,BrokerName2,BrokerQMName2. Therefore, if you require to clone three brokers BRKA, BRKB, and BRKC, you must run the following commands:
mqsichangeproperties BRKA -e default -o DynamicSubscriptionEngine
 -n clonedPubSubBrokerList -v \"BRKB,BRKBQM,BRKC,BRKCQM\"
mqsichangeproperties BRKB -e default -o DynamicSubscriptionEngine
 -n clonedPubSubBrokerList -v \"BRKA,BRKAQM,BRKC,BRKCQM\"
mqsichangeproperties BRKC -e default -o DynamicSubscriptionEngine
 -n clonedPubSubBrokerList -v \"BRKA,BRKAQM,BRKB,BRKBQM\"
It is also possible to remove brokers from a cloned environment. For example, if BRKC is to be removed from the clone use the following commands:
mqsichangeproperties BRKA -e default -o DynamicSubscriptionEngine
 -n clonedPubSubBrokerList -v \"-BRKC\"
mqsichangeproperties BRKB -e default -o DynamicSubscriptionEngine
 -n clonedPubSubBrokerList -v \"-BRKC\"
mqsichangeproperties BRKC -e default -o DynamicSubscriptionEngine
 -n clonedPubSubBrokerList -v \"\"

Note the minus symbol in the list for BRKA and BRKB. BRKC does not specify any brokers and is, therefore, not a clone. However, BRKA and BRKB remain clones of each other.

  • Value type - String
  • Initial value - none
enableClientDiscOnQueueOverflow
If true, and if after deleting all possible messages the maxClientQueueSize is still exceeded, the broker disconnects the client.
  • Value type - Boolean
  • Initial value - False
enableQopSecurity
Enables the level of quality of protection for messages.

By default, Quality of Protection is enabled if either the isysQopLevel or sysQopLevel value has been changed from the default value of none.

  • Value type - string
  • Initial value - none
interbrokerHost
Specifies the IP host name of the broker. A single broker configuration can be left to default as null.

mqsichangeproperties <broker> -o DynamicSubscriptionEngine -n interbrokerHost -v <IP host name>

  • Value type - String
  • Initial value - null

If you change the value, the broker must be stopped and restarted. Then you must redeploy the full topology.

interbrokerPort
Port number on which the Broker listens for incoming interbroker connections. If running more than one broker on the same machine, set the interbrokerPort property to a different value for each broker. For example:

mqsichangeproperties <broker> -o DynamicSubscriptionEngine -n interbrokerPort -v <port number>

If you do not set the interbrokerPort value before the topology is deployed, restart the broker.

  • Value type - Integer
  • Initial value -1507

If you change the value, the broker must be stopped and restarted. Then you must redeploy the full topology.

isysQopLevel
Applies to the system and allows brokers only to publish and subscribe.
  • Value type - string
  • Initial value - none
jvmMaxHeapSize
Specifies the size of the Java Virtual Machine (JVM) heap size used with the JVMManager for your Java plug in nodes.

This must be in the range 16 777 216 through 8 589 934 592.

  • Value type - Integer
  • Initial value - 134 217 728
maxBrokerQueueSize
Maximum number of bytes that the broker should queue for transmission to another broker. If the maximum is exceeded, the broker deletes all messages queued to that broker, except for the latest message, high-priority messages, and responses. If 0, the broker does not limit the number of bytes queued to another broker:
  • Value type - Integer
  • Initial value - 1000000
maxClientQueueSize
Maximum number of bytes that the broker should queue for transmission to a client. If the maximum is exceeded, the broker deletes all messages queued to that client, except for the latest message, high-priority messages, and response messages. If 0, the broker does not limit the number of bytes queued to a client.
  • Value type - Integer
  • Initial value - 100000

The value of this property must be greater than, or equal to, the maxMessageSize value.

maxConnections
The maximum number of concurrently connected clients which the broker permits. If this limit is reached, the broker denies new connection requests from clients. If this value is less than 0, the number of clients is unlimited.
  • Value type - Integer
  • Initial value -100
maxHopCount
Specifies that maximum number of multibroker links over which a message is sent, to ensure that messages never loop in a multibroker network. Set this value large enough to ensure that messages can travel the entire multibroker network.
  • Value type - Integer
  • Initial value - 20
maxMessageSize
Maximum allowed message size in bytes. If a message exceeding this maximum size is received from a client, that client is disconnected.
  • Value type - Integer
  • Initial value - 100000

The value of this property must be less than, or equal to, the maxClientQueueSize value.

multicastAddressRangeMax
The highest IP address that the broker can use for its Multicast transmissions.
This should be in the range 224.0.0.2 through 239.255.255.255
  • Value type - String
  • Initial value - 239.255.255.255
multicastAddressRangeMin
The lowest IP address that the broker can use for its Multicast transmissions.
This should be in the range 224.0.0.2 through 239.255.255.255
  • Value type - String
  • Initial value - 224.0.0.2
multicastBackoffTimeMillis
The maximum time, in milliseconds, that a client listens for another's NACKs before sending its own NACK. This value can be in the range 0 through 1000.
  • Value type -Integer
  • Initial value -100
multicastDataPort
The UDP data port through which Multicast packets are sent and received:
  • Value type - Integer
  • Initial value - 34343
multicastEnabled
Indicates whether the topics that are defined in the multicastTopicsConfigFile are delivered Multicast. If the value is true, the topics in the multicastTopicsConfigFile are delivered Multicast.
  • Value type - Boolean
  • Initial value - false
multicastHeartbeatTimeoutSec
Indicates the time in seconds between the arrival of control packets at each client. If a control packet does not arrive within the number, defined as twice the value specified by this property, of seconds of the previous control packet's arrival an error can be suspected.
  • Value type - Integer
  • Initial value -20
multicastLimitTransRate
This property can be used in conjunction with the multicastTransRateLimitKbps property to control network congestion. Possible values are:
Disabled
Multicast data is transmitted as fast as possible
Static
The transmission rate is limited by the value specified in multicastTransRateLimitKbps
Dynamic
The transmission rate can vary throughout the process, but never exceeds the value specified in multicastTransRateLimitKbps
  • Value type - String
  • Initial value - Disabled
multicastMaxKeyAge
Maximum age, in minutes, of a topic encryption key before it must be redefined.
  • Value type - String
  • Initial value - 360
multicastMaxMemoryAllowedKBytes
Maximum memory consumption by client reception buffers, measured in kilobytes.
  • Value type - Integer
  • Initial value - 262144

This parameter is available only if a Pragmatic General Multicast (PGM) protocol is selected.

multicastMCastSocketTTL
The maximum number of hops that a Multicast packet can make between the client and the broker. This value is one more than the maximum number of routers that there can be between the client and the broker.
A value of 1 indicates that the packet reaches all local nodes, but cannot be relayed by routers. The maximum value is 255.
  • Value type - Integer
  • Initial value - 1
multicastMinimalHistoryKBytes
The minimum size, in kilobytes, of a buffer that is allocated as an archive for all transmitted packets. This buffer is shared by all reliable topics, and can be used to recover lost packets. This value can be in the range 1000 through 1,000,000.
  • Value type - Integer
  • Initial value - 60000
multicastMulticastInterface
Indicates what interface to use for Multicast transmissions. You can specify a host name or an IP address. A value of "none" causes the network interface to be operating system dependent.
  • Value type - String
  • Initial value - "none"
Note: If you have only one network card, the default value of none works because the operating system uses the localhost value. However, if you have more than one network card you must set this parameter to ensure that the correct card is used.
multicastNACKAccumulationTimeMillis
The time, in milliseconds, that NACKs are aggregated in the broker, before recovered packets are sent. This value can be in the range 50 through 1000.
  • Value type - Integer
  • Initial value - 300
multicastNACKCheckPeriodMillis
The time, in milliseconds, between periodic checks of reception status and sequence gap detection for NACK building. This value can be in the range 10 thru 1000
  • Value type - Integer
  • Initial value - 500
multicastOverlappingTopicBehavior
This property is used to control the behavior of the broker when a client requests a Multicast subscription for a topic, that is part of a topic hierarchy containing topics, explicitly excluded for Multicast. Possible values are:
Accept
A matching Multicast subscription is accepted and all publications matching the topic, except those that are specifically excluded, are multicast.
Reject
A Multicast subscription to a topic with children that are not enabled for Multicast is rejected by the broker.
Revert
Subscriptions to a topic, or to children of that topic, that are not enabled for Multicast result in unicast transmission.
  • Value type - String
  • Initial value - Accept
multicastPacketBuffers
The number of memory buffers that are created at startup for packet reception. Having a high number of buffers available improves the reception performance and minimizes packet loss at high delivery rates, at the price of increased memory utilization. Each buffer is 33KB and this value can be in the range 1 through 5000.
  • Value type - Integer
  • Initial value - 500
multicastPacketSizeBytes
Indicates the size, in bytes, of Multicast packets. This can be in the range 500 through 32000.
  • Value type - Integer
  • Initial value - 7000
multicastProtocolType
Specifies the protocol type. This must be one of:
  • PTL
  • PGM/IP
  • PGM/UDP
  • Value type - String
  • Initial value - PTL
multicastSocketBufferSizeKbytes
The size, in kilobytes, of the client's socket receiver buffer. Increasing it leads to lower loss rates. This value can be in the range 65 through 10000.
  • Value type - Integer
  • Initial value - 3000
multicastTransRateLimitKbps
Limits the overall transmission rate in Kb (kilobits) per second.
This property is only effective if the multicastLimitTransRate property is not Disabled. The value of this property should not be set higher than the maximum data transmission rate of the system or the network and can be in the range 10 through 1,000,000.
  • Value type - Integer
  • Initial value - 9500
nonDurableSubscriptionEvents
Indicates whether the user requires event messages when a non-durable subscriber is created or deleted. A true value causes an event publication to be created, false indicates that no event publications are made.
  • Value type - Boolean
  • Initial value - False
pingTimeoutMultiple
Number of consecutive clientPngIntervals or brokerPngIntervals without a response that the broker waits before disconnecting a client or broker.
  • Value type - Integer
  • Initial value - 3
statsInterval
The value is the number of milliseconds between statistics publications. If set to 0, statistics publications are not generated. You do not need to restart the broker after changing this property, however it can take the broker up to a minute to start producing statistics after the value is changed.
This should be in the range 0 through 1000
  • Value type - Integer
  • Initial value - 0
Note: This value refers to the publish/subscribe statistics interval only.
sysQopLevel
Applies to the system and allows brokers only to publish.
  • Value type - string
  • Initial value - none

Authorization

Windows platform On Windows platforms, the user ID used to invoke this command must have Administrator authority on the local system.

UNIX platform On UNIX systems, the user ID used to invoke this command must be a member of the mqbrkrs group.

Additionally, the authority required by the broker for the different protocols is as follows:
PGM/IP
The broker requires:
  • Linux platform UNIX platform Root authority on Linux and UNIX systems
  • Windows platform Administrator authority on Windows platforms
  • z/OS platform Root authority (UNIX System Services only) on z/OS
PGM/UDP
The broker requires User authority on all supported platforms.
PTL
The broker requires User authority on all supported platforms.

Examples

Change the clientPingInterval to 200
mqsichangeproperties TEST -o DynamicSubscriptionEngine -n clientPingInterval -v 200 
Enable multicast
mqsichangeproperties TEST -o DynamicSubScriptionEngine -n multicastEnabled -v true
Change the default ssl protocol from SSLv3 to TLS
mqsichangeproperties TEST -b httplistener -o HTTPListener -n sslProtocol -v TLS 
Enable the HTTPS Connector
mqsichangeproperties TEST -b httplistener -o HTTPListener -n enableSSLConnector -v true
Change the location of the JAR files for the IBM SIB JMS client
mqsichangeproperties WBRK6_DEFAULT_BROKER -c JMSProviders -o JMS_Default_IBM_SIB -n jarsURL -v file://D:\SIBClient\Java
Start of changeEnable TFIM identity mapping
mqsichangeproperties WBRK6_DEFAULT_BROKER -c SecurityProfiles -o MyFirstSecurityProfile -n mapping,mappingConfig -v TFIM,http://tfimhost1.ibm.com
End of change
Notices | Trademarks | Downloads | Library | Support | Feedback

Copyright IBM Corporation 1999, 2007Copyright IBM Corporation 1999, 2007. All Rights Reserved.
This build: July 31, 2007 21:33:39

an09140_ This topic's URL is: