Configuration

Coreflux's MQTT Broker is a pivotal component of the platform, ensuring seamless communication between devices and the data hub. This guide will walk you through the configuration parameters of the MQTT Broker, allowing you to tailor it to your specific needs.

Configuration Overview

The configuration for the MQTT Broker is a JSON object that contains various parameters to customize the behavior and security of the broker. Here's a breakdown of each parameter:

Parameter	Description
Name	The name of your DataHub.
Port	The port on which the MQTT broker listens for incoming non-encrypted connections. Default is `1883`.
TlsPort	The port on which the MQTT broker listens for incoming encrypted connections using TLS. Default is `1884`.
WebsocketPortTls	The port for MQTT communication over WebSockets with TLS encryption. Default is `443`.
WebsocketPort	The port for MQTT communication over WebSockets without encryption. Default is `5000`.
FullDebugLog	A boolean value that, when set to `true`, enables detailed logging for debugging purposes.
AnonymousLogin	A boolean value that, when set to `true`, allows clients to connect without providing a username and password.
BindIPForMQTT	The IP address the MQTT broker binds to for non-encrypted MQTT connections. Default is `0.0.0.0`.
BindIPForMQTTwithTls	The IP address the MQTT broker binds to for encrypted MQTT connections using TLS. Default is `0.0.0.0`.
BindIpForWebSockets	The IP address the MQTT broker binds to for MQTT communication over WebSockets without encryption. Default is `0.0.0.0`.
BindIpForWebSocketsTls	The IP address the MQTT broker binds to for MQTT communication over WebSockets with TLS encryption. Default is `0.0.0.0`.
CertificatePath	Specifies the location of the certificate file used for encrypted communication. Paths differ based on OS.
CertificatePassword	The password for the certificate.

Updating the Configuration

Configuration Changes

If you are making changes to the configuration that might impose limitations on running the Coreflux Broker, please ensure to erase the file. Depending on your operating system:

Linux: /usr/share/Coreflux/bin/Anselmo.ralph
Windows: C:\ProgramData\Coreflux\bin\Anselmo.ralph

This step is crucial to prevent potential conflicts or issues arising from previous configurations. Always backup any essential data before making such changes.

To update the MQTT Broker's configuration:

Prepare the desired configuration in a JSON format.
Use a MQTT client to publish the configuration JSON to the $SYS/Coreflux/Config/New topic.

Given the configuration:

{
  "Name": "Coreflux DataHub",
  "Port": 1883,
  "TlsPort": 8883,
  "WebsocketPortTls": 443,
  "WebsocketPort": 5000,
  "FullDebugLog": false,
  "AnonymousLogin": true,
  "BindIPForMQTT": "0.0.0.0",
  "BindIPForMQTTwithTls": "0.0.0.0",
  "BindIpForWebSockets": "0.0.0.0",
  "BindIpForWebSocketsTls": "0.0.0.0",
  "CertificatePath": "D:\\ExampleFolder\\CorefluxCentral\\certificate.pfx",
  "CertificatePassword": "YourPassword"
}

Using a MQTT client, publish this configuration to $SYS/Coreflux/Config/New. Once published, the MQTT Broker will update its configuration based on the provided JSON. Ensure to review the configuration carefully before publishing to avoid any unintended changes.

With this guide, you should be able to understand and modify the MQTT Broker's configuration to suit your needs. Always ensure to maintain the security of your broker by using strong passwords and restricting unnecessary access. By following this guide, you'll have a tailored MQTT Broker configuration and a successfully installed Coreflux platform. Dive deeper into Coreflux's features and embark on your IoT journey. Check how to handle Certificates and Secure Connections

User Management via MQTT

All user management commands can be executed via MQTT by publishing the respective command to the $SYS/Coreflux/Cloud/Command/ or $SYS/Coreflux/Command/ topic. This mechanism aligns with the asset manipulation commands, ensuring a consistent approach to managing both assets and users.

Adding a User

To add a new user to the MQTT Broker:

-addUser <username> <password>

For example, to add a user named "JohnDoe" with the password "secure123":

-addUser JohnDoe secure123

Removing a User

To remove an existing user from the MQTT Broker:

-removeUser <username>

For example, to remove a user named "JohnDoe":

-removeUser JohnDoe

Changing User Password

To change the password of an existing user:

-changeUserPassword <username> <newPassword>

For example, to change the password of user "JohnDoe" to "newSecure123":

-changeUserPassword JohnDoe newSecure123

CyberSecurity Note

When changing passwords or transmitting any sensitive information, always ensure that you are using the broker with TLS (Transport Layer Security). Without TLS, data transmitted between the client and the broker is not encrypted, making it vulnerable to eavesdropping or "man-in-the-middle" attacks. In such scenarios, malicious actors can intercept and read the data being transmitted, including passwords. Always prioritize security by using encrypted connections, especially when dealing with sensitive operations or data.

Modifying User Settings

To change the settings of a user, you can use the following command:

-changeUserSettings <username> <settingToChange> <valueOfSetting>

Here are some examples of how you can use this command to modify different user settings:

Changing Allowed Base Topic: This setting determines the base topic a user is allowed to publish and subscribe to. If left empty, the user can access any topic.

-changeUserSettings JohnDoe AllowedBaseTopic home/livingroom/

In the above command, user "JohnDoe" will only be able to access topics that start with home/livingroom/.

Modifying System Configuration Access: This setting determines whether a user has permissions to modify system configurations.

-changeUserSettings JohnDoe AllowedSystemConfiguration true

With this command, user "JohnDoe" is granted permission to modify system configurations.

Remember, when using the -changeUserSettings command, always ensure that the <settingToChange> parameter matches the exact setting name from the user configuration, and the <valueOfSetting> parameter provides a valid value for that setting.

By understanding and using these commands, you can effectively manage user settings in the MQTT Broker, ensuring that each user has the appropriate permissions and configurations.

User permissions

In the MQTT Broker's configuration, the AllowedSystemConfiguration parameter plays a pivotal role in determining user permissions, especially when it comes to controlling the data hub.

What does `AllowedSystemConfiguration` do?

When set to true for a specific user, the AllowedSystemConfiguration parameter grants the user access to the $SYS topic. This is a special topic that provides insights into the internal workings of the MQTT Broker and allows for advanced control over its operations.

Future Enhancements to AllowedSystemConfiguration

In upcoming versions (>v1.5), the AllowedSystemConfiguration parameter will be enhanced to support specific keys. These keys will provide a more granular control over user permissions, allowing for the creation of admin users with varied capabilities. Admin users could have permissions to:

Install assets
Run or stop assets
Change the data hub's configuration
Overhaul the entire configuration of the data hub

This enhancement aims to provide a more flexible and secure user management system, ensuring that the right users have the right permissions at all times.

AllowedSystemConfiguration is the most comprehensive permission a user can have, granting full control over all broker configurations. For more granular control, consider using the additional user access properties AllowedUserManagement for user-related operations and AllowedAssetManipulation for managing assets.

What does `AllowedUserManagement` do?

Users with the AllowedUserManagement permission can perform the following actions:

Add New Users: Create new user accounts on the MQTT Broker.
Remove Users: Delete existing user accounts from the MQTT Broker.
Modify User Password: Change password for normal (non admin users).

Command Syntax for User Management

The following commands are available for users with AllowedUserManagement permissions:

Adding a User:
```
-addUser <username> <password>
```
Removing a User:
```
-removeUser <username>
```

Changing User Password:

-changeUserPassword <username> <newPassword>

Behavioral Aspects of `AllowedUserManagement`

When a user attempts to subscribe to topics related to user management commands ($SYS/Coreflux/Cloud/Command or $SYS/Coreflux/Command), the broker checks the AllowedUserManagement permission:

Access to User Management Topics: Users with AllowedUserManagement can subscribe to and publish on topics dedicated to user management commands. This ensures that only authorized personnel can manage user accounts, enhancing the system's security.
Restricted Access to System Configuration: Unlike AllowedSystemConfiguration, the AllowedUserManagement permission does not allow users to alter system-wide settings or access the $SYS topic for broader system configurations. This limitation ensures that users can manage user accounts without affecting the system's operational parameters.

Security Considerations

Use of Secure Connections: Ensure that all user management commands are executed over secure connections (TLS/SSL) to prevent unauthorized access and ensure data integrity.
Regular Permission Audits: Regularly review and audit user permissions, especially for those with AllowedUserManagement, AllowedAssetManipulation and AllowedSystemConfiguration, to maintain a secure and efficient environment.

Why is this important?

Having access to the $SYS topic means the user can:

Install Assets: Deploy new assets to the data hub, expanding its capabilities.
Change Settings: Modify the operational settings of the data hub, tailoring it to specific needs.
Update Configuration: Adapt the configuration of the MQTT Broker, ensuring it aligns with the desired operational parameters.
Control Assets: Start, stop, or modify the behavior of assets running within the data hub.

A Word of Caution

Given the extensive control the $SYS topic provides, it's crucial to be judicious about which users have the AllowedSystemConfiguration parameter set to true. Granting this access means the user can make significant changes to the data hub's operation, which could impact its performance or security.

Always ensure that only trusted users have this permission. Regularly review user permissions to ensure that the data hub remains secure and operates as intended.

By understanding the significance of the AllowedSystemConfiguration parameter, you can effectively manage user permissions, ensuring a secure and efficient operation of your MQTT Broker and the broader Coreflux platform.