Managing MQTT Sessions

On a Solace PubSub+ event broker, an MQTT session object holds the state of an MQTT client (that is, it is used to contain a client’s QoS 0 and QoS 1 subscription sets and any undelivered QoS 1 messages). MQTT sessions are identified by their Client ID and associated Message VPN.

You can perform the following configuration tasks for an existing MQTT session:

Creating MQTT Sessions

An MQTT session can be automatically created when an MQTT client connects to an event broker. An MQTT session can also be manually created using the Solace CLI, SolAdmin, or Solace Element Management Protocol (SEMP).

To manually create an MQTT session in the given Message VPN, enter the following command: 

solace(configure/message-vpn/mqtt)# create mqtt-session <client-id> [primary | backup | auto]

To configure an existing MQTT session in the given Message VPN, enter the following command: 

solace(configure/message-vpn/mqtt)# mqtt-session <client-id> [primary | backup | auto]

Where:

<client-id> is a client ID that will match that used by the connecting client. Client IDs can be up to 128 characters long.

primary specifies that the MQTT session belongs to the primary virtual router.

backup specifies that the MQTT session belongs to the backup virtual router.

auto specifies that the MQTT session belongs to either the primary or backup virtual router, depending on the current setting of the redundancy active-standby-role.This is the default value. We recommend using the auto setting except for event brokers configured with an active/active HA redundancy model.

The no version of this command, no mqtt-session, deletes the given MQTT session and all its state, including undelivered messages. To delete an MQTT session, it must be shut down.

Prior to SolOS version 9.13.0, the auto value was not available, and primary was the default virtual router for the MQTT session upon creation. If you are upgrading DR sites to 9.13.0 or later, any MQTT session created as auto on a DR site with new (9.13.0 or later) versions of SolOS will fail when propagated to a DR site with older versions, causing Config-Sync to fall out-of-sync for the MsgVpn of the MQTT Session, because the auto value is not understood by the old loads. For this reason, upgrade all replicated brokers to at least version 9.13.0 before configuring any MQTT sessions as auto.

Setting MQTT Session Owners

When an MQTT client connects and an MQTT session is automatically created, the client username of the connecting client is the MQTT session owner.

When an MQTT session is configured manually using the CLI or SEMP, the MQTT session does not have an assigned owner.

To set the owner of a manually-created MQTT session, enter the following command:

solace(configure/message-vpn/mqtt/mqtt-session)# owner <owner>

Where:

<owner> is a client username that exists in the given Message VPN

The no version of this command, no owner, removes any configures owner from the MQTT session.

The MQTT session must be shutdown before its owner can be changed.

Enabling MQTT Sessions

To enable the given MQTT session, enter the following command:

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

To disable the given MQTT session, enter the following command:

solace(configure/message-vpn/mqtt/mqtt-session)# shutdown

When an MQTT session is disabled, clients attempting to connect to the session will be refused, and any existing connections will be closed. QoS1 subscriptions of a disabled MQTT session will continue to attract messages.

Managing Queues

Each MQTT session created for a client can have an associated queue to store the client’s QoS 1 subscriptions and any undelivered messages attracted by those subscriptions.

A queue for the MQTT session is automatically created when the session is first given a QoS 1 subscription. Once created, the queue’s lifetime is tied to the MQTT session. It will be destroyed only when its session is destroyed.

When created, the initial configuration parameters of the queue are copied from the named copy-from-on-create queue if the following are both true:

  • There is such a named copy-from-on-create queue in the client-profile
  • The MQTT Session was created automatically by the connecting MQTT Client (and not manually by the administrator through CLI/SEMP)

Regardless of where the initial configuration parameters come from, once created, the configuration parameters of this queue can only be changed through the MQTT Session, except for the following:

  • owner—the queue owner always mirrors the session owner
  • access-type—always exclusive
  • permissions—always all read-only
  • shutdown—always no shutdown

Managing MQTT Session Subscriptions

To create a topic subscription for the given MQTT session, enter the following command:

solace(configure/message-vpn/mqtt/mqtt-session)# create subscription <topic>

To configure an existing topic subscription for the given MQTT session, enter the following command:

solace(configure/message-vpn/mqtt/mqtt-session)# subscription <topic>

Where:

<topic> is a topic name that uses MQTT topic syntax.

Although MQTT topic syntax is similar to that used for Solace Message Format (SMF) messages, it is recommended that you refer to Topic Support & Syntax for information on MQTT topic syntax and considerations that should made for topic names to be handled similarly for both MQTT and Solace PubSub+.

For a given MQTT topic subscription in an MQTT session, you can do the following:

Setting QoS Levels for Topic Subscriptions

To set the QoS level of a configured topic subscription for the given MQTT session, enter the following command:

solace(...ge-vpn/mqtt/mqtt-session/subscription)# qos <qos-value>

Where:

<qos-value> is the QoS level to assign to the topic subscription. The valid values are 0 (“deliver at most once”) or 1 (“deliver at least once”).

The no version of this command ,no qos, resets the subscription QoS level to the default value of 0.

Although QoS level of 2 cannot be configured. If a QoS level of 1 is configured, messages with matching topics with a QoS level of 2 will be accepted but treated as QoS 1 messages.

Adding/Removing Multiple Topic Subscriptions

Instead of adding or removing individual topic subscriptions for an MQTT session, you can subscribe to or unsubscribe from multiple topics at once.

To add or remove multiple topic subscriptions for the given MQTT session, enter the following command:

solace(configure/message-vpn/mqtt/mqtt-session)# subscription-list qos <qos-value> [<topic-list>]

Where:

<qos-value> is the QoS level of the topic subscriptions to be added or removed. The valid range is 0 (“deliver at most once”) or 1 (“deliver at least once”). When removing topic subscriptions, the QoS level entered must match the QoS level of the topic subscriptions to be removed.

<topic-list> is a list of topics, separated by spaces, with each topic prefixed by either a “+” (which indicates that the topic subscription will be added) or a “-” (which indicates that the topic subscription will be removed).

solace(configure/message-vpn/mqtt/mqtt-session)# subscription-list qos 0 +temperature +pressure -humidity

Entering the above command will add QoS 0 subscriptions to the topics temperature and pressure, and remove a QoS 0 subscription to the topic humidity if it exists.

Requesting Session Info with Special Topics

An MQTT client may add topic subscriptions to special reserved topics that will provide the client with information about itself and the event broker it has connected to. This information includes the client name assigned to the session and the reply-to topic reserved for the client. These special topic subscriptions will always be QoS 0 and must be exact matches (that is, they must not contain wildcards).

When an MQTT client subscribes to one of these special topics, the event broker responds by sending the relevant info to the MQTT client. The returned strings are not NULL terminated.

Special Topics for Requesting MQTT Session Information
Topic Event broker responds with...

$SYS/client/client-name

The body of the message published to this topic provides the client name for the MQTT session.

$SYS/client/reply-to

Reply-to destination for the MQTT client.

The body of the message published to this topic provides the reply-to topic/destination that is reserved for the client.