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

    • Memory

      Session data is held in memory only. This is the fastest option but session data will be lost when the broker shuts down.

    • Disk (buffered)

      Session data is written to disk utilizing a write buffer. There is a chance that MQTT messages are acknowlegded before data is physically written to disk. If session data must survive broker shutdown then this is the best performing option providing a good balance of performance and reliability.

    • Disk (unbuffered)

      Session data is written to disk immediately and MQTT messages are acknowledged after data is written to disk. This is significantly slower than the buffered write.

    • Disk (unbuffered and fault tolerant)

      Some data is backed up before session data is written to disk immediately. If the write is not completed because the broker or system crashes then data is restored from backup when the broker restarts. This is the slowest option.

Certificate Authority

The MQTT Connector manages its own Certificate Authority or you can import your own. Client certificates issued by the 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

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

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.

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.
  • Retained message storage size
    The file size in megabytes used for storing retained messages (zero unless “Enable persistent sessions and messages” is checked in the server settings).
  • Queued message storage size
    The file size in megabytes used for storing higher level quality-of-service messages for disconnected clients (zero unless “Enable persistent sessions and messages” is checked in the server settings).
  • Persisted session storage size
    The file size in megabytes used for storing topic subscriptions for disconnected clients (zero unless “Enable persistent sessions and messages” is checked in the server settings).