Eye on Data

# EoD MQTT Broker

# Introduction

The EoD MQTT Broker makes it possible to work with MQTT, where topics can be managed, configured and subscribed to. This document describes the main functionalities and updates that apply to the broker and its settings.

# Configuration of the broker

# Environment variables

The environment variables have to be set for the various environments. The remaining parts of the deployment can be carried out as usual.

# Connecting to the broker

# Security and connection

Connecting to the EoD MQTT Broker requires an MQTTS connection, using a secure connection over SSL. The connection has to be made with the broker.eyeondata.eu certificate. In addition, authentication with a user name and password is required to access the broker. This ensures that only authorised users gain access to the broker and the available topics, with access rights such as read, write and subscribe being checked.

Users are authenticated through Keycloak. A mosquitto plugin linked to the eodProcessor checks whether the supplied user name and password are valid by means of Keycloak, and validates access to the broker based on the configured rights for specific topics.

# EoD JSON format and Sparkplug protocol

The EoD JSON structure is based on the Sparkplug protocol, a standardised approach for communicating data between devices and applications in industrial IoT applications. This format ensures efficient and reliable data transfer within the platforms, with the data neatly structured in JSON and easy to process for monitoring and analysis. The Sparkplug protocol supports both publish-subscribe and request-response communication, which makes it suitable for a variety of applications, such as monitoring devices and processes within the EoD infrastructure.

# Functionality and settings

# 1. ACL settings for broker access

In Mosquitto 1.5 there are four important ACL (Access Control List) settings that govern access to topics. These settings determine whether a client has access to a specific topic for various actions such as reading, writing and subscribing.

# Available ACL settings:

  1. MOSQ_ACL_NONE (0x00)

    • Description: indicates that no access has been granted to the topic in question. This is the default value when no specific rights have been set.

  2. MOSQ_ACL_READ (0x01)

    • Description: governs whether a client can receive a message from a topic (read access).
    • Use: checked when a client subscribes to a topic and a message is published.

  3. MOSQ_ACL_WRITE (0x02)

    • Description: governs whether a client may publish messages to a certain topic (write rights).
    • Use: applied when a client wants to publish a message to a topic.

  4. MOSQ_ACL_SUBSCRIBE (0x04)

    • Description: introduced in Mosquitto 1.5 and used when a client tries to subscribe to a topic. This differs from MOSQ_ACL_READ, because it is specifically about subscribing to a topic.
    • Use: can be used, for example, to prevent a client from subscribing to wildcard topics such as #, while still granting access to read specific topics.

# Difference between MOSQ_ACL_READ and MOSQ_ACL_SUBSCRIBE:

  • MOSQ_ACL_SUBSCRIBE is checked when a client tries to subscribe to a topic, before any messages are sent.
  • MOSQ_ACL_READ is checked when a message is pushed to a topic and determines whether a client may receive that message.

# Example of use:

  • MOSQ_ACL_SUBSCRIBE: blocks a wildcard subscription such as # for all clients, but does allow specific topics, such as topic/1.
  • MOSQ_ACL_READ: allows a client to access messages on specific topics, even if wildcard subscriptions are blocked.

# Available values:

  • MOSQ_ACL_NONE: no access.
  • MOSQ_ACL_READ: read access (receiving messages).
  • MOSQ_ACL_WRITE: write rights (publishing messages).
  • MOSQ_ACL_SUBSCRIBE: subscribing to a topic.

# 2. Settings

# MQTT prefix configuration

The MQTT prefix (for example the Sparkplug version) can be configured per organisation. This means that on a version upgrade from, say, 1.0 to 1.1, only one setting has to be changed.

  • Setting: mqttPrefix='spBv1.0'
  • The default value for the topic per owner is set to //+/.

# Access for users

An option can now be added to give users access to the broker with specific rights and topics.

  • Rights: users can be granted access to the broker based on their rights and the configuration of the allowed topics.
  • IsSuper option: the isSuper option has to be hidden for data connectors. This option may only give access to all topics of an organisation for internal users (such as root, admin, lead, member) when it is activated. Access is limited to the topics of the organisation in question, for example spBv1.0/organisation/#.

# 3. Functionality

# Copy icon for topics

A copy icon is added for topics, so that users can easily copy the name of a topic for use in other configurations.

← Integrations in Eye on Data →