EnvisionSCADA contains an MQTT broker. When it is enabled, external MQTT clients connect to EnvisionSCADA and the broker routes published messages to the clients that subscribed to the matching topics.
The broker is standalone. It moves messages between MQTT clients and does not read or write EnvisionSCADA variables, and its users are separate from the EnvisionSCADA users on the Users page. Enabling the broker therefore gives an MQTT client no access to the rest of the system.
The broker is not the same as the MQTT pages in the configuration area. Those pages configure EnvisionSCADA as a client that connects out to an external broker. The MQTT Broker makes EnvisionSCADA the server that other clients connect to. Both can be used at the same time.
The broker is configured on the Parameters page, in the MQTT Broker section. The users and their topic rules are configured with the Edit users button in that same section.
Broker Settings
Set Enable MQTT Broker to start the broker. The remaining settings appear once the broker is enabled.
Changing the port, the TLS settings, or the certificate name restarts the broker, which disconnects the connected clients. Changing Allow anonymous connections or Enforce topic access control, or editing a user or a rule, applies immediately without restarting the broker.
| Setting | Description | Example | Units / Format |
|---|---|---|---|
| Enable MQTT Broker | Starts the broker and makes it accept MQTT clients. | false | Boolean |
| Port | TCP port for unencrypted MQTT connections. | 1883 | Integer (1-65535) |
| Enable TLS (MQTTS) | Adds an encrypted endpoint on a second port. The unencrypted port stays available, so clients can be moved to TLS one at a time. | false | Boolean |
| TLS port | TCP port for encrypted MQTT connections. | 8883 | Integer (1-65535) |
| Certificate name | Subject name of the server certificate in the Windows certificate store under Local Computer / Personal (Docker: the files in /app/certs/tls). | envision-broker | Text |
| Allow anonymous connections | Lets clients connect without a username and password. These clients use the rules of the Anonymous user. | false | Boolean |
| Enforce topic access control | Applies the topic rules of each user. When cleared, an authenticated client may use any topic. | true | Boolean |
No rows match the filter.
MQTT Broker Users
Press Edit users in the MQTT Broker section to manage the accounts that MQTT clients use to connect. The list shows Enable, Name, Username, Rules, and Description for each user.
Press Add to create a user, or the edit icon on a row to change one. The dialog contains the sections General, Credentials, and Topic access control. Press Save to apply the changes.
A client authenticates with the Username and Password of a user. Two users cannot share the same Username. The password is stored as a salted hash and is never shown again after it is saved, so the Password field stays empty when an existing user is opened. Leave it empty to keep the current password, or type a new one to replace it.
A user must be enabled to connect. Disabling or deleting a user, or changing its credentials or rules, disconnects the sessions of that user so it reconnects under the new settings. Other clients stay connected.
| Setting | Description | Example | Units / Format |
|---|---|---|---|
| Enable | Allows this user to connect. A disabled user is refused. | true | Boolean |
| Name | Unique name of the user. Letters, digits, and underscore. | scada_gateway | Text |
| Description | Free text description for documentation purposes. | Site 1 field gateway | Text |
| Username | Username the MQTT client presents when it connects. | gateway1 | Text |
| Password | Password the MQTT client presents when it connects. Stored as a salted hash. | Text |
No rows match the filter.
Topic Access Control
The Topic access control section of a user holds its rules. Each rule allows one topic filter for a direction. The broker refuses any topic that no rule of that user allows, so a new user without rules can connect but cannot use any topic.
A topic filter may use the MQTT wildcards. A plus sign matches exactly one topic level and must fill a whole level. A number sign matches the remaining levels and must be the last level. For example, plant/+/temperature matches plant/line1/temperature, and devices/site1/# matches every topic under devices/site1.
Press Add rule to add a row, and the cross on a row to remove it. Press Export rules to save the rules of the open user to a file, and Import rules to add the rules from a file to the open user. Use these to reuse the same rules on another user instead of typing them again.
| Access | Description |
|---|---|
| Subscribe | The user may subscribe to topics that match the filter and receive messages on them. |
| Publish | The user may publish messages to topics that match the filter. |
| Both | The user may subscribe to and publish on topics that match the filter. |
No rows match the filter.
Anonymous Connections
Set Allow anonymous connections to let clients connect without a username and password.
These clients use the rules of the Anonymous user, which is always present in the user list. The Anonymous user cannot be renamed or deleted and has no username or password. It is supplied disabled and without rules, so allowing anonymous connections on its own still grants nothing. Enable the Anonymous user and give it rules to define what anonymous clients may do.
TLS
Set Enable TLS (MQTTS) to add an encrypted endpoint on the TLS port. Clients then connect to that port over TLS. The unencrypted port keeps listening.
Enter the subject name of the server certificate in Certificate name. The broker reads the certificate from the Windows certificate store under Local Computer / Personal, which is the same store the MQTT client pages use for their client certificate. The certificate needs a private key that the account running EnvisionSCADA can read.
On Docker, place the certificate in the /app/certs/tls folder of the container: a .pfx or .p12 file without password, or a .crt, .pem or .cer file with its private key in the same file or in a .key file with the same name. Mount /app/certs as a volume so the certificate is kept when the container is recreated.
If the certificate cannot be found or has no usable private key, the broker writes a system event and keeps serving the unencrypted port, so the encrypted port is not available until the certificate is corrected.
MQTT Broker Log
The MQTT Broker Log page shows what the broker is doing right now. Open it from the menu, next to System Log and System Metrics. The page updates continuously.
The header shows whether the broker is running, the ports it serves, and whether anonymous connections are allowed or topic access control is not enforced.
Connected clients lists the sessions that are connected at this moment, with the user each session authenticated as, its address, how long it has been connected, and how many messages it sent and received. Press the cross on a row to disconnect that session. The client is dropped immediately and other clients keep running. A client that reconnects on its own appears again.
Live log lists the actions the broker handled. Use the filters to show only connections, subscriptions, publications or refused actions, and the search box to narrow the list further. Press Pause to stop the list from updating while reading it, and Resume to follow the broker again. Press Clear to empty the list, and Export to save the visible rows as a CSV file.
Publications are not listed by default, because a busy broker handles many of them. Set Log publishes to follow them while investigating, and clear it again afterwards. Refused publications are always listed, whether the setting is on or off.
| Column | Description |
|---|---|
| Time | Time the broker handled the action. |
| Event | Broker, Connect, Connected, Disconnected, Subscribe or Publish. |
| Client Id | Client identifier the MQTT client presented when it connected. |
| User | MQTT broker user the session authenticated as. |
| Topic | Topic or topic filter of the action. For connections it holds the client address or the reason the connection was refused. |
| Result | Accepted, Rejected, Allowed, Denied or Info. Refused actions are highlighted. |
No rows match the filter.
The log is held in memory and keeps the number of events set by Broker Log Entries in the MQTT Broker section of the Parameters page (2000 by default). The oldest events are dropped once the limit is reached, and a changed limit applies without restarting the broker. It is emptied when the broker or the server restarts, and each server keeps its own log. Refused actions, together with the broker starting and stopping, are also written to the system log, where they are kept and can be reviewed later on the System Log page.
Redundancy
The broker runs on both the primary and the standby server. Each server runs its own broker and a client connects to one of them. The brokers do not exchange retained messages or client sessions with each other.
The users and their rules are part of the configuration and are replicated from the primary to the standby like the rest of the configuration, so both servers accept the same accounts.
The server certificate is not part of the configuration. Install it in the Windows certificate store of each server (Docker: the /app/certs/tls folder of each container).
Notes
Retained messages and client sessions are held in memory. Restarting the broker or the server clears them.
If the configured port is already used by another program on the same server, the broker writes a system event and does not start. The rest of EnvisionSCADA keeps running.