Managing MQTT Retained Messages

Using MQTT retained messages allows publishing MQTT clients to indicate that a message must be stored for later delivery to subscribing clients when those subscribing clients add subscriptions matching the retained message’s topic. For a given topic, the event broker preserves the last message published on that topic with the retain bit set. In Solace PubSub+ event brokers, retained messages are preserved in special Solace PubSub+ Cache cache clusters called MQTT retain caches.

Prerequisites

Before an event broker can process MQTT retained messages, the following is required:

Limitations

Solace PubSub+ event brokers support MQTT retained messages with the following limitations:

  • Using retained messages on an appliance requires chassis variant CHS-3560AC-06-A or later.
  • Retained messages are supported only for DMR and bridges. MNR is not supported.
  • The event broker's transport mechanism for retained messages is equivalent to QoS 0, although it has the ability to retain QoS 1 messages. This means:

    • QoS 1 messages can be retained even though the event broker did not accept the published message.

    • QoS 1 messages sent by the retain cache to clients may be lost. The following is a list of factors that may contribute to QoS 1 retained messages loss:

      • The burst size of retained messages directed towards the client due to large batches of subscriptions and/or addition of wildcard subscriptions covering a large number of retained messages.
      • The available space remaining on the message-spool and/or the client's QoS 1 queue when a burst of retained messages is queued towards the client.
      • The speed at which the client is able to receive messages. If the client can consume messages faster than the retained messages are queued to the client, little stress is placed on the message-spool and/or queue capacity limits in response to a burst of retained messages.

MQTT Retained Message Memory Usage Considerations

Enabling a PubSub+ event broker to process retained messages consumes additional system memory beyond what is normally required. The amount of additional memory depends on the number and length of topics, and the payload of the retained messages the event broker needs to support.

For any reasonable retained message use case, a PubSub+ software event broker requires a minimum of an extra 2 GB of memory to process retained messages. More memory may be required if the retained messages are large, or if the use case has a very large number of retained messages. Solace recommends that you test and monitor your deployment for memory use and adjust the allocation as necessary.

For example, suppose you are creating a PubSub+ software event broker that would normally require 4 GB of memory (based on scaling tier). If this event broker needs to process retained messages, you must reserve an additional 2 GB of memory (at minimum) on the host to process these messages.

After you've reserved this additional memory, you can allocate it by configuring a maximum shared pool of memory for all retain caches on the event broker. For more information, refer to MQTT Retain Cache Shared Memory Configuration.

MQTT Retained Messages in Redundant Event Broker Deployments

Consider the following when using retained messages in redundant event broker deployments:

  • Before you can use retained messages in redundant deployments, you must set a pre-shared authentication key on each event broker (for more information, refer to Pre-Shared Authentication Keys for Software Event Brokers for the software event broker, or to Pre-Shared Authentication Keys for Appliances for the appliance).
  • Retained messages are not supported in active/active deployments.
  • In any scenario where the primary event broker goes offline, the act of re-establishing the connection to the network (now on the backup), results in re-delivery of all retained messages appropriate to the topic subscriptions for each client. The failover process may also result in the potential for multiple deliveries of retained messages.

MQTT Retain Cache Shared Memory Configuration

You can configure the global maximum allowed memory for all MQTT retain caches on the broker. If the maximum memory is reached, all arriving retained messages are discarded. By default, no memory is allocated for software event brokers, which means all arriving retained messages are discarded. 1024 MB is allocated for appliances.

To configure the global maximum allowed memory for retain caches, enter the following commands:

solace(configure)# mqtt
solace(configure/mqtt)# retain
solace(configure/mqtt/retain)# max-memory <megabytes>

Where:

<megabytes> is the number of megabytes allocated as a shared pool for all retain caches on the broker. The no version of this command returns the value to the default.

MQTT Retain Cache Configuration

MQTT retain caches are configured on a per Message VPN basis. Each retain cache processes all retained messages for the Message VPN.

When you create a retain cache, a number of ancillary PubSub+ Cache objects are also created. For more information, refer to MQTT Retain Cache Ancillary Objects.

On software event brokers, before you can enable a retain cache you must configure the global maximum allowed memory for all retain caches on the event broker. For more information, refer to MQTT Retain Cache Shared Memory Configuration.

You must disable a retain cache before you can remove it. When you remove a retain cache, all retained messages are lost and all in flight and subsequent requests are ignored.

To create an MQTT retain cache, enter the following commands:

solace(configure)# message-vpn <vpn-name>
solace(configure/message-vpn)# mqtt
solace(configure/message-vpn/mqtt)# retain
solace(configure/message-vpn/mqtt/retain)# create cache <retain-cache-name>

To modify an existing retain cache, enter the following command.

solace(configure/message-vpn/mqtt/retain)# cache <cache-name>

To enable a retain cache, enter the following command:

solace(configure/message-vpn/mqtt/retain/cache)# no shutdown

Where:

<cache-name> is the name of the retain cache you want to configure.

The configuration tasks you can perform for an existing retain cache include:

Configuring the Maximum Memory

You can configure the maximum memory that an MQTT retain cache is allowed to consume. If the maximum memory is reached, any arriving retained messages in the corresponding Message VPN are discarded. By default, the maximum memory for each retain cache is bound only by the global pool of memory configured for all retain caches (refer to MQTT Retain Cache Shared Memory Configuration).

To configure the maximum memory for a retain cache, enter the following commands:

solace(configure/message-vpn/mqtt/retain/cache)# max-memory <megabytes>

Where:

<megabytes> is the number of megabytes allocated from the shared pool for this retain cache. Setting this value to 0 prevents the retain cache from becoming operational. When selecting an appropriate size for each retain cache, consider that each cache stores all retained messages across the Message VPN. The no version of this command returns the value to the default.

Configuring the Retained Message Lifetime

You can configure the length of time you want messages to persist in an MQTT retain cache. If a message remains cached for the duration of its lifetime, the retain cache removes the message. By default, no limit is configured.

To configure the retained message lifetime for a retain cache enter the following commands:

solace(configure/message-vpn/mqtt/retain/cache)# message-lifetime <seconds>

Where:

<seconds> is the lifetime of the message in seconds. A lifetime of 0 results in the message being retained indefinitely. The no version of this command returns the value to the default.

Monitoring MQTT Retain Caches

This section provides some examples showing how to monitor MQTT retain caches on your PubSub+ event broker.

There are two ways to do this:

  • The recommended way to monitor retain caches is with the Solace PubSub+ Manager. After logging in, select a Message VPN and navigate to Caches > MQTT Retain Cache.
  • Alternatively, you can monitor retain caches via Solace CLI, for more information, refer to the following sections.

Because PubSub+ Cache is the underlying mechanism used to manage retained messages, in addition to the sections below, refer to Monitoring PubSub+ Cache for general information about monitoring PubSub+ Cache components.

Displaying General MQTT Retain Cache Information

To display general information about an MQTT retain cache, enter the following command:

show message-vpn <message-vpn> mqtt retain cache <cache-name> [detail]

Where:

<message-vpn> is the name of the Message VPN where the retain cache resides.

<cache-name> is the name of the retain cache you want to monitor.

detail displays detailed information about the retain cache, including the names of PubSub+ Cache objects created to support the retain cache. For more information about these objects, see MQTT Retain Cache Ancillary Objects.

Displaying Retain Cache Statistics

To display statistics about an MQTT retain cache, including memory and CPU usage, enter the following command:

show cache-instance <name> message-vpn <vpn-name> remote status

Where:

<name> is the name of the PubSub+ Cache instance created to support the retain cache. For more information, see MQTT Retain Cache Ancillary Objects.

<vpn-name> is the name of the Message VPN where the retain cache resides.

Displaying Retain Cache Topics

To display the list of topics a MQTT retain cache is subscribed to, enter the following command:

show cache-instance <name> message-vpn <vpn-name> remote topics

Where:

<name> is the name of the PubSub+ Cache instance created to support the retain cache. For more information, see MQTT Retain Cache Ancillary Objects.

<vpn-name> is the name of the Message VPN where the retain cache resides.

Clearing Retain Cache Statistics

To clear MQTT retain cache statistics, enter the following command:

clear cache-instance <name> message-vpn <vpn-name> stats

Where:

<name> is the name of the PubSub+ Cache instance created to support the retain cache. For more information, see MQTT Retain Cache Ancillary Objects.

<vpn-name> is the name of the Message VPN where the retain cache resides.

Retain Cache Events

For a complete list of MQTT retain cache events, refer to the PubSub+ Cache syslog Message section in the Event Reference.

Verifying Retain Cache Redundancy

To verify that a retain cache is redundant (for example, to make sure no messages are lost on upgrade), you must verify that the corresponding primary and backup cache instances are synchronized. This must be verified for all message VPNs on which a retain cache has been configured (and is expected to be operational).

To verify that the primary and backup cache instances are synchronized, enter the following command and confirm that each cache instance is operational:

show message-vpn * mqtt retain cache * detail