# NanoMQ Toolkit

NanoMQ 有丰富的工具集,其中包括 broker、 bench、 conn、 pub、 sub client。接下来将一一进行介绍。

# broker

NanoMQ 是一款用在物联网平台边缘端的超轻量 MQTT Broker。

ParameterabbreviationOptional valueDefault valueDescription
--url--nmq-tcp://127.0.0.1:1883指定监听的 url: 'nmq-tcp://host:port', 'tls+nmq-tcp://host:port' or 'nmq-ws://host:port/path' or 'nmq-wss://host:port/path'
--conf---NanoMQ 配置文件路径
--http-true falsefalseHttp 服务开关
--port-p-8081Http 服务端口设置
--tq_thread-t--Taskq 线程数量设置,最小为1, 最大为256
--max_tq_thread-T--Taskq 最大线程数量设置,最小为1, 最大为256
--parallel-n--可以处理的最大外部请求数
--property_size-s--MQTT 用户属性的最大数量
--msq_len-S--重发消息的最大数量
--qos_duration-D--Qos 定时器时间间隔
--daemon-dtrue falsefalseDaemon 模式运行 NanoMQ
--cacert---PEM 编码 CA 证书路径
--cert-E--用户证书路径
--key---PEM 编码用户私钥路径
--keypass---用户密钥。在私钥受密钥保护的情况下使用。
--verify-true falsefalse设置对端证书验证
--fail-true falsefalse客户端证书验证操作使能位。如果设置为true,客户端无证书时拒绝连接
--log_level-trace, debug, info, warn, error, fatalwarn日志等级
--log_file---日志文件输出路径
--log_stdout-true, falsetrue日志输出到控制台
--log_syslog-true, falsefalse日志输出到Syslog (默认只支持Linux系统)

例如,我们在 url nmq-tcp://localhost:1884 上启动 NanoMQ 监听 MQTT 消息,在 url nmq-ws://localhost:8085 上启动 websocket 消息,在端口 30000 上启用 http 服务器。

$ nanomq start --url nmq-tcp://localhost:1884 --url nmq-ws://localhost:8085 --http -p 30000
1

nanomq命令行支持多个日志类型输出,例如以下同时启用三种输出类型, 并设置日志等级为debug:

$ nanomq start --log_level=debug --log_file=nanomq.log  --log_stdout=true --log_syslog=true
1

# bench

Bench 是使用 NanoSDK 编写的简洁强大的 MQTT 协议性能测试工具。

# Compile

注意:bench 工具默认不构建,您可以通过-DBUILD_BENCH=ON 启用它。

$ cmake -G Ninja -DBUILD_BENCH=ON ..
$ Ninja
1
2

编译完成后,会生成一个名为“nanomq”的可执行文件。执行以下命令确认可以正常使用:

$ nanomq_cli 
available tools:
   * pub
   * sub
   * conn
   * bench
   * nngproxy
   * nngcat

Copyright 2022 EMQ Edge Computing Team
1
2
3
4
5
6
7
8
9
10
$ nanomq_cli bench
Usage: nanomq_cli bench { pub | sub | conn } [--help]
1
2

以上内容的输出证明bench已经被正确编译。

# 使用

bench 有三个子命令:

  1. pub:用于创建大量客户端来执行发布消息的操作。
  2. sub:用于创建大量客户端订阅主题和接收消息。
  3. conn:用于创建大量连接。

# 发布

执行 nanomq_cli bench pub --help 时,您将获得可用的参数输出。

ParameterabbreviationOptional valueDefault valueDescription
--host-h-localhost服务端地址
--port-p-1883服务端端口
--version-V3 4 55MQTT 协议版本
--count-c-200客户端数量
--interval-i-10创建客户端的时间间隔 (ms)
--interval_of_msg-I-1000发布消息时间间隔
--username-u-None; optional客户端用户名
--password-P-None; optional客户端密码
--topic-t-None; required发布主题
--size-s-256消息负载的大小
--qos-q-0Qos 服务级别
--retain-rtrue falsefalse保留消息标示位
--keepalive-k-300保活时间
--clean-Ctrue falsetrue清理会话标示位
--ssl-Strue falsefalseSSL 使能位
--certfile--None客户端 SSL 证书
--keyfile--None客户端私钥
--ws-true falsefalse是为建立 websocket 连接

例如,我们启动 10 个连接,每秒向主题 t 发送 100 条 Qos0 消息,其中每个消息负载的大小为 16 字节:

$ nanomq_cli bench pub -t t -h nanomq-server -s 16 -q 0 -c 10 -I 10
1

# 订阅

执行 nanomq_cli bench sub --help 以获取此子命令的所有可用参数。它们的解释已包含在上表中,此处不再赘述。

例如,我们启动 500 个连接,每个连接使用 Qos0 订阅 t 主题:

$ nanomq_cli bench sub -t t -h nanomq-server -c 500
1

# 连接

执行 nanomq_cli bench conn --help 以获取此子命令的所有可用参数。它们的解释已包含在上表中,此处不再赘述。

例如,我们启动 1000 个连接:

$ nanomq_cli bench conn -h nano-server -c 1000
1

# SSL 连接

bench 支持建立安全的 SSL 连接和执行测试。

单向认证

$ nanomq_cli bench sub -c 100 -i 10 -t bench -p 8883 -S
$ nanomq_cli bench pub -c 100 -I 10 -t bench -p 8883 -s 256 -S
1
2

双向认证

$ nanomq_cli bench sub -c 100 -i 10 -t bench -p 8883 --certfile path/to/client-cert.pem --keyfile path/to/client-key.pem
$ nanomq_cli bench pub -c 100 -i 10 -t bench -s 256 -p 8883 --certfile path/to/client-cert.pem --keyfile path/to/client-key.pem
1
2

# client

目前客户端支持 MQTT 版本 3.1/3.1.1。

# Pub

执行 nanomq pub --help 时,您将获得可用的参数输出。

ParameterabbreviationOptional valueDefault valueDescription
--url--mqtt-tcp://127.0.0.1:1883连接到服务端的 url
--version-V3 4 54MQTT 协议版本
--parallel-n-1客户端并行数
--verbose-v-disable是否详细输出
--user-u-None; optional客户端用户名
--password-P-None; optional客户端密码
--topic-t-None; required发布的主题
--msg-m-None; required发布的消息
--qos-q-0Qos 级别
--retain-rtrue falsefalse保留标识位
--keepalive-k-300保活时间
--count-C-1客户端数量
--clean_session-ctrue falsetrue会话清除
--ssl-strue falsefalseSSL 使能位
--cacert--NoneSSL 证书
--cert-E-None证书路径
--key-true falsefalse私钥路径
--keypass--None私钥密码
--interval-i-10创建客户端间隔(ms)
--identifier-I-random客户端订阅标识符
--limit-L-1最大发布消息刷量
--will-qos--0遗愿消息的 qos 级别
--will-msg--None遗愿消息
--will-topic--None遗愿消息主题
--will-retain-true falsefalse遗愿消息保留标示位

例如,我们使用用户名 nano 启动 1 个客户端,并向主题 t 发送 100 条 Qos2 消息测试。

$ nanomq_cli pub -t t -h nanomq-server -q 2 -u nano -L 100 -m test
1

# Sub

执行 nanomq_cli sub --help 以获取该命令的所有可用参数。它们的解释已包含在上表中,此处不再赘述。

例如,我们使用用户名 nano 启动 1 个客户端,并从主题 t 设置 Qos1。

$ nanomq_cli sub -t t -h nanomq-server -q 1
1

# Conn

执行 nanomq_cli conn --help 以获取该命令的所有可用参数。它们的解释已包含在上表中,此处不再赘述。

例如,我们使用用户名 nano 启动 1 个客户端并设置 Qos1 。

$ nanomq_cli conn -h nanomq-server -q 1
1

# Rule

执行 nanomq_cli rules --help 以获取该命令的所有可用参数。

# rules create

创建一个新的规则。参数:

  • <sql>: 规则 SQL
  • <actions>: JSON 格式的动作列表

使用举例:

## 创建一个 sqlite 落盘规则,存储所有发送到 'abc' 主题的消息内容
$ nanomq_cli rules --create --sql 'SELECT * FROM "abc"' --actions '[{"name":"sqlite", "params": {"table": "test01"}}]'

{"rawsql":"SELECT * FROM \"abc\"","id":4,"enabled":true}

1
2
3
4
5

# rules list

列出当前所有的规则:

$ nanomq_cli rules --list

{"rawsql":"SELECT payload.x.y as y, payload.z as z FROM \"#\" WHERE y > 10 and z != 'str'","id":1,"enabled":true}
{"rawsql":"SELECT * FROM \"abc\"","id":2,"enabled":true}
{"rawsql":"SELECT payload, qos FROM \"#\" WHERE qos > 0","id":3,"enabled":true}
{"rawsql":"SELECT * FROM \"abc\"","id":4,"enabled":true}

1
2
3
4
5
6
7

# rules show

查询规则:

## 查询 RuleID 为 '1' 的规则
$ nanomq_cli rules --show --id 1

{"rawsql":"SELECT payload.x.y as y, payload.z as z FROM \"#\" WHERE y > 10 and z != 'str'","id":1,"enabled":true}
1
2
3
4

# rules delete

删除规则:

## 删除 RuleID 为 'rule:1' 的规则
$ nanomq_cli rules --delete --id 1

{"code":0}
1
2
3
4