Skip to content

Latest commit

 

History

History
133 lines (98 loc) · 5.48 KB

README.md

File metadata and controls

133 lines (98 loc) · 5.48 KB
Raw

Description

Build Status

The MQTT-Proxy itself sits between the MQTT-Provider & -Consumer and intercepts incoming MQTT-Commands, with the ability to call a REST-API at the API-Gateway. With that, it is for instance possible to validate, that a certain MQTT-Consumer can subscribe to a topic, as the API-Gateway can easily validate the Subscription-Request using a database, another downstream API, whatever.

To get an overview you can also watch our MQTT video series:
MQTT Proxy and Trigger videos

alt text

The diagram below details more flows between the various components:

alt text

API Management Version Compatibilty

This artefact can be used with every API Management Plus version

Prerequisites

  • docker 17.06 (and docker-compose)
  • MQTT Broker : activemq / rabbitmq / mosquitto / ...
  • Policy Engine : Axway API Gateway or custom engine (see [./tests/policy] ) exposing the REST-API to use

Configure your policy engine

The first important step is to tell the MQTT-Proxy, the location of the REST-API to use. This is configured using the Docker Environment-Variable AUTH_URL and when configured every mqtt packet (CONNECT, SUBSCRIBE, PUBLISH in/out) is checked against this endpoint. The REST-API calls exeuted by the MQTT-Proxy are described here: AUTH_API

We are providing some sample REST-APIs for the Axway API Gateway in: ./api-gateway-policies/mqtt-proxy-apigw-policy.xml To use it, just "Import the Configuration Fragment" using Axway API Gateway Policy Studio and deploy this to your API-Gateway.

Command-line / Environment options

The MQTT-Proxy binary comes with a number of command-line options to enable, disable or control certain features. To review all possible command-line options the MQTT-Proxy provides, please execute the following command:

docker run -it --rm davinci1976/mqtt-proxy mqtt-proxy --help

Quickstart

To use the MQTT-Proxy you have multiple ways to start it, either using your own MQTT-Broker or an MQTT-Broker included in this asset and started as a Docker-Container.

Standalone (mqtt-proxy only)

Standalone means, that no MQTT-Broker is started, hence you have to configure the location of your existing running MQTT-Broker. This is a simple example without user-authentication against the MQTT-Broker:

docker run -it --rm -e AUTH_URL=http://api-host:8080/mqtt -e MQTT_BROKER_HOST=my-mqtt-broker -p 1883:1883 davinci1976/mqtt-proxy

An example would be:

docker run -it --rm -e AUTH_URL=http://172.17.0.1:8080/mqtt -e PORT=1884 -e MQTT_BROKER_HOST=172.10.1 -p 1884:1883 davinci1976/mqtt-proxy

another one using some of command line options provided by the mqtt-proxy binary plus user-authn against the MQTT-Broker:

docker run -it --rm -e AUTH_URL=http://172.17.0.1:8080/mqtt -e MQTT_BROKER_HOST=172.10.1 -e MQTT_BROKER_USERNAME=mqttuser -e MQTT_BROKER_PASSWORD=changeme -p 1884:1883 davinci1976/mqtt-proxy mqtt-proxy -mqtt-port 1884 -mqtts-port 1885

The following environment variables including default values are supported (please use --help for all command line options):

PORT 1883
MQTT_BROKER_HOST 0.0.0.0
MQTT_BROKER_PORT 1883
MQTT_BROKER_USERNAME guest
MQTT_BROKER_PASSWORD guest
AUTH_URL ""

Full environment (mqtt-proxy + broker + custom policy engine)

This brings up a complete environment, including the MQTT-Proxy, MQTT-Broker (RabbitMq, Mosquitto, ActiveMQ) and a Node.js based REST-API listening on http://policy:3000/mqtt for testing purposes:

docker-compose -f docker-compose.yml up

This is much more than needed, but you can adjust the docker-compose.yml file according to your needs.

Build standalone binary:

Prerequisites : golang

make install-deps
make

Build docker image

Prerequisites : docker 17.05

docker build -t mqtt-proxy .

-or-

make docker

Test

make docker-test

Changelog

  • 0.0.4

    • Add HTTPS and MQTTS server support --mqtts-* --https-*
    • Add HTTPS client support for authz/authn with added cert verification
    • Remove the 2 steps build: use docker 17.05 build capability

  • 0.0.3

    • Add websocket support --http-host --http-port
    • rename --mqtt-* variables to --mqtt-broker-*

Limitations/Caveats

  • No broker routing : Only one broker per mqtt-proxy instance
    • no configurable routes
  • No TLS support for broker
  • No additional TLS options supported between the client and mqtt-proxy (algo, ....)
  • No HTTP API to publish a MQTT message on a topic /topics/:topic?qos=:qos (like http://docs.aws.amazon.com/iot/latest/developerguide/protocols.html#http)
  • No cache for publish/receive/subscribe policy check

Contributing

Please read Contributing.md for details on our code of conduct, and the process for submitting pull requests to us.

Team

alt text Axway Team

License

Apache License 2.0