Setting up a multicast broker

You can set up a multicast broker by either using the Message Brokers Toolkit or by using the Configuration Manager Proxy Java API. This topic describes how to use the Message Brokers Toolkit. For information about how to use the Configuration Manager Proxy (CMP), see Developing applications using the CMP and Class com.ibm.broker.config.proxy.BrokerProxy.MulticastParameterSet.

To make a broker capable of handling multicast requests:

  1. Switch to the Broker Administration perspective.
  2. In the Domains view, expand the appropriate broker domain.
  3. Double-click the Topology item to open the Broker Topology editor.
  4. In the Broker Topology editor, right-click the broker that you want to modify, and select Properties.
  5. In the left panel of the properties window, select Multicast.
  6. Select the Multicast Enabled check box.
  7. Optional: Modify the properties that are listed below; any properties that are not modified take the default value.
    Protocol Type
    The multicast protocol type.

    Valid values are "PTL", "PGM/IP", and "UDP encapsulated PGM". The default value is "PTL".

    See Multicast protocol types for an explanation of these multicast protocol types.

    Min Address
    The lowest IP address that the broker can use for its multicast transmissions.

    This must be in the range 224.0.0.0 through 239.255.255.255. The default value is 239.255.0.0.

    Max Address
    The highest IP address that the broker can use for its multicast transmissions.

    This must be in the range 224.0.0.0 through 239.255.255.255, and must not be lower than the value of Min Address. The default value is 239.255.255.255.

    Data Port
    The UDP data port through which multicast packets are sent and received.

    The default value is 34343.

    Broker Packet Size
    The size, in bytes, of multicast packets.

    This can be in the range 500 through 32000. The default value is 7000.

    Broker Heartbeat Timeout
    The broker sends a control packet periodically, approximately every second, to each client. This packet is used to send various control information, and to keep the heartbeat. The heartbeat timeout value is made known to the clients to help the clients detect a transmitter or network failure. If a control packet does not arrive within a number, defined as twice the value specified by this property, of seconds of the previous control packet's arrival, a client can suspect that there has been a transmitter failure or a network failure.

    The default value is 20.

    Broker Multicast TTL
    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.

    The default value is 1, which means that the multicast packet must remain local to its originator and does not pass through any routers. The maximum value is 255.

    Do not use a value of 0. In some operating systems, this might have the effect of preventing messages from being received, but in other operating systems (for example, Windows 2000, Windows XP, and Linux), a value of 0 does not have this effect.

    Broker Network Interface
    The name of the network interface over which multicast packets are transmitted. This is only relevant when the broker is running on a host with more than one network interface.

    This can be a host name or an IP address. The default is 'None'. If the default value is chosen, the network interface that is used is operating system dependent.

    Overlapping Multicast Topic Behavior
    Choose Accept, Reject, or Revert.

    The Overlapping Multicast Topic Behavior property controls the behavior of the broker when a client requests a multicast subscription for a topic that is part of a topic hierarchy containing topics that are explicitly disabled for multicast.

    For example, consider a topic hierarchy where multicast is a topic with two children, foo that is enabled for multicast, and bar that is not enabled for multicast.

    The three possible settings are:
    Accept
    A matching multicast subscription is accepted and all publications matching the topic, except those that are specifically excluded, are multicast. In the example shown above, a multicast subscription to multicast/# receives messages published on foo over multicast, but does not receive any messages published on bar.
    Reject
    A multicast subscription to a topic with children that are disabled for Multicast is rejected by the broker. Subscriptions to multicast/# are rejected.
    Revert
    Subscriptions to a topic that is disabled for multicast, or has children that are disabled for multicast, result in unicast transmission. A multicast subscription to multicast/# receives messages published on foo and bar, but the messages are sent unicast rather than multicast.

    The default value is Accept.

    Maximum Key Age
    The maximum age, in minutes, of a topic encryption key before it must be redefined.

    The default value is 360.

  8. Optional: Click the + next to Multicast and click Advanced. You can now modify the following additional properties:
    Broker Transmission Rate Limit Activation
    Use the Broker Transmission Rate Limit Activation property in conjunction with Broker Transmission Rate Limit Value to control network congestion. Choose one of the following values from the drop-down menu:
    Disabled
    Multicast data is transmitted as fast as possible. If the rate at which messages are submitted to be multicast exceeds the machine or network limits (that is, the speed of Ethernet or the host CPU becomes the bottleneck), these limits define the maximum transmission rate, and message submissions are stopped until all previously submitted messages have been sent.
    Static
    The transmission rate is limited by the value that is specified in Broker Transmission Rate Limit Value.
    Dynamic
    The limit on the transmission rate can vary during run time, depending on congestion conditions and data losses reported by clients. But the rate never exceeds the Broker Transmission Rate Limit Value.

    The default is Disabled. If you choose Static, you can also choose a value for the property Broker Transmission Rate Limit Value.

    Broker Transmission Rate Limit Value
    This limits the overall transmission rate, in kilobits per second, of multicast packets. This parameter is effective only if the Broker Transmission Rate Limit Activation property is Static. This property must not exceed the capabilities of the machine or network.

    This value can be in the range 10 through 1,000,000.

    Client NACK Back Off Time
    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. The default value is 100.

    Client NACK Check Period
    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 through 1000. The default value is 300.

    Client Packet Buffer Number
    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, but requires increased memory use. Each buffer is 33 KB; having 500 buffers (the default value) uses approximately 15 MB of main memory.

    If memory use is important, try using different values for this property and look at the effect on the overall performance of your application when transmission rates are high.

    This value can be in the range 1 through 5000. The default value is 500.

    Client Socket Buffer Size
    The size, in kilobytes, of the client's socket receiver buffer. Increasing this value reduces the number of data packets that might be dropped by the client receiver.

    This value can be in the range 65 through 10000. The default value is 3000.

    Broker History Cleaning Time
    The time, in seconds, that is defined for cleaning the retransmission buffer.

    This value can be in the range 1 through 20. The default value is 7.

    Note: This property is not used in Version 6.
    Broker Minimal History Size
    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. The default value is 60,000.

    Broker NACK Accumulation Time
    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. The default value is 500.

    Maximum Client Memory Size
    The maximum amount of memory, in kilobytes, that can be used by reception buffers in the client.

    This property is applicable only to PGM multicast protocols. The default value is 262,144 which represents 256 MB.

    Important: Be aware that by increasing the values of properties such as Broker Minimal History Size you increase the amount of memory that is required by the Java Virtual Machine (JVM). This might cause a "JVM Out of Memory" error when a subscription to the broker is attempted for the first time after this change. If this error occurs, either increase your JVM heap size or reduce the value of the property (such as Broker Minimal History Size) that you have just increased.
  9. Click OK.
  10. Restart the broker; you must do this for the changes that you have made to take affect.

Before you can use multicast, you must define some topics as capable of being multicast.

The recommended way of changing the broker's multicast configuration is to use the workbench. However, you can also use the command mqsichangeproperties to change the broker's properties.

The following table relates the properties described above to the corresponding names of the parameters on the mqsichangeproperties command that support multicast. Full details of the mqsichangeproperties command is in mqsichangeproperties command.
Property name mqsichangeproperties parameter
Multicast Enabled multicastEnabled
Protocol Type multicastProtocolType
Min Address multicastAddressRangeMin
Max Address multicastAddressRangeMax
Data Port multicastDataPort
Broker Packet Size multicastPacketSizeBytes
Broker Heartbeat Timeout multicastHeartbeatTimeoutSec
Broker Multicast TTL multicastMCastSocketTTL
Broker Network Interface multicastMulticastInterface
Overlapping Multicast Topic Behavior multicastOverlappingTopicBehavior
Maximum Key Age multicastMaxKeyAge
Broker Transmission Rate Limit Activation multicastLimitTransRate
Broker Transmission Rate Limit Value multicastTransRateLimitKbps
Client NACK Back Off Time multicastBackoffTimeMillis
Client NACK Check Period multicastNackCheckPeriodMillis
Client Packet Buffer Number multicastPacketBuffers
Client Socket Buffer Size multicastSocketBufferSizeKbytes
Broker History Cleaning Time (deprecated in V6) N/A
Broker Minimal History Size multicastMinimalHistoryKBytes
Broker NACK Accumulation Time multicastNackAccumulationTimeMillis
Maximum Client Memory Size, multicastMaxMemoryAllowedKBytes
To enable multicast for the broker WBRK_BROKER use the following command:
   mqsichangeproperties WBRK_BROKER -o DynamicSubscriptionEngine -n multicastEnabled -v true
This enables the broker for multicast, but does not change any other properties of the broker.
To enable multicast for the broker WBRK_BROKER, and to restrict the transmission rate to 50,000 kilobits per second, use the following command:
   mqsichangeproperties WBRK_BROKER -o DynamicSubscriptionEngine -n multicastEnabled,
    multicastLimitTransRate,multicastTransRateLimitKbps -v true,Static,50000
None of the other properties of the broker are changed.

Note the use of commas to separate the properties that are being changed, and also their values.

For the changes to be effective, you must restart the broker.

Warning: Any changes to the broker configuration made using mqsichangeproperties are overwritten with the configuration that is held in the Configuration Manager whenever the broker configuration is deployed.

Related concepts
Multicast publish/subscribe
Multicast protocol types
Related tasks
Modifying broker properties
Making topics multicast
Related reference
Broker Administration perspective
mqsichangeproperties command