Versions Compared

Old Version 15

changes.mady.by.user Dan Potter

Saved on

compared with

New Version 21

changes.mady.by.user Gill Houghton

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

MQTT Distributor provides a configuration section to the Ignition Gateway .  These can be and this can been seen in the Configure section left side bar of the Ignition Gateway web UI in the left-hand navigation panel - Configure → MQTT Distributor → Settings. 

Once in the Settings section there are two tabs.  Each has a number of configuration options as described below.

General

...

.Image Added

The configuration options for each of the tabs - General and Users - are detailed below.

Anchor
General
General
General

These are the global MQTT Server configuration parameters.  The configuration sections available are Main, Non-TLS Settings, TLS Settings and Advanced.

Anchor
GeneralMain
GeneralMain
General - MainImage Added

  • Enabled
    • This denotes whether or not to enable or disable the MQTT Server functionality of MQTT Distributor

Anchor
GeneralNonTLSSettings
GeneralNonTLSSettings
General - Non-TLS SettingsImage Added

  • Enable TCP

    • This denotes whether or not to enable plain TCP connections. This is enabled by default.

  • Port
    • This is the standard TCP MQTT Server listening port.  By default it is port 1883 and is the MQTT reserved port with IANA
  • Enable Websocket
    • This denotes whether or not to enable plain Websocket connections. This is enabled by default.
  • Websocket Port
    • This is the standard Websocket listening port for the MQTT Server.  By default this is 8090

Anchor
GeneralTLSSettings
GeneralTLSSettings
General - TLS Settings

Tip
For more details on enabling TLS for the MQTT Server see this tutorial: Configuring Secure MQTT Communication.

Image Added

  • Enable TLS

    • Checkbox to enable TLS.

    • Requires that TLS Certificate has been uploaded in Ignition. For more details on enabling TLS for the MQTT Server see this tutorial: Configuring Secure MQTT Communication.

  • Secure MQTT Port
    • This is the TLS enabled MQTT Server listening port if TLS is enabled.  By default it is port 8883 and is a reserved port with IANA
  • Enable Secure Websocket
    • Checkbox to enable Secure Websocket connections for MQTT Server
  • Secure Websocket Port
    • TLS enabled Websocket port for the MQTT Server.  By default this is port 9443

Anchor
GeneralAdvanced
GeneralAdvanced
General - Advanced

Image Added

  • Allow Anonymous MQTT Connections
    • Checkbox to enable anonymous MQTT connections. Not selected by default.
  • Custom Properties
    • Do not use unless instructed to by Cirrus Link personnel.


Anchor
Users
Users
Users

Image Added

There is a single configuration section Main available.

Anchor
UsersMain
UsersMain
Users - MainImage Added

  • Username
    • The username that must be provided in the MQTT Connect packet to MQTT Server. Any client attempting an anonymous connection will be rejected. 
    • By default a user with Username admin is created
  • Password
    • The password that must be provided in the MQTT Connect packet to MQTT Server. Any client attempting an anonymous connection will be rejected. 
    • By default the admin user has a Password changeme created
  • ACLs
    • The comma separated list of Access Control Lists (ACLs) that clients connecting with this username and password are allowed to publish and subscribe on.
    • By default the admin user has an ACL of RW #



MQTT Distributor provides a configuration section to the Ignition Gateway and this can been seen in the left side bar of the Ignition Gateway web UI.Image Added

The configuration options for each of the tabs - General and Users - are detailed below.

Anchor
General
General
General

These are the global MQTT Server configuration parameters.  The configuration sections available are Main, Non-TLS Settings, TLS Settings and Advanced.

Anchor
GeneralMain

...

GeneralMain
General - MainImage Added

  • Enabled
    • This denotes whether or not to enable or disable the MQTT Server functionality of MQTT Distributor

Anchor
GeneralNonTLSSettings
GeneralNonTLSSettings
General - Non-TLS SettingsImage Added

  • Enable TCP

    • This denotes whether or not to enable plain TCP connections. This is enabled by default.

  • Port
    • This is the standard TCP MQTT Server listening port.  By default it is port 1883 and is the MQTT reserved port with IANA
  • Enable Websocket
    • This denotes whether or not to enable plain Websocket connections. This is enabled by default.
  • Websocket Port
    • This is the standard Websocket listening port for the MQTT Server.  By default this is 8090

Anchor
GeneralTLSSettings
GeneralTLSSettings
General - TLS Settings

For more details on enabling TLS for the MQTT Server see this tutorial: TLS Enable MQTT Distributor.Image Added

  • Enable TLS

    • This denotes whether or not to enable TLS connections.  If TLS is used a Java Keystore file must be uploaded to secure the connection.  This is not enabled by default

  • Secure MQTT Port
    • This is the TLS enabled MQTT Server listening port if TLS is enabled.  By default it is port 8883 and is a reserved port with IANA
  • Secure Websocket Port
    • This is the TLS enabled Websocket port for the MQTT Server.  By default this is port 9443
  • Keystore Password
    • This is the Java Keystore password to use if TLS is enabled and a Java Keystore file is provided
  • Java Keystore File
    • This is the Java Keystore file that contains the server certificate and private key files

Anchor
GeneralAdvanced
GeneralAdvanced
General - AdvancedImage Added

  • Allow Anonymous MQTT Connections
    • Checkbox to enable anonymous MQTT connections. Not selected by default.


Anchor
Users
Users
Users

Image Added

There is a single configuration section Main available.

Anchor
UsersMain
UsersMain
Users

...

- MainImage Added

  • Username
    • The username that must be provided in the MQTT Connect packet to MQTT Server. Any client attempting an anonymous connection will be rejected. 

...

    • By default a user with Username admin is created

Image RemovedEach user has the following configuration:

Main

  • Username
    • The username that must be provided in the MQTT Connect packet
  • Password
    • The password that must be provided in the MQTT Connect packet to MQTT Server. Any client attempting an anonymous connection will be rejected. 
    • By default the admin user has a Password changeme created
  • ACLs
    • The comma separated list of Access Control Lists (ACLs) that clients connecting with this username and password are allowed to publish and subscribe on

Image RemovedACL Format

ACLs are defined by the following format: [R|W|RW] topic

where:

R = Read or 'subscribe' privileges

W = Write or 'publish' privileges

RW = Read and Write (subscribe and publish) privileges

topic = The topic or wildcard topic representing the scope of the privilege

Examples:

RW #

  • This allows clients connecting using this username/password to publish and subscribe on any topic

R #

  • This allows clients connecting using this username/password to subscribe on any topic but not publish on any topics

W #

  • This allows clients connecting using this username/password to publish on any topic but not subscribe on any topics

Specific example for Transmission to publish specific Topics only:

Specific Publish ( W ) topics:

  • spBv1.0/GroupID/+/EdgeNodeID/#

Specific Subscribe ( R ) topics:

  • STATE/PrimaryHostID, spBv1.0/GroupID/+/EdgeNodeID/#

Example as entered in Distributor browser portal:

Image Removed

W device_one/temp/#,R state/#

  • This allows clients connecting using this username/password to publish on device_one/temp/# and subscribe on state/# topics

ACLs should be designed with a 'principal of least privilege' model while also considering device management and maintenance.  For example gateways and devices in the field should be limited to publishing and subscribing only on the topics for which they should be expected to.  The same should be true of 'consumer' applications that will be either sending commands to devices in the field or consuming data coming from those devices.

It is also important to note that a username is not limited to a single MQTT client.  A username/password pair could be used for multiple MQTT clients.

If you are new to MQTT topics, the Eclipse Foundation's Paho project provides good information here on the basics of wildcards.

Client Connection Limits

...

    • .
    • By default the admin user has an ACL of RW #