Quick Start

# Preface

This document is a quick start guide for Apusic Distributed Message Queue for MQTT (Apusic Distributed Message Queue, referred to as: ADMQ for MQTT), providing a product introduction, basic steps for installation and deployment, and verification methods.

# Target Audience

This document is intended for IT information business leaders, R&D managers, software project managers, software architects, and operations engineers.

To learn more about ADMQ for MQTT, please refer to the following ADMQ for MQTT product documentation set:

No. Document Description
1 Apusic Distributed Message Queue for MQTT Quick Start Guide Briefly introduces how to quickly get started with ADMQ for MQTT.
2 Apusic Distributed Message Queue for MQTT Installation Guide Details how to install ADMQ for MQTT on various operating systems, as well as service start/stop operations.
3 Apusic Distributed Message Queue for MQTT Message Engine User Manual Details the use, configuration, and management of ADMQ for MQTT message engine features and supporting tools.
4 Apusic Distributed Message Queue for MQTT Console User Manual Details the use and operation of the ADMQ for MQTT console.
5 Apusic Distributed Message Queue for MQTT Development Guide Details how to develop ADMQ for MQTT client applications in various development languages.
6 Apusic Distributed Message Queue for MQTT Migration Guide Details the migration from MQTT Broker to ADMQ for MQTT.
7 Apusic Distributed Message Queue for MQTT Operations Manual Details monitoring, operations, and security hardening for ADMQ for MQTT.
8 Apusic Distributed Message Queue for MQTT Performance Optimization Guide Details performance tuning for ADMQ for MQTT.

# Technical Support

ADMQ for MQTT provides comprehensive technical support services. You can obtain technical support through the following channels:

  • Website: www.apusic.com
  • Phone: 400-855-5800
  • Email: support@apusic.com
  • Kingdee Cloud Community: https://vip.kingdee.com/?productId=73&productLineId=14&lang=zh-CN

When seeking technical support, please provide the following information:

  1. Your name

  2. Company information and contact details

  3. Operating system and its version

  4. Product version number

  5. Detailed information such as logs and screenshots of the exception or error

# Quick Start

# Process Overview

Step 1: Create Authenticator and Authorization Source
            |
            ↓
Step 2: Create User ──┐
                      ├──→ Step 4: Configure ACL Permissions
Step 3: Create Topic ──┘            |
                                    ↓
       Step 5: Send Test Message to Verify Path ──→ Step 6: Integrate Business Code
1
2
3
4
5
6
7
8

# Step 1: Create Authenticator and Authorization Source

MQTT users and ACL rules depend on the authenticator and authorization source respectively. When using an MQTT cluster for the first time, you need to create a built-in database authenticator and authorization source first.

  1. Go to the Authentication & Authorization page (Left menu: Message Middleware → ADMQ MQTT → Authentication & Authorization)
  2. On the Authenticator tab, click the "Add" button
  3. Fill in:
    • Name: built_in_database
    • Authentication Method: Built-in Database
    • Description: MQTT Built-in Database Authenticator
  4. Click "Confirm"
  5. Switch to the Authorization Source tab, click the "Add" button
  6. Fill in:
    • Name: built_in_database
    • Authorization Method: Built-in Database
    • Description: MQTT Built-in Database Authorization Source
  7. Click "Confirm"

Why do this first? Users created later must be bound to an authenticator, and ACL rules must be bound to an authorization source. Without an authenticator and authorization source, the user and permission pages will not have the corresponding source to select.

# Step 2: Create User

Create a dedicated MQTT user for the "Device Reporting System":

  1. Go to the Users page (Left menu: Message Middleware → ADMQ MQTT → Users)
  2. Click the "Add" button
  3. Fill in:
    • Authenticator: Select the created built_in_database authenticator
    • Username: device-service
    • Password: Set a secure password
    • Is Super User: No
    • Description: Device reporting system service account
  4. Click "Confirm"

It is recommended not to enable super user for regular business accounts. Super users bypass all ACL checks.

# Step 3: Create Topic

Topics are the categorization unit for messages in MQTT. Create a topic for device reporting:

  1. Go to the Topics page (Left menu: Message Middleware → ADMQ MQTT → Topics)
  2. Click the "Add" button
  3. Fill in:
    • Topic: sensor/+/temperature
    • Default QoS: 1
    • Retain: No
    • Description: Device temperature reporting topic
  4. Click "Confirm"

Topic Wildcard Explanation: + matches a single level, so sensor/+/temperature can match sensor/living-room/temperature, but cannot match sensor/living-room/bedroom/temperature (the latter requires #).

# Step 4: Configure ACL Permissions

Assign publish/subscribe topic permissions to the user:

  1. Go to the Permissions page (Left menu: Message Middleware → ADMQ MQTT → Permissions)
  2. Ensure built_in_database authorization source is selected at the top
  3. Click the "Add" button
  4. Fill in:
    • Subject Type: Username
    • Username: device-service
    • Permission: Allow
    • Action: All (allow both publish and subscribe)
    • Topic: sensor/#
    • QoS: -1 (unlimited)
    • Retain: -1 (unlimited)
    • Description: Device service can read/write all topics under sensor
  5. Click "Confirm"

Effectiveness Note: ACL rules take effect automatically after saving, no need to click "Sync to MQTT".

# Step 5: Send Test Message to Verify Path

Before integrating business code, use the platform's built-in send function to verify the message path:

  1. Go to the Topics page
  2. Click "Send Message" on the sensor/+/temperature row
  3. Fill in:
    • Payload: {"deviceId":"D001","temperature":24.5}
    • QoS: 1
    • Retain: No
  4. Click "Confirm Send"
  5. Go to the Retained Messages page (if Retain is No, it will not appear here), or go to the Clients page to check if a test client is online

Verification Pass Indicator: Message sent successfully with no permission denial prompt, indicating user authentication and ACL configuration are effective.

# Step 6: Integrate Business Code

Platform resources are now ready. Next, integrate the MQTT client into your application:

Connection Parameters:

Parameter Value How to Obtain
Broker Address Cluster node IP Provided by administrator
Port 1883 (TCP) View from listener management page
Username device-service Created in Step 2
Password Your set password Set in Step 2
ClientID Business-defined Must be globally unique

Producer Example (Java + Eclipse Paho):

import org.eclipse.paho.client.mqttv3.MqttClient;
import org.eclipse.paho.client.mqttv3.MqttMessage;

MqttClient client = new MqttClient("tcp://localhost:1883", "publisher-001");
org.eclipse.paho.client.mqttv3.MqttConnectOptions options = new org.eclipse.paho.client.mqttv3.MqttConnectOptions();
options.setUserName("device-service");
options.setPassword("your-password".toCharArray());
client.connect(options);

MqttMessage message = new MqttMessage("{\"deviceId\":\"D001\",\"temperature\":24.5}".getBytes());
message.setQos(1);
client.publish("sensor/D001/temperature", message);

client.disconnect();
client.close();
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

Consumer Example (Java + Eclipse Paho):

MqttClient client = new MqttClient("tcp://localhost:1883", "subscriber-001");
org.eclipse.paho.client.mqttv3.MqttConnectOptions options = new org.eclipse.paho.client.mqttv3.MqttConnectOptions();
options.setUserName("device-service");
options.setPassword("your-password".toCharArray());
client.connect(options);

client.subscribe("sensor/+/temperature", 1);
client.setCallback(new org.eclipse.paho.client.mqttv3.MqttCallback() {
    public void messageArrived(String topic, MqttMessage message) {
        System.out.println("Message received: " + topic + " -> " + new String(message.getPayload()));
    }
    public void connectionLost(Throwable cause) {}
    public void deliveryComplete(org.eclipse.paho.client.mqttv3.IMqttDeliveryToken token) {}
});
1
2
3
4
5
6
7
8
9
10
11
12
13
14

# Subsequent Operations

After business integration, daily operations can be managed through the following features:

Operations Scenario Navigation Path Description
View Online Clients Client Management View client ID, username, IP, connection time
Force Offline Abnormal Client Client row → "Disconnect" Immediately disconnect the specified connection
View Message Backlog Topic Monitoring / Monitoring Dashboard Monitor inflow/outflow/discard counts
Troubleshoot Consumption Delay Slow Subscription Management View subscriptions with long message delivery time
Manage Retained Messages Retained Message Management View or delete unwanted retained messages
View System Alerts Monitoring & Statistics → Alerts View alerts for CPU/memory/connection count anomalies
Adjust Authentication/Authorization Authentication & Authorization Modify authenticators, authorization sources, ACL rules

# Summary

After completing the above 6 steps, you have:

  • ✅ Created MQTT built-in database authenticator and authorization source
  • ✅ Created a dedicated MQTT business user
  • ✅ Created a device reporting topic
  • ✅ Configured fine-grained ACL access control
  • ✅ Verified the correctness of the message path
  • ✅ Integrated configuration parameters into business code

This is the minimum viable closed loop for using MQTT. Based on business needs, you can further extend with more topics, users, ACL rules, or configure listeners and system parameters for richer functionality.

For detailed descriptions of each feature, please refer to other documents in the same directory.

编辑页面 (opens new window)
#Quick Start Guide

← Console User Manual→