EMQX基础功能

目录

1、Dashboard

1.1 查看和配置Dashboard

1.2 Dashboard界面

1.2.1 ADMIN

1.2.2 MONITORING

1.2.3 RULE ENGINE

1.2.4 MANAGEMENT

1.2.5 TOOLS

2、认证

2.1 简介

2.1.1 认证方式

2.1.2 EMQX身份认证流程

2.2 Username 认证

2.2.1 预设认证数据

2.2.2 HTTP API 管理认证数据

2.2.3 MQTTX客户端验证

2.3 Client ID 认证

2.3.1 预设认证数据

2.3.2 HTTP API 管理认证数据

2.3.3 MQTTX客户端验证

2.4 HTTP认证

2.4.1 认证原理

2.4.2 HTTP 请求信息

2.4.3 认证请求

2.4.4 认证服务开发

2.4.5 MQTTX客户端验证

3、客户端SDK

3.1 Eclipse Paho Java​

3.1.1 Paho介绍

3.1.2 Paho实现消息收发

3.2 MQTT.js

3.2.1 API列表​

3.2.2 MQTT.js实现消息收发

4. 日志与追踪

4.1 控制日志输出

4.2 日志级别

4.3 日志文件和日志滚动

4.4 针对日志级别输出日志文件

4.5 日志格式

4.6 日志级别和log handlers

4.7 运行时修改日志级别

4.8 日志追踪

---

1、Dashboard

EMQX 提供了 Dashboard 以方便用户管理设备与监控相关指标。通过 Dashboard可以查看服务器基本信息、负载情况和统计数据，可以查看某个客户端的连接状态等信息甚至断开其连接，也可以动态加载和卸载指定插件。除此之外，EMQ X Dashboard 还提供了规则引擎的可视化操作界面，同时集成了一个简易的 MQTT 客户端工具供用户测试使用。

EMQX Dashboard 功能由 emqx-dashboard 插件实现，该插件默认处于启用状态，它将在 EMQX 启动时自 动加载。如果你希望禁用 Dashboard 功能，你可以将 data/loaded_plugins 中的 {emqx_dashboard, true} 修改为 {emqx_dashboard, false} 。

1.1 查看和配置Dashboard

EMQ X Dashboard 是一个 Web 应用程序，你可以直接通过浏览器来访问它，无需安装任何其他软件。 当 EMQX 成功运行在你的本地计算机上且 EMQX Dashboard 被默认启用时，通过访问 http://localhost:18083 来查看Dashboard，默认用户名是 admin ，密码是 public 。

 

如果EMQX是基于docker容器部署的，可以在容器中的 etc/plugins/emqx_dashboard.conf 中查看或修改 EMQ X Dashboard 的配置。 EMQ X Dashboard 配置项可以分为默认用户与监听器两个部分：

默认用户

EMQ X Dashboard 可以配置多个用户，但在配置文件中仅支持配置默认用户。 需要注意的是，一旦您通过 Dashboard 修改了默认用户的密码，则默认用户的相关信息将以您在 Dashboard 上的最新改动为准，配置文件中的默认用户配置将被忽略。

监听器

EMQ X Dashboard 支持 HTTP 和 HTTPS 两种 Listener，但默认只启用了监听端口为 18083 的 HTTP Listener。

1.2 Dashboard界面

为了使用户在操作和浏览中可以快速地定位和切换当前位置，EMQ X Dashboard 采用了侧边导航的模式，默 认情况下 Dashboard 包含以下一级导航项目：

最新版本EMQ X Broker的Dashboard界面布局略有不同，增加了些导航，但基本都差不多

 

 

1.2.1 ADMIN

Users

您可以在 Users 页面查看和管理能够访问和操作 Dashboard 的用户：

 

Settings

目前 EMQ X Dashboard 仅支持修改主题和语言两种设置：

 

1.2.2 MONITORING

EMQ X Dashboard 提供了非常丰富的数据监控项目，完整地覆盖了服务端与客户端，这些信息都将在MONITORING 下的页面中被合理地展示给用户。

Overview

Overview 作为 Dashboard 的默认展示页面，提供了 EMQ X 当前节点的详细信息和集群其他节点的关键信息，以帮助用户快速掌握每个节点的状态。

Clients

Clients 页面提供了连接到指定节点的客户端列表，同时支持通过 Client ID 直接搜索客户端。除了查看客户端的基本信息，您还可以点击每条记录右侧的 Kick Out 按钮踢掉该客户端，注意此操作将断开客户端连接并终结其会话。

Clients 页面使用快照的方式来展示客户端列表，因此当客户端状态发生变化时页面并不会自动刷新，需要您手动刷新浏览器来获取最新客户端数据。

 

 如果你无法在客户端列表获取到你需要的信息，你可以单击 Client ID 来查看客户端的详细信息。

 

 我们将客户端详情中的各个字段分为了 连接，会话 和 指标 三类，以下为各字段的说明：

 连接

 会话

 指标

在客户端详情的 Subscriptions 标签页中，您可以查看当前客户端的订阅信息，以及新建或取消订阅：

Topics

展示系统所有的Topic情况

 

Subscriptions

Subscriptions 页面提供了指定节点下的所有订阅信息，并且支持用户通过 Client ID 查询指定客户端的所有订阅。

 

1.2.3 RULE ENGINE

用 EMQ X 的规则引擎可以灵活地处理消息和事件，例如将消息转换成指定格式后存入数据库表或者重新发送到消息队列等等。为了方便用户更好地使用规则引擎，EMQ X Dashboard 提供了相应的可视化操作页面，您可以 点击 RULE ENGINE 导航项目来访问这些页面。

鉴于规则引擎的相关概念比较复杂， 涉及到的操作可能会占据相当大的篇幅，后面会单独写一篇博客来介绍。

 

1.2.4 MANAGEMENT

目前 EMQ X Dashboard 的 MANAGEMENT 导航项目下主要包括扩展插件 的监控管理页面和用于 HTTP API 认证的 AppID 与 AppSerect 的管理页面。

 

Plugins

Plugins 页面列举了 EMQ X 能够发现的所有插件，包括 EMQ X 官方插件与您遵循 EMQ X 官方标准自行开发的插件，您可以在此页面查看插件当前的运行状态以及随时启停插件。

 

可以看到，除了emqx-dashboard以外， EMQ X 还将默认启动 emqx-rule-engine等4个插件。

Applications

Applications 页面列举了当前已创建的应用，您可以在此页面进行诸如创建应用、临时禁用或启动某个应用的访问权限等操作。EMQ X 会创建一个 AppID 为 admin ，AppSecret 为 publish 的默认应用方便用户首次访问：

 

您可以点击 Application 页面右上角的 New App 按钮来创建一个新的应用，其中 AppID 与 AppSecret 是必 选项。创建完成后您可以点击 View 按钮来查看应用详情，AppSecret 也会在详情中显示。以下是相关字段的说明：

1.2.5 TOOLS

目前 EMQ X Dashboard 的 TOOLS 导航项目下主要包括 WebSocket 客户端工具页面以及 HTTP API 速查页面。

Websocket

Websocket 页面为您提供了一个简易但有效的 WebSocket 客户端工具，它包含了连接、订阅和发布功能，同时还能查看自己发送和接收的报文数据，我们期望它可以帮助您快速地完成某些场景或功能的测试验证：

HTTP API

HTTP API 页面列举了 EMQ X 目前支持的所有 HTTP API 及其说明：

 

2、认证

2.1 简介

身份认证是大多数应用的重要组成部分，MQTT 协议支持用户名密码认证，启用身份认证能有效阻止非法客户端的连接。

EMQ X 中的认证指的是当一个客户端连接到 EMQ X 的时候，通过服务器端的配置来控制客户端连接服务器的权限。

EMQ X 的认证支持包括两个层面：

1. MQTT 协议本身在 CONNECT 报文中指定用户名和密码，EMQ X 以插件形式支持基于 Username、 ClientID、HTTP、JWT、LDAP 及各类数据库如 MongoDB、MySQL、PostgreSQL、Redis 等多种形式的认证。

2. 在传输层上，TLS 可以保证使用客户端证书的客户端到服务器的身份验证，并确保服务器向客户端验证服务器证书。也支持基于 PSK 的 TLS/DTLS 认证。

2.1.1 认证方式

EMQ X 支持使用内置数据源（文件、内置数据库）、JWT、外部主流数据库和自定义 HTTP API 作为身份认证数据源。

连接数据源、进行认证逻辑通过插件实现的，每个插件对应一种认证方式，使用前需要启用相应的插件。

客户端连接时插件通过检查其 username/clientid 和 password 是否与指定数据源的信息一致来实现对客户端的身份认证。

EMQ X 支持的认证方式：

内置数据源

Username 认证

Cliend ID 认证

使用配置文件与 EMQ X 内置数据库提供认证数据源，通过 HTTP API 进行管理，足够简单轻量。

外部数据库

LDAP 认证

MySQL 认证

PostgreSQL 认证

Redis 认证

MongoDB 认证

外部数据库可以存储大量数据，同时方便与外部设备管理系统集成。

其他

HTTP 认证

JWT 认证

JWT 认证可以批量签发认证信息，HTTP 认证能够实现复杂的认证鉴权逻辑。

更改插件配置后需要重启插件才能生效，部分认证鉴权插件包含 ACL 功能

认证结果

任何一种认证方式最终都会返回一个结果：

认证成功：经过比对客户端认证成功

认证失败：经过比对客户端认证失败，数据源中密码与当前密码不一致忽略认证（ignore）：当前认证方式中未查找到认证数据，无法显式判断结果是成功还是失败，交由认证链下一认证方式或匿名认证来判断

匿名认证

EMQ X 默认配置中启用了匿名认证，任何客户端都能接入 EMQ X。没有启用认证插件或认证插件没有显式允许/拒绝（ignore）连接请求时，EMQ X 将根据匿名认证启用情况决定是否允许客户端连接。

配置匿名认证开关：

# 进入 etc/emqx.conf 
## Value: true | false 
allow_anonymous = true

生产环境中请禁用匿名认证。

注意：我们需要进入到容器内部修改该配置，然后重启EMQ X服务

密码加盐规则与哈希方法

EMQ X 多数认证插件中可以启用哈希方法，数据源中仅保存密码密文，保证数据安全。

启用哈希方法时，用户可以为每个客户端都指定一个 salt（盐）并配置加盐规则，数据库中存储的密码是按照。加盐规则与哈希方法处理后的密文。

以 MySQL 认证为例：

加盐规则与哈希方法配置：

# 进入etc/plugins/emqx_auth_mysql.conf 

## 不加盐，仅做哈希处理 
auth.mysql.password_hash = sha256 

## salt 前缀：使用 sha256 加密 salt + 密码 拼接的字符串 auth.mysql.password_hash = salt,sha256 

## salt 后缀：使用 sha256 加密 密码 + salt 拼接的字符串 auth.mysql.password_hash = sha256,salt 

## pbkdf2 with macfun iterations dklen 
## macfun: md4, md5, ripemd160, sha, sha224, sha256, sha384, sha512 
## auth.mysql.password_hash = pbkdf2,sha256,1000,20

如何生成认证信息

1. 为每个客户端分用户名、Client ID、密码以及 salt（盐）等信息

2. 使用与 MySQL 认证相同加盐规则与哈希方法处理客户端信息得到密文

3. 将客户端信息写入数据库，客户端的密码应当为密文信息

2.1.2 EMQX身份认证流程

1. 根据配置的认证 SQL 结合客户端传入的信息，查询出密码（密文）和 salt（盐）等认证数据，没有查询结果时，认证将终止并返回 ignore 结果 。

2. 根据配置的加盐规则与哈希方法计算得到密文，没有启用哈希方法则跳过此步 。

3. 将数据库中存储的密文与当前客户端计算的到的密文进行比对，比对成功则认证通过，否则认证失败 。

写入数据的加盐规则、哈希方法与对应插件的配置一致时认证才能正常进行。更改哈希方法会造成现有认证数据失效。

认证链

当同时启用多个认证方式时，EMQ X 将按照插件开启先后顺序进行链式认证：

• 一旦认证成功，终止认证链并允许客户端接入

• 一旦认证失败，终止认证链并禁止客户端接入

• 直到最后一个认证方式仍未通过，根据匿名认证配置判定

  • 匿名认证开启时，允许客户端接入

  • 匿名认证关闭时，禁止客户端接入

 

同时只启用一个认证插件可以提高客户端身份认证效率。

2.2 Username 认证

Username 认证使用配置文件预设客户端用户名与密码，支持通过 HTTP API 管理认证数据。

Username 认证不依赖外部数据源，使用上足够简单轻量。使用这种认证方式前需要开启插件，我们可以在Dashboard里找到这个插件并开启。

插件：

emqx_auth_username

 

哈希方法

Username 认证默认使用 sha256 进行密码哈希加密，可在 etc/plugins/emqx_auth_username.conf 中更改：

配置哈希方法后，新增的预设认证数据与通过 HTTP API 添加的认证数据将以哈希密文存储在 EMQ X 内置数据库中。

2.2.1 预设认证数据

可以通过配置文件预设认证数据，编辑配置文件：etc/plugins/emqx_auth_username.conf

插件启动时将读取预设认证数据并加载到 EMQ X 内置数据库中，节点上的认证数据会在此阶段同步至集群中。

预设认证数据在配置文件中使用了明文密码，出于安全性与可维护性考虑应当避免使用该功能。

2.2.2 HTTP API 管理认证数据

EMQ X提供了对应的HTTP API用以维护内置数据源中的认证信息，我们可以添加/查看/取消/更改认证数据 。

我们通过VSCode来访问EMQ X的API /auth_username 完成认证数据的相关操作

打开VSCode下载插件

接下来我们就可以区VSCode去编写代码。

创建一个html文件

 1、查看已有认证用户数据： GET api/v4/auth_username

@hostname = 192.168.200.129 
@port=18083 
@contentType=application/json 
@userName=admin 
@password=public 
#############查看已有用户认证数据############## 
GET http://{{hostname}}:{{port}}/api/v4/auth_username HTTP/1.1 Content-Type: {{contentType}} 
Authorization: Basic {{userName}}:{{password}}

返回

 2、添加认证数据API 定义： POST api/v4/auth_username{ "username": "emqx_u", "password": "emqx_p"}

########添加用户认证数据############## 
POST http://{{hostname}}:{{port}}/api/v4/auth_username HTTP/1.1
Content-Type: {{contentType}}
Authorization: Basic {{userName}}:{{password}}

 { "username": "user", "password": "123456" }

返回

3、更改指定用户名的密码API 定义： PUT api/v4/auth_username/${username}{ "password": "emqx_new_p"}

指定用户名，传递新密码进行更改，再次连接时需要使用新密码进行连接：

###########更改指定用户名的密码############# 
PUT http://{{hostname}}:{{port}}/api/v4/auth_username/user HTTP/1.1 
Content-Type: {{contentType}} 
Authorization: Basic {{userName}}:{{password}} 
 
{ "password": "user" }

返回

4、查看指定用户名信息API 定义： GET api/v4/auth_username/${username}

指定用户名，查看相关用户名、密码信息，注意此处返回的密码是使用配置文件指定哈希方式加密后的密码：

###########查看指定用户名信息############# 
GET http://{{hostname}}:{{port}}/api/v4/auth_username/user HTTP/1.1 
Content-Type: {{contentType}} 
Authorization: Basic {{userName}}:{{password}}

返回

 

5：删除认证数据API 定义： DELETE api/v4/auth_username/${username}

用以删除指定认证数据

###########删除指定的用户信息############# 
DELETE http://{{hostname}}:{{port}}/api/v4/auth_username/user HTTP/1.1 
Content-Type: {{contentType}} 
Authorization: Basic {{userName}}:{{password}}

返回

2.2.3 MQTTX客户端验证

使用mqtt客户端工具验证使用username连接登录的功能。从 MQTT X: Cross-platform MQTT 5.0 Desktop Client 这个地址下载对应操作系统的mqtt客户端工具。

 1、新建连接，参数配置如下

在对应的输入框内输入username和password，clientId这里目前可以随便输入(因为基于clientId的认证功能还没有启用)，之后点连接，连接成功。用户名和密码如果输入错误的话是连接不成功的。

2、再次创建一个客户端连接，可作为消息的订阅者，上一个连接作为发布者，如下

 

 3、订阅者添加订阅

 

 订阅完成后

 

 4、上一个客户端连接作为消息的发布者来进行消息的发布

 

 5、查看订阅者是否已经接收到消息

2.3 Client ID 认证

Client ID 认证使用配置文件预设客户端Client ID 与密码，支持通过 HTTP API 管理认证数据。

Client ID 认证不依赖外部数据源，使用上足够简单轻量，使用该种认证方式时需要开启 emqx_auth_clientid 插件，直接在DashBoard中开启即可。

 

哈希方法

Client ID 认证默认使用 sha256 进行密码哈希加密，可在etc/plugins/emqx_auth_clientid.conf 中更改：

配置哈希方法后，新增的预设认证数据与通过 HTTP API 添加的认证数据将以哈希密文存储在 EMQ X 内置数据库中。

2.3.1 预设认证数据

可以通过配置文件预设认证数据，编辑配置文件： etc/plugins/emqx_auth_clientid.conf

 

插件启动时将读取预设认证数据并加载到 EMQ X 内置数据库中，节点上的认证数据会在此阶段同步至集群中。

预设认证数据在配置文件中使用了明文密码，出于安全性与可维护性考虑应当避免使用该功能。

2.3.2 HTTP API 管理认证数据

我们使用VSCode来通过EMQ X的API来添加和查看Client ID的认证数据。

1、添加认证数据API 定义： POST api/v4/auth_clientid{ "clientid": "emqx_c", "password": "emqx_p"}

####添加clientId和密码##### 
POST http://{{hostname}}:{{port}}/api/v4/auth_clientid HTTP/1.1 
Content-Type: {{contentType}} 
Authorization: Basic {{userName}}:{{password}} 

{ "clientid": "emq-client1", "password": "123456" }

返回

 2、查看已经添加的认证数据API 定义： GET api/v4/auth_clientid

#############获取所有详细信息######## 
GET http://{{hostname}}:{{port}}/api/v4/auth_clientid HTTP/1.1 
Content-Type: {{contentType}} 
Authorization: Basic {{userName}}:{{password}}

返回

 3：更改指定 Client ID 的密码API 定义： PUT api/v4/auth_clientid/${clientid}{ "password": "emqx_new_p"} 指定 Client ID，传递新密码进行更改，再次连接时需要使用新密码进行连接：

#############更改指定 Client ID 的密码######## 
PUT http://{{hostname}}:{{port}}/api/v4/auth_clientid/emq-client1 HTTP/1.1 
Content-Type: {{contentType}} 
Authorization: Basic {{userName}}:{{password}} 

{ "password": "654321" }

返回

2.3.3 MQTTX客户端验证

使用mqtt客户端工具验证使用Client ID连接登录的功能

 

此时用户名字段需要输入一个，但是可以随便填写！

2.4 HTTP认证

HTTP 认证使用外部自建 HTTP 应用认证数据源，根据 HTTP API 返回的数据判定认证结果，能够实现复杂的认证鉴权逻辑。启用该功能需要将 emqx_auth_http 插件启用，并且修改该插件的配置文件，在里面指定HTTP认证接口的url。 emqx_auth_http 插件同时还包含了ACL的功能，我们暂时还用不上，通过注释将其禁用。

1：在Dashboard中中开启 emqx_auth_http 插件，同时为了避免误判我们可以停止通过username，clientID 进行认证的插件 emqx_auth_clientid ， emqx_auth_username

2.4.1 认证原理

EMQ X 在设备连接事件中使用当前客户端相关信息作为参数，向用户自定义的认证服务发起请求查询权限， 通过返回的 HTTP 响应状态码 (HTTP statusCode) 来处理认证请求。

1. 认证失败：API 返回 4xx 状态码

2. 认证成功：API 返回 200 状态码

3. 忽略认证：API 返回 200 状态码且消息体 ignore

2.4.2 HTTP 请求信息

HTTP API 基础请求信息，配置证书、请求头与重试规则。

 

加盐规则与哈希方法

HTTP 在请求中传递明文密码，加盐规则与哈希方法取决于 HTTP 应用。

2.4.3 认证请求

进行身份认证时，EMQ X 将使用当前客户端信息填充并发起用户配置的认证查询请求，查询出该客户端在 HTTP 服务器端的认证数据。

打开etc/plugins/emqx_auth_http.conf配置文件，通过修改如下内容：修改完成后需要重启EMQX服务 。

HTTP 请求方法为 GET 时，请求参数将以 URL 查询字符串的形式传递；POST、PUT 请求则将请求参数以普通表单形式提交（content-type 为 x-www-form-urlencoded）。

你可以在认证请求中使用以下占位符，请求时 EMQ X 将自动填充为客户端信息：

• %u：用户名

• %c：Client ID

• %a：客户端 IP 地址

• %r：客户端接入协议

• %P：明文密码

• %p：客户端端口

• %C：TLS 证书公用名（证书的域名或子域名），仅当 TLS 连接时有效

• %d：TLS 证书 subject，仅当 TLS 连接时有效

推荐使用 POST 与 PUT 方法，使用 GET 方法时明文密码可能会随 URL 被记录到传输过程中的服务器日志中。

2.4.4 认证服务开发

创建基于springboot的应用程序： emqx-demo

1、pom文件

    4.0.0
    
        org.springframework.boot
        spring-boot-starter-parent
        2.6.5
         
    
    com.jie
    emqx-demo
    0.0.1-SNAPSHOT
    emqx-demo
    Demo project for Spring Boot
    
        1.8
    
    
        
            org.springframework.boot
            spring-boot-starter-web
        

        
            org.springframework.boot
            spring-boot-devtools
            runtime
            true
        
        
            org.springframework.boot
            spring-boot-configuration-processor
            true
        
        
            org.projectlombok
            lombok
            true
        
        
            org.springframework.boot
            spring-boot-starter-test
            test
        
    

    
        
            
                org.springframework.boot
                spring-boot-maven-plugin
                
                    
                        
                            org.projectlombok
                            lombok
                        
                    
                
            
        
    

2、创建application.yml配置文件并配置

server:
  port: 8991
spring:
  application:
    name: emqx-demo

3、创建Controller：com.jie.emqxdemo.mqtt.AuthController；编写如下

package com.jie.emqxdemo.controller.mqtt;


import lombok.extern.slf4j.Slf4j;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.util.StringUtils;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

import javax.annotation.PostConstruct;
import java.util.HashMap;
import java.util.Map;

/**
 * @description:接受认证请求
 * @author: jie
 * @time: 2022/3/29 20:57
 */
@RestController
@RequestMapping("/mqtt")
@Slf4j
public class AuthController {
    /**
     * 用于存储数据   实际开发应该是存储在数据库中
     */
    private Map users;

    @PostConstruct
    public void init() {
        //实际的密码应该是密文,mqtt的http认证组件传输过来的密码是明文，我们需要自己进行加密验证
        users = new HashMap<>();
        users.put("user", "123456");
        users.put("emq-client2", "123456");
        users.put("emq-client3", "123456");
    }

    /**
     * @description:接受消息 如果属性名对应不上可以用@RequestParam注解做映射
     * @author: jie
     * @time: 2022/3/29 21:03
     */
    @PostMapping("/auth")
    public ResponseEntity auth(@RequestParam("clientid") String clientid,
                                  @RequestParam("username") String username,
                                  @RequestParam("password") String password) {
        log.info("emqx认证组件调用自定义的认证服务开始认证,clientid={},username={},password= {}", clientid, username, password);
        //在此处可以进行复杂也的认证逻辑,但是我们为了演示方便做一个固定操作
        String value = users.get(username);
        if (StringUtils.isEmpty(value)) {
            return new ResponseEntity