libmqttunnel

README

libmqttunnel: tunnel via MQTT broker

This library tunnels TCP Connection through the MQTT Broker.

Based on https://github.com/shirou/mqtunnel

How to use

Config file

You can use client certs as well as username/password in the Config file.

{
    "host": "mqttbroker.example",
    "port": 8883,
    "username", "",
    "password", "",
    "caCert": "certs/root-CA.crt",
    "clientCert": "certs/5a880e326f-certificate.pem.crt",
    "privateKey": "certs/5a880e326f-private.pem.key",
    "control": "device/1/control"
}

Other options

• clientId: MQTT ClientID. If empty, random string is generated

Architecture

Example: Local port = 2022, Remote port = 22,

sequenceDiagram

LocalTCP ->> LocalMQTunnel: conn read from port 2022
LocalMQTunnel ->> MQTTBroker: Publish to local port topic '/2022'
MQTTBroker ->> RemoteMQTunnel: Recieve from local port topic '/2022'
RemoteMQTunnel ->> RemoteTCP: conn write to port 22
RemoteTCP ->> RemoteMQTunnel: conn read from port 22
RemoteMQTunnel ->> MQTTBroker: Publish to local port topic '/22'
MQTTBroker ->> LocalMQTunnel: Recieve from local port topic '/22'
LocalMQTunnel ->> LocalTCP: conn write to port 2022

More internal architecture

sequenceDiagram

participant Remote
participant RemoteTCP
participant RemoteTCPConnection
participant RemoteMQTunnel

RemoteMQTunnel ->> RemoteMQTunnel: subscribe control topic
LocalMQTunnel ->> LocalMQTunnel: make a Tunnel instance which includes local/remote port pair
LocalMQTunnel ->> LocalTCP: NewTCPConnection()
LocalTCP ->> LocalTCP: start listening
Local ->> LocalTCP: connect
LocalTCP ->> LocalMQTunnel: OpenTunnel()
LocalMQTunnel ->> RemoteMQTunnel: Publish control packet
RemoteMQTunnel ->> RemoteTCPConnection: NewTCPConnection()
RemoteTCPConnection ->> RemoteTCP: connect()
RemoteTCP ->> Remote: connect()

License

• Apache License

Documentation

Index

• func NewMQTTBroker(conf Config, controlCh chan controlPacket) (*mqttBroker, error)
• type Config
  • func ReadConfig(filePath string) (Config, error)
• type MQTunnel
  • func NewMQTunnel(conf Config) (*MQTunnel, error)
  • func (mqt *MQTunnel) Start(ctx context.Context, localPort, remotePort int) error
• type TCPConnection
  • func NewTCPConnection(port int, tun *Tunnel) (*TCPConnection, error)
• type TCPListener
  • func NewTCPListener(conf Config, port int) (*TCPListener, error)
• type Tunnel
  • func NewTunnelFromConnect(ctx context.Context, mqttBroker *mqttBroker, conn net.Conn, topicRoot string, ...) (*Tunnel, error)
  • func NewTunnelFromControl(ctx context.Context, mqttBroker *mqttBroker, ctl controlPacket) (*Tunnel, error)

Functions

func NewMQTTBroker

func NewMQTTBroker(conf Config, controlCh chan controlPacket) (*mqttBroker, error)

Types

type Config

type Config struct {
	Host     string `json:"host"`
	Port     int    `json:"port"`
	UserName string `json:"username"`
	Password string `json:"password"`
	ClientID string `json:"clientId"`

	CaCert     string `json:"caCert"`
	ClientCert string `json:"clientCert"`
	PrivateKey string `json:"privateKey"`

	Control string `json:"control"`
}

func ReadConfig

func ReadConfig(filePath string) (Config, error)

type MQTunnel

type MQTunnel struct {
	// contains filtered or unexported fields
}

MQTunnel is a main component of mqtunnel.

func NewMQTunnel

func NewMQTunnel(conf Config) (*MQTunnel, error)

func (*MQTunnel) Start

func (mqt *MQTunnel) Start(ctx context.Context, localPort, remotePort int) error

Start starts a MQTT tunnel.

type TCPConnection

type TCPConnection struct {
	// contains filtered or unexported fields
}

func NewTCPConnection

func NewTCPConnection(port int, tun *Tunnel) (*TCPConnection, error)

type TCPListener

type TCPListener struct {
	// contains filtered or unexported fields
}

func NewTCPListener

func NewTCPListener(conf Config, port int) (*TCPListener, error)

type Tunnel

type Tunnel struct {
	ID          string
	LocalPort   int
	LocalTopic  string
	RemotePort  int
	RemoteTopic string
	// contains filtered or unexported fields
}

func NewTunnelFromConnect

func NewTunnelFromConnect(ctx context.Context, mqttBroker *mqttBroker, conn net.Conn, topicRoot string, local, remote int) (*Tunnel, error)

NewTunnelFromConnect creates a new Tunnel on local

func NewTunnelFromControl

func NewTunnelFromControl(ctx context.Context, mqttBroker *mqttBroker, ctl controlPacket) (*Tunnel, error)

NewTunnelFromControl creates a new Tunnel on remote side.