mqttor

MQTTOR

The fully compliant, embeddable high-performance Go MQTT broker server, support cluster mode. Its based on mochi-co/mqtt and hashicorp/memberlist.

Quick Start

mqttor can be used as a standalone broker. Simply checkout this repository and run the cmd/main.go entrypoint in the cmd folder which will expose tcp (:1883), tls tcp (:8883), websocket (:1882), and dashboard (:8080) listeners. mqttor also support cluster mode. it based on memberlist (:7943).

Simple start

cd cmd
go build -o mqttor && ./mqttor

Start with dashboard

./mqttor -dashboard=8080

Start with TLS

# only tls on 8883
./mqttor -tls=8883 -tls-ca="./ca.crt" -tls-cert="./server.crt" -tls-key="./server.key"

# both start tcp and tls tcp
./mqttor -tcp=1883 -tls=8883 -tls-ca="./ca.crt" -tls-cert="./server.crt" -tls-key="./server.key"

Start cluster

# start the first node
./mqttor -tcp=1883 \ 
  -mode=cluster \ 
  -cluster-addr="172.16.3.3:7943" \ 

# start the second node
./mqttor -tcp=1884 \ 
  -mode=cluster \ 
  -cluster-addr="172.16.3.3:7944" \ 
  -cluster-members="172.16.3.3:7943"

Using Docker

A simple Dockerfile is provided for running the cmd/main.go Websocket, TCP, and Stats server:

docker build -t mqttor:latest .
docker run \
    -e TCP_PORT=1883 \
    -v ./log:/log \
    -v ./data:/data \
    --name mqttor \
    -p 1883:1883 \
    -d mqttor

Docker start tls

docker run \
    -e TCP_PORT=1883 \
    -e TLS_PORT=8883 \
    -e TLS_CA=/ssl/root.crt \
    -e TLS_CERT=/ssl/server.crt \
    -e TLS_KEY=/ssl/server.key \
    -v ./log:/log \
    -v ./ssl:/ssl \
    -v ./data:/data \
    -p 8883:8883 \
    -p 1883:1883 \
    -d mqttor

Docker start cluster

# start node1
docker run \
    -e TCP_PORT=1883 \
    -e MODE=cluster \
    -e CLUSTER_ADDR=":7943" \
    -e ADVERTIES_ADDR="172.16.3.3:7943" \
    -v ./log:/log \
    -v ./data:/data \
    --name node1 \
    -p 8883:8883 \
    -p 1883:1883 \
    -p 7943:7943 \
    -p 8883:8883/udp \
    -p 1883:1883/udp \
    -p 7943:7943/udp \
    -d mqttor

# start node2
docker run \
    -e TCP_PORT=1883 \
    -e MODE=cluster \
    -e CLUSTER_ADDR=":7943" \
    -e ADVERTIES_ADDR="172.16.3.3:7944" \
    -e CLUSTER_MEMBERS="172.16.3.3:7943" \
    -v ./log:/log \
    -v ./data:/data \
    --name node2 \
    -p 8884:8883 \
    -p 1884:1883 \
    -p 7944:7943 \
    -p 8884:8883/udp \
    -p 1884:1883/udp \
    -p 7944:7943/udp \
    -d mqttor

Developing with mqttor

Importing as a package

Importing mqttor as a package requires just a few lines of code to get started.

import (
  "log"

  "github.com/thermog/mqttor"
  "github.com/thermog/mqttor/hooks/auth"
  "github.com/thermog/mqttor/listeners"
)

func main() {
  // Create the new MQTT Server.
  server := mqttor.New(nil)
  
  // Allow all connections.
  _ = server.AddHook(new(auth.AllowHook), nil)
  
  // Create a TCP listener on a standard port.
  tcp := listeners.NewTCP("t1", ":1883", nil)
  err := server.AddListener(tcp)
  if err != nil {
    log.Fatal(err)
  }
  
  err = server.Serve()
  if err != nil {
    log.Fatal(err)
  }
}

Examples of running the broker with various configurations can be found in the examples folder.

Network Listeners

The server comes with a variety of pre-packaged network listeners which allow the broker to accept connections on different protocols. The current listeners are:

Use the listeners.Listener interface to develop new listeners. If you do, please let us know!

A *listeners.Config may be passed to configure TLS.

Examples of usage can be found in the examples folder or cmd/main.go.

Server Options and Capabilities

A number of configurable options are available which can be used to alter the behaviour or restrict access to certain features in the server.

server := mqtt.New(&mqtt.Options{
  Capabilities: mqtt.Capabilities{
    MaximumSessionExpiryInterval: 3600,
    Compatibilities: mqtt.Compatibilities{
      ObscureNotAuthorized: true,
    },
  },
  SysTopicResendInterval: 10,
})

Review the mqtt.Options, mqtt.Capabilities, and mqtt.Compatibilities structs for a comprehensive list of options.

Event Hooks

A universal event hooks system allows developers to hook into various parts of the server and client life cycle to add and modify functionality of the broker. These universal hooks are used to provide everything from authentication, persistent storage, to debugging tools.

Hooks are stackable - you can add multiple hooks to a server, and they will be run in the order they were added. Some hooks modify values, and these modified values will be passed to the subsequent hooks before being returned to the runtime code.

Many of the internal server functions are now exposed to developers, so you can make your own Hooks by using the above as examples. If you do, please Open an issue and let everyone know!

More refer to mochi-co/mqtt

Access Control

Allow Hook

By default, mqttor uses a DENY-ALL access control rule. To allow connections, this must overwritten using an Access Control hook. The simplest of these hooks is the auth.AllowAll hook, which provides ALLOW-ALL rules to all connections, subscriptions, and publishing. It's also the simplest hook to use:

server := mqttor.New(nil)
_ = server.AddHook(new(auth.AllowHook), nil)

Don't do this if you are exposing your server to the internet or untrusted networks - it should really be used for development, testing, and debugging only.

Auth Ledger

The Auth Ledger hook provides a sophisticated mechanism for defining access rules in a struct format. Auth ledger rules come in two forms: Auth rules (connection), and ACL rules (publish subscribe).

Auth rules have 4 optional criteria and an assertion flag:

ACL rules have 3 optional criteria and an filter match:

Rules are processed in index order (0,1,2,3), returning on the first matching rule. See hooks/auth/ledger.go to review the structs.

server := mqttor.New(nil)
err := server.AddHook(new(auth.Hook), &auth.Options{
    Ledger: &auth.Ledger{
    Auth: auth.AuthRules{ // Auth disallows all by default
      {Username: "peach", Password: "password1", Allow: true},
      {Username: "melon", Password: "password2", Allow: true},
      {Remote: "127.0.0.1:*", Allow: true},
      {Remote: "localhost:*", Allow: true},
    },
    ACL: auth.ACLRules{ // ACL allows all by default
      {Remote: "127.0.0.1:*"}, // local superuser allow all
      {
        // user melon can read and write to their own topic
        Username: "melon", Filters: auth.Filters{
          "melon/#":   auth.ReadWrite,
          "updates/#": auth.WriteOnly, // can write to updates, but can't read updates from others
        },
      },
      {
        // Otherwise, no clients have publishing permissions
        Filters: auth.Filters{
          "#":         auth.ReadOnly,
          "updates/#": auth.Deny,
        },
      },
    },
  }
})

The ledger can also be stored as JSON or YAML and loaded using the Data field:

err = server.AddHook(new(auth.Hook), &auth.Options{
    Data: data, // build ledger from byte slice: yaml or json
})

See examples/auth/encoded/main.go for more information.

Persistent Storage

Redis

A basic Redis storage hook is available which provides persistence for the broker. It can be added to the server in the same fashion as any other hook, with several options. It uses github.com/go-redis/redis/v8 under the hook, and is completely configurable through the Options value.

err := server.AddHook(new(redis.Hook), &redis.Options{
  Options: &rv8.Options{
    Addr:     "localhost:6379", // default redis address
    Password: "",               // your password
    DB:       0,                // your redis db
  },
})
if err != nil {
  log.Fatal(err)
}

For more information on how the redis hook works, or how to use it, see the examples/persistence/redis/main.go or hooks/storage/redis code.

Badger DB

There's also a BadgerDB storage hook if you prefer file based storage. It can be added and configured in much the same way as the other hooks (with somewhat less options).

err := server.AddHook(new(badger.Hook), &badger.Options{
  Path: badgerPath,
})
if err != nil {
  log.Fatal(err)
}

For more information on how the badger hook works, or how to use it, see the examples/persistence/badger/main.go or hooks/storage/badger code.

There is also a BoltDB hook which has been deprecated in favour of Badger, but if you need it, check examples/persistence/bolt/main.go.

Developing with Event Hooks

Many hooks are available for interacting with the broker and client lifecycle. The function signatures for all the hooks and mqtt.Hook interface can be found in hooks.go.

The most flexible event hooks are OnPacketRead, OnPacketEncode, and OnPacketSent - these hooks be used to control and modify all incoming and outgoing packets.

If you are building a persistent storage hook, see the existing persistent hooks for inspiration and patterns. If you are building an auth hook, you will need OnACLCheck and OnConnectAuthenticate.

Direct Publish

To publish basic message to a topic from within the embedding application, you can use the server.Publish(topic string, payload []byte, retain bool, qos byte) error method.

err := server.Publish("direct/publish", []byte("packet scheduled message"), false, 0)

The Qos byte in this case is only used to set the upper qos limit available for subscribers, as per MQTT v5 spec.

Packet Injection

If you want more control, or want to set specific MQTT v5 properties and other values you can create your own publish packets from a client of your choice. This method allows you to inject MQTT packets (no just publish) directly into the runtime as though they had been received by a specific client. Most of the time you'll want to use the special client flag inline=true, as it has unique privileges: it bypasses all ACL and topic validation checks, meaning it can even publish to $SYS topics.

Packet injection can be used for any MQTT packet, including ping requests, subscriptions, etc. And because the Clients structs and methods are now exported, you can even inject packets on behalf of a connected client (if you have a very custom requirements).

cl := server.NewClient(nil, "local", "inline", true)
server.InjectPacket(cl, packets.Packet{
  FixedHeader: packets.FixedHeader{
    Type: packets.Publish,
  },
  TopicName: "direct/publish",
  Payload: []byte("scheduled message"),
})

MQTT packets still need to be correctly formed, so refer our the test packets catalogue and MQTTv5 Specification for inspiration.

See the hooks example to see this feature in action.

Testing

Unit Tests

Mochi MQTT tests over a thousand scenarios with thoughtfully hand written unit tests to ensure each function does exactly what we expect. You can run the tests using go:

go run --cover ./...

Paho Interoperability Test

You can check the broker against the Paho Interoperability Test by starting the broker using examples/paho/main.go, and then running the mqtt v5 and v3 tests with python3 client_test5.py from the interoperability folder.

Note that there are currently a number of outstanding issues regarding false negatives in the paho suite, and as such, certain compatibility modes are enabled in the paho/main.go example.

Performance Benchmarks

Refer to mochi-co/mqtt