Declared Shared Subscriptions

Declared shared subscriptions allow your HiveMQ MQTT broker to enqueue messages that are published to specific preconfigured shared subscriptions on demand as soon as HiveMQ starts. Unlike a standard shared subscription, messages to a declared shared subscription are enqueued even if there are no connected shared subscribers for the topic.

To ensure that the desired messages are enqueued, the same declared-shared-subscriptions.xml configuration file must be present on each node of your HiveMQ cluster.

If the declared shared subscriptions configuration is not the same on all nodes of the cluster, HiveMQ logs a warning. The presence of inconsistent declared shared subscription configurations does not prevent HiveMQ startup. However, inconsistent configurations lessens your protection form message loss in disaster situations.

The declared shared subscriptions must be provided in a configuration file before the HiveMQ instance starts.
For more information, see Configuration.

Configuration

To configure declared shared subscriptions, add a file called declared-shared-subscriptions.xml to the conf folder in your HiveMQ instance.

For your convenience, an example declared-shared-subscriptions.xml file that you can copy and modify is included in the conf/examples/configuration/declared-shared-subscriptions folder of your HiveMQ installation.

Your declared shared subscriptions must be listed in the XML file as shown in the example.

If HiveMQ detects an invalid or malformed declared-shared-subscriptions.xml configuration, HiveMQ logs an error and your HiveMQ instance does not start.
Example declared shared subscription configuration
<declared-shared-subscriptions>
    <subscription>
        <topic-filter>device/status</topic-filter>
        <share-name>group1</share-name>
    </subscription>
    <subscription>
        <topic-filter>device/update</topic-filter>
        <share-name>group2</share-name>
    </subscription>
    ...
</declared-shared-subscriptions>
It is not possible to make changes to your declared shared subscriptions configuration at runtime.
If you want to change your declared-shared-subscriptions.xml configuration, do a rolling restart of the nodes in your cluster. Thorough protection from potential message loss to the configured declared shared subscriptions is effective once all nodes in the cluster have the same declared-shared-subscriptions.xml configuration files.

Declared Shared Subscription Concepts

If multiple nodes in a cluster crash and the configured replication factor for the cluster is not greater than the number of crashed nodes, session information such as shared subscriptions can be lost. PUBLISH messages that arrive during the break in connection are not enqueued for the lost shared subscription until the client reconnects and recreates the shared subscription.

In the unlikely event that multiple HiveMQ instances fail, session data and subscriptions can be lost for the remaining cluster and result in lost messages. A similar problem can occur during cluster splits if partitions of the cluster do not have all the sessions and subscriptions and therefore cannot deliver all messages.
To avoid possible message loss, you can declare shared subscriptions on demand that are resilient against node outages or cluster splits and available as soon as you start HiveMQ.

Declared Shared Subscription Use Cases

Declared shared subscriptions can be particularly useful in scenarios that rely heavily on shared subscription messages to guarantee the continuity of their business operations. Here are a few use case where declared shared subscriptions can be beneficial:

  • Your business model requires that messages to specific known shared subscriptions must be delivered to clients that subscribe to the shared subscription, even if the client connection is not yet established or lost.

  • The backend systems that ingest MQTT messages must be able to consume all shared messages, even if the backend service is temporarily not available.

  • You need assurance that no messages published to specific known shared subscriptions are lost regardless of cluster splits and disasters.