Managing MQTT Messaging

Solace routers support Message Queuing Telemetry Transport (MQTT) clients. MQTT is a lightweight, open protocol designed for Machine-to-Machine (M2M) and Internet of Things (IoT) use cases. The MQTT protocol is an OASIS (Organization for the Advancement of Structured Information Systems) standard.

Managing the MQTT Service

MQTT service on a Solace router can be configured on a per-Message VPN level.

You can configure the following settings for MQTT service.

Setting Listen Ports

You must configure a TCP port number for MQTT clients to use when connecting to a Message VPN. Separate ports can be configured for each transport type that MQTT clients can use. The possible transport types are: plain-text, TLS/SSL, WebSocket, and WebSocket Secure.

To set a listen port for MQTT connections to the given Message VPN, enter the following commands:

solace(configure)# message-vpn <vpn-name>

solace(configure/message-vpn)# service mqtt

solace(configure/message-vpn/service/mqtt)# listen-port <port> [ssl] [web]

Where:

<port> is the port number from 1 to 65535. This port must not be in use for any other service. Note that if the ssl and/or web parameters are not included with the command, the port will use a plain text transport.

[ssl] specifies that the given port uses TLS/SSL encryption.

[web] specifies that the given port uses WebSockets.

[ssl] and [web] together specify that the given port uses WebSockets Secure.

Note:   

  • Enter the command a separate time for each transport type that you want to configure.
  • The no version of this command (no listen-port) removes the currently configured port number.
  • To change a port number, the MQTT connection must be shutdown (refer to Enabling/Disabling MQTT Connections).

Setting the Maximum Number of MQTT Connections

To set the maximum number of MQTT clients that can simultaneously connect to the given Message VPN, enter the following commands:

solace(configure)# message-vpn <vpn-name>

solace(configure/message-vpn)# service mqtt

solace(configure/message-vpn/service/mqtt)# max-connections <value>

Where:

<value> is the maximum number of simultaneous connections permitted

Note:   

  • The no version of this command (no max-connections) resets the value to the maximum limit supported by the router.
  • This parameter can be set to a value that is higher than the maximum number of simultaneous connections permitted by the router, but the connection limit for the router will still be enforced.

Enabling/Disabling MQTT Connections

Within a Message VPN, the MQTT service for the given Message VPN can be enabled or disabled according to the specific transport type that is used. By default, MQTT service is not enabled for a Message VPN.

The following transports can be enabled and disabled for MQTT service:

Plain-Text

  • To enable MQTT connections using TCP plain-text transport for the given Message VPN, enter the following commands:

    solace(configure)# message-vpn <vpn-name>

    solace(configure/message-vpn)# service mqtt

    solace(configure/message-vpn/service/mqtt)# no plain-text shutdown

  • To disable MQTT connections using TCP plain-text transport for the given Message VPN, enter the following commands:

    solace(configure)# message-vpn <vpn-name>

    solace(configure/message-vpn)# service mqtt

    solace(configure/message-vpn/service/mqtt)# plain-text shutdown

    Disabling plain-text connections will disconnect any clients currently connected to the configured plain-text listen port.

SSL

  • To enable MQTT connections using Transport Layer Security (TLS) / Secure Sockets Layer (SSL) transport for the given Message VPN, enter the following commands:

    solace(configure)# message-vpn <vpn-name>

    solace(configure/message-vpn)# service mqtt

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

  • To disable MQTT connections using Transport Layer Security (TLS) / Secure Sockets Layer (SSL) transport for the given Message VPN, enter the following commands:

    solace(configure)# message-vpn <vpn-name>

    solace(configure/message-vpn)# service mqtt

    solace(configure/message-vpn/service/mqtt)# ssl shutdown

    Disabling TLS/SSL connections will disconnect any clients currently connected to the configured TLS/SSL listen port.

WebSocket

  • To enable MQTT connections using Websocket transport for the given Message VPN, enter the following commands:

    solace(configure)# message-vpn <vpn-name>

    solace(configure/message-vpn)# service mqtt

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

  • To disable MQTT connections using Websocket transport for the given Message VPN, enter the following commands:

    solace(configure)# message-vpn <vpn-name>

    solace(configure/message-vpn)# service mqtt

    solace(configure/message-vpn/service/mqtt)# websocket shutdown

    Disabling Websocket connections will disconnect any clients currently connected to the configured Websocket listen port.

WebSocket Secure

  • To enable MQTT connections using Websocket Secure transport for the given Message VPN, enter the following commands:

    solace(configure)# message-vpn <vpn-name>

    solace(configure/message-vpn)# service mqtt

    solace(configure/message-vpn/service/mqtt)# no websocket-secure shutdown

  • To disable MQTT connections using Websocket Secure transport for the given Message VPN, enter the following commands:

    solace(configure)# message-vpn <vpn-name>

    solace(configure/message-vpn)# service mqtt

    solace(configure/message-vpn/service/mqtt)# websocket-secure shutdown

    Disabling Websocket Secure connections will disconnect any clients currently connected to the configured Websocket Secure listen port.

Managing MQTT Sessions

MQTT sessions are virtual objects that represent the MQTT sessions of MQTT clients that connect to a Solace router. On a Solace router, an MQTT session contains important connection information, topic subscriptions, and undelivered QoS 1 messages.

The router identifies connecting MQTT clients by using their Client ID and associated Message VPN.

An MQTT session can be automatically created when an MQTT client connects to a router. (The MQTT session is only created if a client with the same ID and Message VPN does not exist.)

It 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 commands:

    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 commands:

    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.

Note:  The no version of this command (no mqtt-session) deletes the given MQTT session. To delete an MQTT session, it must be shut down.

You can perform the following configuration tasks for a manually-created MQTT session:

Creating Queues

Each MQTT session created for a client can be associated with a queue so that the client’s QoS 1 subscriptions and any undelivered messages attracted by those subscriptions are persisted.

When an MQTT client connects and an MQTT session is automatically created, a queue with an automatically‑generated name is also created for that MQTT session.

However, when an MQTT session is manually created using the CLI, SolAdmin, or SEMP, a queue can also be manually created for the MQTT session—it is not created automatically. A queue created for an MQTT session receives the same default configuration parameters used for non-MQTT queues. These configuration parameters can be modified (the only exception is that the ability to manually add topic subscriptions to the queue is not available). For more information on the available queue configuration parameters, refer to Configuring Queues.

A manually‑created queue for an MQTT session is given an automatically‑generated name.

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

solace(configure/message-vpn/mqtt/mqtt-session)# create queue

Note:  The no version of this command (no queue) removes the provisioned queue from the MQTT session.

Managing MQTT Session Subscriptions

  • To create a topic subscription for the given MQTT session, enter the following MQTT VPN CONFIG 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.

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

For existing MQTT topic subscriptions, 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”).

Note:   

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

Setting an MQTT Session Owner

When an MQTT client connects and an MQTT session is automatically created, the client username of the connecting client is the MQTT session owner. However, 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

Note:   

  • The MQTT session must be shutdown before its owner can be changed.
  • The no version of this command (no owner) removes any configured owner from the MQTT session.

Enabling/Disabling MQTT Sessions

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

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

  • To disable a given MQTT session, enter:

    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.

Requesting Session Information with Special Topics

Some information that is used by Solace Message Format (SMF) clients is not normally available to MQTT clients. MQTT clients can access this information by adding a topic subscription to designated special topics. The client name and reply-to topic provided by these special topics are useful for MQTT clients that would like to make use of subscription managers. 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 router responds by sending the relevant info as a message on the topic to the MQTT client.

Special Topics for Requesting MQTT Session Information

Topic

Router responds with...

$SYS/client/client-name

Client name for the MQTT session

$SYS/client/reply-to

Reply-to destination for the MQTT client