# NanoMQ Toolkit

NanoMQ contains abundant toolkit include broker, bench, conn, pub, sub client. Here we will show you one by one.

# broker

NanoMQ MQTT Broker (NanoMQ) is a lightweight and blazing-fast MQTT Broker for the IoT Edge platform.

ParameterabbreviationOptional valueDefault valueDescription
--url--nmq-tcp://127.0.0.1:1883Specify listener's url: 'nmq-tcp://host:port', 'tls+nmq-tcp://host:port' or 'nmq-ws://host:port/path' or 'nmq-wss://host:port/path'
--conf---The path of a specified nanomq configuration file
--http-true falsefalseEnable http server
--port-p-8081The port of http server
--tq_thread-t--The number of taskq threads used, num greater than 1 and less than 256
--max_tq_thread-T--The maximum number of taskq threads used, num greater than 1 and less than 256
--parallel-n--The maximum number of outstanding requests we can handle
--property_size-s--The max size for a MQTT user property
--msq_len-S--The queue length for resending messages
--qos_duration-D--The interval of the qos timer
--daemon-dtrue falsefalseRun nanomq as daemon
--cacert---Path to the file containing PEM-encoded CA certificates
--cert-E--Path to a file containing the user certificate
--key---Path to the file containing the user's private PEM-encoded key
--keypass---String containing the user's password. Only used if the private keyfile is password-protected
--verify-true falsefalseSet verify peer certificate
--fail-true falsefalseServer will fail if the client does not have a certificate to send
--log_level-trace, debug, info, warn, error, fatalwarnLog level
--log_file---The path of the log file
--log_stdout-true, falsetrueEnable/Disable console log output
--log_syslog-true, falsefalseEnable/Disable syslog (only enable on Linux)

For example, we start NanoMQ listen mqtt message on url nmq-tcp://localhost:1884, websocket message on url nmq-ws://localhost:8085, enable http server on port 30000.

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

nanomq support multiple log types; For example, set output log to file ,console and syslog with log level debug:

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

# bench

Bench is a concise and powerful MQTT protocol performance testing tool written with NanoSDK.

# Compile

**Note **: bench tool isn't built by default, you can enable it via -DBUILD_BENCH=ON.

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

After the compilation, an executable file named nanomq will be generated. Execute the following command to confirm that it can be used normally:

$ 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

The output of the above content proves that bench has been correctly compiled.

# Use

There are three subcommands of bench:

  1. pub: used to create a large number of clients to perform the operation of publishing messages.
  2. sub: Used to create a large number of clients to subscribe to topics and receive messages.
  3. conn: used to create a large number of connections.

# Publish

When executing nanomq_cli bench pub --help, you will get the available parameter output.

ParameterabbreviationOptional valueDefault valueDescription
--host-h-localhostAddress of the MQTT server to connect
--port-p-1883MQTT service port
--version-V3 4 55MQTT protocol version used
--count-c-200Total number of clients
--interval-i-10Interval to create a client; unit: ms
--interval_of_msg-I-1000Interval to publish a message
--username-u-None; optionalClient username
--password-P-None; optionalClient password
--topic-t-None; requiredPublished topics
--size-s-256Message Payload size; unit: bytes
--qos-q-0Qos level
--retain-rtrue falsefalseWhether the message sets the Retain flag
--keepalive-k-300Client keepalive time
--clean-Ctrue falsetrueWhether to establish a connection by cleaning the session
--ssl-Strue falsefalseWhether to enable SSL
--certfile--NoneClient SSL certificate
--keyfile--NoneClient SSL key file
--ws-true falsefalseWhether to establish a connection via Websocket

For example, we start 10 connections and send 100 Qos0 messages to the topic t every second, where the size of each message payload is16 bytes:

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

# Subscribe

Execute nanomq_cli bench sub --help to get all available parameters of this subcommand. Their explanations have been included in the table above and are omitted here.

For example, we start 500 connections, and each subscribes to the t topic with Qos0:

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

# Connect

Execute nanomq_cli bench conn --help to get all available parameters of this subcommand. Their explanations have been included in the table above and are omitted here.

For example, we start 1000 connections:

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

# SSL connection

bench supports establishing a secure SSL connection and performing tests.

One-way certificate:

$ 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

Two-way certificate:

$ 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

An MQTT version 3.1/3.1.1 client for now.

# Pub

When executing nanomq_cli pub --help, you will get the available parameter output.

ParameterabbreviationOptional valueDefault valueDescription
--url--mqtt-tcp://127.0.0.1:1883The url for mqtt broker
--version-V3 4 54MQTT protocol version used
--parallel-n-1The number of parallel for client
--verbose-v-disableEnable verbose mode
--user-u-None; optionalClient username
--password-P-None; optionalClient password
--topic-t-None; requiredPublished topics
--msg-m-None; requiredPublish message
--qos-q-0Qos level
--retain-rtrue falsefalseWhether the message sets the Retain flag
--keepalive-k-300Client keepalive time
--count-C-1Num of client
--clean_session-ctrue falsetrueWhether to establish a connection by cleaning the session
--ssl-strue falsefalseWhether to enable SSL
--cacert--NoneClient SSL certificate
--cert-E-NoneCertificate file path
--key-true falsefalsePrivate key file path
--keypass--NonePrivate key password
--interval-i-10Interval to create a client; unit: ms
--identifier-I-randomThe client identifier UTF-8 String
--limit-L-1Max count of publishing message
--will-qos--0Quality of service level for the will message
--will-msg--NoneThe payload of the will message
--will-topic--NoneThe topic of the will message
--will-retain-true falsefalseWill message as retained message

For example, we start 1 client with username nano and send 100 Qos2 messages test to the topic t .

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

# Sub

Execute nanomq_cli sub --help to get all available parameters of this command. Their explanations have been included in the table above and are omitted here.

For example, we start 1 client with username nano and set Qos1 from topic t .

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

# Conn

Execute nanomq_cli conn start --help to get all available parameters of this command. Their explanations have been included in the table above and are omitted here.

For example, we start 1 client with username nano and set Qos1 .

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

# Rule

Execute nanomq_cli rule --help to get all available parameters of this command.

# rules create

Create a new rule with the following parameter:

  • <sql>:rule SQL
  • <actions>: Action list in JSON format

Example:

## Create a sqlite rule,store all datas sent to  '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

List all rules:

## list all rules
$ 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
8

# rules show

Query rules:

## Query rule with 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

Delete a rule:

## Delete rule with RuleID '1' 
$ nanomq_cli rules --delete --id 1

{"code":0}
1
2
3
4