# 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
--bridge---The path of a specified bridge configuration file
--auth---The path of a specified authorize 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

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 broker start --url nmq-tcp://localhost:1884 --url nmq-ws://localhost:8085 --http -p 30000
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
available applications:
   * broker
   * pub
   * sub
   * conn
   * bench
   * nngcat

EMQX Edge Computing Kit v0.6.0-3
Copyright 2022 EMQX Edge Team
1
2
3
4
5
6
7
8
9
10
11
$ nanomq bench start
Usage: nanomq bench start { 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 bench start 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 bench start pub -t t -h nanomq-server -s 16 -q 0 -c 10 -I 10
1

# Subscribe

Execute nanomq bench start 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 bench start sub -t t -h nanomq-server -c 500
1

# Connect

Execute nanomq bench start 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 bench start conn -h nano-server -c 1000
1

# SSL connection

bench supports establishing a secure SSL connection and performing tests.

One-way certificate:

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

Two-way certificate:

$ nanomq bench start sub -c 100 -i 10 -t bench -p 8883 --certfile path/to/client-cert.pem --keyfile path/to/client-key.pem
$ nanomq bench start 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 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 pub start -t t -h nanomq-server -q 2 -u nano -L 100 -m test
1

# Sub

Execute nanomq sub 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 from topic t .

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

# Conn

Execute nanomq 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 conn start -h nanomq-server -q 1
1