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. On Solace PubSub+ event brokers, retained messages are preserved in special PubSub+ Cache cache clusters called MQTT retain caches.

Support for MQTT Retained Messages is a Controlled Availability (CA) feature. Please contact Solace to find out if this feature is supported for your use case.

Prerequisites

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

• The appropriate amount of memory must be allocated to the event broker to support retained messages. For more information, see MQTT Retained Message Memory Usage Considerations.
• If the event broker is deployed in a redundant configuration, a pre-shared authentication key must be configured for all event brokers in the deployment. For more information, see Pre-Shared Authentication Keys for Software Event Brokers for the software event broker, or to Pre-Shared Authentication Keys for Appliances for the appliance.
• Appliances that are configured in high-availability (HA) redundant pairs must have their redundancy role configured as primary or backup.For more information, see Assigning the Active/Standby Role.
• The message backbone must be enabled on the event broker. For more information, see Enabling All Messaging Services
• The SMF service must be enabled on the event broker. For more information, see Enabling System-Level SMF Service.
• An MQTT retain cache must be created and enabled on the event broker. For more information, see MQTT Retain Cache Configuration.

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 the maximum number of client connections). 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, see 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, see 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, see Using MQTT.

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, see 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 Retained Message Lifetime

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 PubSub+ Broker 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, see the following sections.

Because PubSub+ Cache is the underlying mechanism used to manage retained messages, in addition to the sections below, see 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 Using MQTT.

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 Using MQTT.

<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 Using MQTT.

<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 Using MQTT.

<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, see the PubSub+ Cache syslog Message section in the Syslog 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