Coreflux CLI Tool Documentation

The Coreflux CLI Tool (coreflux-cli) is a command-line interface for securely managing configurations on the Coreflux MQTT Broker. With this CLI, administrators can modify broker settings, manage users, update passwords, list, alter, add, and remove models, and display user details, ensuring efficient and secure broker management.

Overview

Purpose

The Coreflux CLI Tool simplifies administrative tasks for Coreflux MQTT Broker management, allowing for quick, command-based modifications and configuration reviews.

Main Features

• Broker Configuration: Modify MQTT Broker settings such as ports, IP bindings, and TLS configurations.
• User Management: Add, remove and update user accounts and passwords.
• Model Management: Add, alter, remove and list models for LOT integration in the broker.
• Secure Access: All commands require root password verification for added security.

Installation

The coreflux-cli tool is distributed as an executable file and supports multiple platforms:

• Windows [Link]
• Linux [Link]
• Linux ARM [Link]

Requirements

• Root Authentication: Commands require root password authentication for security
• MQTT Broker Access: Ensure the specified directory path to the MQTT Broker is accessible for the CLI to manage user data

Usage Overview

The CLI tool supports the following commands:

• User Management:

  • add user: Adds a new user to the configuration
  • remove: Removes an existing user from the configuration
  • changepass: Changes the password of an existing user
  • showusers: Displays all users and their passwords in the configuration file

• Broker Configuration:

  • configureBroker: Modify broker settings such as ports, IP bindings, and TLS configurations.

• Model Management:

  • manageModels: Manage LOT models by adding, altering, removing or listing them.

Each command follows the general syntax:

coreflux-cli <command> [options]

Note: For each command, specify the --path option if the Coreflux MQTT Broker directory path is different from the default path.

Commands

Broker Configuration

Modifies the configuration of the Coreflux MQTT Broker, including ports, IP bindings, and TLS certificate details.

Syntax:

coreflux-cli configureBroker [options]

Options:

• -n| or --name: Specify the new name for the broker

  • Example: coreflux-cli configureBroker -n MQTTBrokerNew

• -p or --port: Set the MQTT Communication port

  • Example: coreflux-cli configureBroker -p 8883

• -w or --websocketPort: Set the Websocket Communication port

  • Example: coreflux-cli configureBroker --websocketPort 1421

• -d or --debug: Enable or disable detailed debugging logs

  • Example: coreflux-cli configureBroker -d true

• -a or --allowAnonymous: Allow or disallow anonymous login

  • Example: coreflux-cli configureBroker -a false

• -ip or --bindIpAddress: Set the IP address for MQTT communication binding

  • Example: coreflux-cli configureBroker --bindIpAddress 0.0.0.0

• -c or --certPath: Path to the TLS certificate

  • Example: coreflux-cli configureBroker --certPath "/path/to/certificate.pem"

• -cp or --certPassword: Password for the TLS certificate.

  • Example: coreflux-cli -cp MySecurePassword

• -P or --path: Path to the Coreflux MQTT Broker directory

  • Example: coreflux-cli --path "C:\Users\YourUser\AppData\Roaming\corefluxhub\YourBroker\Coreflux\bin"

User Management

Add User

Creates a new user on the Coreflux MQTT Broker.

Syntax:

coreflux-cli adduser -u <username> -p <password> [-path <path_to_Coreflux_directory>]

Options:

• -u or --username: Specify the new username
• -p or --password: Set a password for the new user
  • Example: coreflux-cli adduser -u newUser -p newPass
• -path or --path : Optional. Specify an alternate path to the Coreflux MQTT Broker directory
  • Example: coreflux-cli adduser -u newUser -p newPass -path C:\Users\YourUser\AppData\Roaming\corefluxhub\YourBroker\Coreflux\bin

Remove User

Deletes a user from the configuration.

Syntax:

coreflux-cli remove -u <username> [-path <path_to_Coreflux_directory>]

Options:

• -u or --username: Username of the user to delete
  • Example: coreflux-cli remove newUser
• -path or --path: Optional. Path to the Coreflux MQTT Broker directory
  • Example: coreflux-cli remove newUser -path C:\Users\YourUser\AppData\Roaming\corefluxhub\YourBroker\Coreflux\bin

Change Password

Updates the password of an existing user.

Syntax:

coreflux-cli changepass -u <username> -password <newpassword> [-p <path_to_Coreflux_directory>]

Options:

• -u or --username: Specify the username
• -p or --password: Set a new password for the user
  • Example: coreflux-cli changepass -u newUser -p anotherNewPass
• -path or --path: Optional. Specify a path to the broker directory
  • Example: coreflux-cli changepass -u newUser -p anotherNewPass -path C:\Users\YourUser\AppData\Roaming\corefluxhub\YourBroker\Coreflux\bin

Show Users

Lists all users and their passwords stored in the configuration.

Syntax:

coreflux-cli showusers [-p <path_to_Coreflux_directory>]

Options:

• -path or --path: Optional. Path to the Coreflux MQTT Broker directory
  • Example: coreflux-cli showusers -path C:\Users\YourUser\AppData\Roaming\corefluxhub\YourBroker\Coreflux\bin

Model Management

Add Model

Adds a new LOT model to the configuration.

Syntax:

coreflux-cli manageModels addModel -c <ModelConfiguration> 

Options:

• -c or --config: Configuration string for the model.
• -p or --path: Optional. Path to the Coreflux directory.
  • Example: coreflux-cli manageModels addModel -c "DEFINE MODEL newModel WITH TOPIC "Coreflux/Topic"

Alter Model

Updates an existing model's configuration.

Syntax:

coreflux-cli manageModels alterModel -n <ModelName> -c <NewModelConfiguration>

Options:

• -n or --name: Name of the model to update.
• -c or --config: New configuration for the model.
• -p or --path: Optional. Path to the Coreflux directory.
  • Example: coreflux-cli manageModels alterModel -n <ExistentModel> -c <NewModelConfiguration>

Remove Model

Deletes a LOT model from the configuration.

Syntax:

coreflux-cli manageModels removeModel -n <ModelName>

Options:

• -n or --name: Name of the model to delete.
• -p or --path: Optional. Path to the Coreflux directory.

List Models

Displays all defined LOT models.

Syntax:

coreflux-cli manageModels listModels

Options:

• -p or --path: Optional. Path to the Coreflux directory.

Additional Details

Root Password Verification

Each command requires root password verification. On command execution, you'll be prompted to enter the root password, which is validated against the root user in the configuration file.

Hidden Password Input

For security, the password prompt for root access hides input characters, showing an asterisk for each character typed.

Model Handling

If a model with incorrect or incomplete syntax is added (e.g., missing double quotes for topics, invalid keywords, or unrecognized configurations), it will still be saved to the configuration file, however, the model will not be recognized or executed by Coreflux Broker. Always verify the syntax of your models before adding or altering them using the LOT documentation.