XMQ MQTT Server – Documentation

MQTT testing suite

xmq_scn runs load-test scenarios described by JSON files. It is broker-neutral: it speaks plain MQTT and can be pointed at Mosquitto, EMQX, NanoMQ or anything else, which is what makes its numbers comparable across brokers.

Scenarios ship in /usr/local/share/xmq. List them with:

xmq_scn --list-scenarios

A scenario file names the client groups, their counts, the topics, and the pacing. The shipped set covers connection ramps, fan-in, fan-out, and point-to-point, at sizes from 10,000 to 1,000,000 connections. Writing a new one is a matter of copying the closest and changing the numbers.

xmq_scn -s Point-To-Point-50K-50K-50K-50K.json --progress
xmq_scn -s 1M-Connections-5K-rate.json -h broker -p 1883

Reaching the larger sizes needs the tuning above on both hosts, and enough source addresses on the client: a connection is identified by its source address and port, so one address runs out of ports long before a million connections. The tested 1,000,000-connection runs used 30 client addresses, about 33,000 connections each. The make_ip_addresses.sh helper in the same directory adds them, andremove_ip_addresses.sh takes them away again:

./make_ip_addresses.sh -s <first three octets> -p <prefix> -f <first host octet> -c 29

Scenarios spread their clients across whatever addresses the host has, so the--id-prefix option keeps client ids distinct when several client machines drive the same broker.

Testing your setup

Three small utilities are enough to prove an installation works. All of them take-h host, -p port, -u username,--password, and --version.

Is the server up?

systemctl status xmq_server
tail -f /var/log/xmq/xmq_server.log

The log names each listener it opened at startup, and says which storage it is using: a Redis address, or memory when persistence is off or Redis could not be reached.

Subscribe and publish

In one terminal, subscribe. In another, publish, and watch it arrive:

xmq_sub -h localhost -p 1883 -u user --password secret -t "test/#" -q 1 -v

xmq_pub -h localhost -p 1883 -u user --password secret -t test/hello -m "it works"

Useful xmq_pub options: -r repeats the message a number of times, -g paces it to a rate, -f takes the payload from a file, -s reads it from standard input, and -l stamps a send timestamp into the payload so latency can be measured at the far end.

Testing TLS

xmq_sub -h localhost -p 8883 -u user --password secret \
        -t "test/#" -q 1 -v --cafile /etc/xmq/certs/ca.crt

If this fails while the plain port works, the certificates are the place to look: the server log says whether it managed to load them at startup.

Many connections at once

xmq_con opens a number of sessions and holds them, which is the quickest way to see whether the host limits are in place:

xmq_con -h localhost -p 1883 -u user --password secret -n 10000 --show-counters

If it stops short of the number asked for, the file descriptor limit is the usual cause, on whichever host ran out first. Check both, then see the tuning section.

Checking a bridge

Subscribe on the remote broker, publish on XMQ, and confirm the message crosses:

xmq_sub -h remote-broker -p 1883 -t "bridged/#" -q 1 -v

xmq_pub -h localhost -p 1883 -u user --password secret -t bridged/test -m "over the bridge"

Nothing arriving usually means the bridge is disabled, its topic pattern does not cover the topic, or its direction excludes it. The server log, withConnections at DEBUG, shows the bridge connecting and how many topics it subscribed to.