MQTT Broker

Overview

The MQTT broker accepts client connections using the MQTT 3.1.1 or MQTT 5.0 protocol over the configured TCP/IP port or WebSockets endpoint. It supports messaging at all quality-of-service levels, retained messages, persistent sessions and authentication via username / password and via client certificates.

Select the “Configuration” node to configure the MQTT broker. The new configuration takes effect once you press the “Apply” toolbar button.

Broker Settings

Configure the following Server Settings.

../_images/mqtt-brokersettings.png
  • Enable MQTT broker service on this computer
    By default, the MQTT broker is disabled. Check the “Enable…” box and press the “Apply” toolbar button to enable the broker after reviewing the remainder of the settings.
  • Enable TCP Server
    When enabled, then the broker will accept connections on the configured TCP/IP port.
  • Enable WebSockets Server
    When enabled, then the broker will accept connections on the configured WebSockets port. Optionally, a relative URL may be specified that clients need to addresss when attempting to connect to the WebSockets server. For example, for a URL “/mqttserver”, local clients would need to address the MQTT broker as “wss://localhost:8883/mqttserver”.
  • Use encryption (TLS)
    If checked then clients must connect over a secure connection.
  • Require client certificates
    If checked, then clients need to provide a client certificate when connecting over a secure connection. By default, all client certificates that are issued by the configured Certificate Authority or that are trusted by the operating system are accepted.
  • Accept trusted authorized client certificates only
    Check this option to only accept trusted client certificates that are specifically listed as an “Authorized” client certificate in the “Client Certificates” settings. Clients that are not on the list will be rejected even if their certificate is trusted.
  • Accept any authorized client certificate
    If a presented client certificate is not trusted (it has neither been issued by the configured certificate authority nor is it trusted by the operating system) then the client is rejected by default. Check the box to by-pass trust checks and accept clients as long as the client certificate matches one of the configured authorized “Client Certificates”.
  • Require client credentials
    If checked then clients must provide a matching username and password before they are allowed to connect.
  • Enable persistent sessions and messages
    MQTT clients may request that the broker maintains session data (such as a list of subscriptions or messages of a higher quality-of-service level) while the client is not connected. Check the box to enable storage of session data. Storage option include

Note

Persistent sessions and messages are held in memory and are cleared when the broker restarts.

Certificate Authority

The MQTT Connector manages its own Certificate Authority. You can create a new certificate (with private key), import your own certificate (which may or may not contain the private key), export the certificate (without private key), and copy the thumbprint of the certificate to reference it elsewhere. Use the toolbar “Add” button to add certificate authorities. Use “Remove” to remove certificate authorities.

Client certificates issued by a configured certificate authority are trusted by default.

If the configured Certificate Authority certificate has a private key then the certificate authority can be used to issue client certificates. The option is disabled if no private key is present.

../_images/mqtt-ca.png

Broker Certificate

The broker certificate is used to encrypt traffic between broker and clients when the “Use TLS” option in the server settings is selected.

By default, a broker certificate issued by the built-in certificate authority is created automatically. Using the toolbar buttons, you have the option to create a new certificate (issued by the configured certificate authority if it has a private key, self-signed otherwise), import your own certificate (this must contain the private key), or export the current certificate (without the private key).

Client Certificates

If option “Require client certificate” or “Accept specifically configured authorized client certificates only” is selected in the server settings then you can add one or more client certificates to authorize or revoke individual client certificates.

Use the “Add” and “Remove” toolbar buttons to manage client certificates and select the added client certificate to be “Authorized” or “Revoked”. The “Revoked” setting takes precedence. Certificates marked as “Authorized” will have an effect on client acceptance only if option “Accept specifically configured authorized client certificates only” is checked.

Topic Access Rules

Topic access rules apply when the broker is configured to require client certificates. In that case, without any topic access rules, clients can neither publish nor subscribe. Add at least one rule to enable access. For example, to grant read and write access to all trusted clients, add the following rule.

../_images/mqtt-topic-access-rules.png

Add other rules to lock down access. When a client attempts to subscribe or publish, then rules are evaluated in the given order until a matching rule is found. If no matching rule is found, then access is denied.

Each rule has the following settings.

  • Name

    Choose any name

  • Topic Access

    The access to be granted by this rule:

    • Deny: Access denied.
    • Read: Client can subscribe.
    • Write: Client can publish.
    • Read / Write: Client can publish and subscribe.
  • Client Match

    This setting determines how client names are evaluated to find a matching rule. Client names are the “Common Name” of the client found in the client’s certificate.

    • All: Any client name matches.
    • Specific: The client name matches only if the following “Client” setting contains the exact client name.
    • Pattern: The following “Client” setting is interpreted as a regular expression and the client name matches if the regular expression matches the client name (see below).
  • Client

    The input field for client matching that contains either nothing (for Client Match “All”), an exact client name (for Client Match “Specific”) or a regular expression (for Client Match “Pattern”). For example, a regular expression “dev.*” matches all client names that start with “dev”.

  • Topic Match

    This setting determines how topic names are evaluated to find a matching rule. Topic names are the MQTT topic names that client wish to publish or subscribe to.

    • All: Any topic name matches.
    • Specific: The topic name matches only if the following “Topic” setting contains an MQTT topic that matches the topic name. The MQTT topic may include wildcards.
    • Pattern: The topic name matches if the following “Topic” setting contains an MQTT topic (that may include wildcards) with client name placeholder substituted by the client name (see below).
  • Topic

    The input field for topic matching that contains either nothing (for Topic Match “All”), an MQTT topic that may include wildcards (for Topic Match “Specific”) or an MQTT topic that may contain a client name place holder in the form “{%client%}”.

Example: There are three MQTT client devices “device1”, “device2”, and “device3” that attempt to publish a temperature value to topics “/device1/temperature”, “/device2/temperature”, and “/device3/temperature”, respectively. Then the following rule would grant Publish access to all of them.

  • Topic Access: Write
  • Client Match: Pattern
  • Client: device.*
  • Topic Match: Pattern
  • Topic: /{%client%}/temperature

Explanation: Topic Access is set to “Write” since publishing should be granted. Client Match is set to “Pattern” so that a regular expression can be specified for “Client” to only match MQTT client names starting with “device”. Topic Match is set to “Pattern” so that a client name placeholder can be specified. Finally, the Topic is set to the MQTT topic that clients wish to publish with the respective client name being substituted to grant access to MQTT topic “/device1/temperature” to MQTT client “device1”, to MQTT topic “/device2/temperature” to MQTT client “device2”, and to MQTT topic “/device3/temperature” to MQTT client “device3”.

Test your topic rules by pressing the “Test” button.

Diagnostics

Select the “Diagnostics” tab and check the selection box to optionally log MQTT messages for fault finding. Note that this may impact performance if many messages are processed.

Status

Status information displayed when selecting the “Status” tab include:

  • Running
    Indicates whether the broker is currently enabled (Yes or No)
  • Clients
    The number of currently connected clients.
  • Sessions
    The current number of client sessions; this may include sessions of disconnected clients.
  • Subscriptions
    The current number of MQTT topic subscriptions across all clients.
  • Messages Received
    The number of MQTT topic messages received since the broker has started.
  • Messages Sent
    The number of MQTT topic messages sent since the broker has started.
  • Messages Retained
    The number of MQTT topic messages that are retained in memory even when clients are disconnected.
  • Connection Requests Accepted
    The number of client connection requests that were accepted.
  • Connection Requests Rejected
    The number of client connection requests that were rejected.
  • Publish Requests Accepted
    The number of client publish requests that were accepted.
  • Publish Requests Rejected
    The number of client publish requests that were rejected.
  • Subscribe Requests Accepted
    The number of client subscribe requests that were accepted.
  • Subscribe Requests Rejected
    The number of client subscribe requests that were rejected.