mqsichangeproperties command

Supported platforms

Purpose

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

Start the broker using mqsistart, and then issue the command on the machine running the broker.

If you change any value you must stop and restart the broker for the change to take effect.

Syntax

Parameters

brokername
(Required) The name of the broker to modify. This must be the first parameter.
-b httplistener
(Optional) The name of the http listener component.
-e ExecutionGroupLabel
(Optional) Reserved
-o ObjectName
(Required) The name of the object whose properties you want to change. This must be set to one of the values listed below.
-n PropertyName
(Required) The name of the property being changed.
-v PropertyValue
(Required) The supplied PropertyValue is assigned to the property specified by PropertyName.
More than one name and corresponding value can be specified using commas as separators. For example,
-n Name1, Name2 -v Value1, Value2
For Inter-broker communications, the following ObjectName values are 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.
The httplistener ComponentName is required when using the HTTP ObjectName settings.
For compatibility mode with previous versions the following ObjectName value is available:
  • ComIbmXmlParserFactory

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
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
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
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
Start of changejvmMaxHeapSizeEnd of change
Start of changeSpecifies 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
End of change
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

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

On UNIX systems, the user ID used to invoke this command must either be root or must be the same as that specified in the -i parameter of the mqsicreatebroker command. It must also 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:
  • Root authority on Linux and UNIX systems
  • Administrator authority on Windows platforms
  • 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

httplistener component parameter values

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 - SunX509 on Solaris and HPUX, and 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.

Authorization

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

On UNIX systems, the user ID used to invoke this command must either be root or must be the same as that specified in the -i parameter of the mqsicreatebroker command. It must also be a member of the mqbrkrs group.

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 -n sslProtocol -v TLS 
Enable the HTTPS Connector
mqsichangeproperties TEST -b httplistener -o HTTPListener -n enableSSLConnector -v true