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]

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]

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. This is the default value.

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

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.

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

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).

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.