red5-mqtt-plugin

This plugin provides MQTT support services.

A little about MQTT

MQTT is a machine-to-machine (M2M)/"Internet of Things" connectivity protocol. It was designed as an extremely lightweight publish/subscribe messaging transport. It is useful for connections with remote locations where a small code footprint is required and/or network bandwidth is at a premium. For example, it has been used in sensors communicating to a broker via satellite link, over occasional dial-up connections with healthcare providers, and in a range of home automation and small device scenarios. This plugin provides an MQTT broker service that can be used to connect MQTT clients to Red5 applications. It supports MQTT v3.1.1 and includes support for persistent sessions, retained messages, QoS 0, 1, and 2, SSL/TLS connections, and authentication via username/password.

The plugin embeds a Moquette-derived broker implementation (source is included under org.eclipse.moquette.*) and uses Disruptor for the broker event loop.

Implementer-focused documentation is available in mqtt/IMPLEMENTERS.md. Proposed MQTT 5.0 design notes live in mqtt/MQTT5_DESIGN.md.

Implementer Quick Start

1. Add transports + broker beans to red5.xml (see Configuration section below).
2. Set dbStorePath to a writable file path for persistent sessions.
3. Optionally set passwdFileName for username/password auth.
4. Confirm ports (1883 for plain, 8883 for TLS).
5. Review version negotiation notes in mqtt/IMPLEMENTERS.md before enabling 5.0.
6. Use the tests in mqtt/src/test/java as a reference for broker behavior.

Build from Source

To build a plugin jar, execute the following on the command line from within the plugin base directory:

mvn -Dmaven.test.skip=true -Dmaven.javadoc.skip=true package

This will create the jar in the "target" directory of the workspace; this will also skip the unit tests.

To download the projects dependencies execute this:

mvn dependency:copy-dependencies

This will download all the dependencies into the "target" directory under "dependency". The files located in that directory should be placed in the plugins directory ONLY if they don't already exist within the lib directory.

Deploying to Red5

Drop the mqttplugin jar into the plugins directory and place the following dependencies there as well:

• Disruptor disruptor-4.0.0.jar
• MapDb mapdb-3.1.0.jar

Configuration

Add the MQTT nodes to your red5.xml or use an import. The mqtt.xml file is provided for your convenience.

To bind to one or many IP addresses and ports:

<bean id="mqttTransport" class="org.red5.server.mqtt.net.MQTTTransport">
        <property name="addresses">
            <list>
                <value>192.168.1.174</value>
                <value>192.168.1.174:1883</value>
                <value>192.168.1.174:2883</value>
            </list>
        </property>
</bean>

If you don't want to specify the IP:

<bean id="mqttTransport" class="org.red5.server.mqtt.net.MQTTTransport">
    <property name="port" value="1883"/>
</bean>

To support ssl / tls communication add this:

<bean id="mqttTransportSecure" class="org.red5.server.mqtt.net.MQTTTransport">
    <property name="secureConfig">
        <bean id="mqttSecureConfig" class="org.red5.server.mqtt.SecureMQTTConfiguration">
            <property name="keystoreType" value="JKS"/>
            <property name="keystoreFile" value="conf/keystore"/>
            <property name="keystorePassword" value="password"/>
            <property name="truststoreFile" value="conf/truststore"/>
            <property name="truststorePassword" value="password"/>
        </bean>
    </property>
    <property name="addresses">
        <list>
            <value>192.168.1.174:8883</value>
        </list>
    </property>
</bean>

Broker node:

<bean id="mqttBroker" class="org.red5.server.mqtt.MQTTBroker" depends-on="mqttTransport">
    <property name="dbStorePath" value="/opt/red5/mqtt_store.mapdb"/>
    <property name="passwdFileName" value=""/>
    <!-- MQTT 5.0 CONNACK capability knobs -->
    <property name="maximumQoS" value="2"/>
    <property name="retainAvailable" value="true"/>
    <property name="wildcardSubscriptionAvailable" value="true"/>
    <property name="subscriptionIdentifierAvailable" value="true"/>
    <property name="sharedSubscriptionAvailable" value="false"/>
    <property name="serverKeepAlive" value="-1"/>
</bean>

Test Client

I've provided a Paho test client here for getting up-to-speed quicker (legacy).

To start the client:

java -jar org.eclipse.paho.mqtt.utility-1.0.2.jar

To enable the debug logs:

java -Djava.util.logging.config.file=./jsr47min.properties -jar org.eclipse.paho.mqtt.utility-1.0.2.jar

References

Paho Paho Github MQTT over QUIC