mosquitto-with-auth/readme.md

# Docker Image containing the Mosquitto MQTT Broker and the mosquitto-auth-plug

This project includes the mosquitto MQTT broker (https://github.com/eclipse/mosquitto, see also https://mosquitto.org/) and the mosquitto-auth-plug (https://github.com/jpmens/mosquitto-auth-plug, forked into https://github.com/wollud1969/mosquitto-auth-plug) as submodules.

Using Gitlab CI and a Dockerfile included in this project a Docker image based on Debian Linux is created.

Note, please: the author of mosquitto-auth-plug has archived his project because he don't want to be bothered concerning this software he is not longer using anymore. So, please, don't be tempted to send him questions again because you find this image useful but run into problems. Read the available resources first, finally you may contact me.


## Mosquitto MQTT Broker

The Mosquitto MQTT Broker in this Docker image is built beyond the default build configuration with websockets support.


## mosquitto-auth-plug

The mosquitto-auth-plug is build only with the MySQL/MariaDB backend. More than that I do not need at the moment.


## Running the container

The container exposed the ports 1883 (MQTT), 8883 (MQTT over SSL) and 9001 (MQTT over websockets). Only the configuration directory containing `mosquitto.conf` and friends is prepared as a volume.

All logging is send to `stdout`, so it can be inspected using `docker logs -f <mosquitto-container>`

To start the container a script is provided, which might need to adjusted to the actual environment:

    #!/bin/bash

    IMAGE=registry.gitlab.com/wolutator/mosquitto-with-auth:latest
    VOLUME=mosquitto-config

    docker volume inspect $VOLUME > /dev/null || docker volume create $VOLUME

    docker pull $IMAGE

    docker run \
    -d \
    --rm \
    -p1883:1883 \
    -p8883:8883 \
    -p9001:9001 \
    -v $VOLUME:/opt/etc/mosquitto \
    --link mariadb \
    --name mosquitto \
    $IMAGE

The container expects the main configuration file in the root of the volume named `mosquitto.conf`.

A very simple configuration, only supporting MQTT on port 1883 is:

    pid_file /var/run/mosquitto.pid
    log_dest stdout

    persistence false

    listener 1883
    protocol mqtt
    #allow_anonymous true
    allow_anonymous false

    auth_plugin /opt/lib/auth-plug.so
    auth_opt_backends mysql
    auth_opt_host mariadb
    auth_opt_port 3306
    auth_opt_dbname mosquittoauth
    auth_opt_user mosquittoauth
    auth_opt_pass xxx
    auth_opt_userquery SELECT pw FROM users WHERE username = '%s'
    auth_opt_aclquery SELECT topic FROM acls WHERE username = '%s' and rw >= %d

The required schema in the database is 

    CREATE TABLE users (
        id INTEGER AUTO_INCREMENT,
        username VARCHAR(25) NOT NULL,
        pw VARCHAR(128) NOT NULL,
        super INT(1) NOT NULL DEFAULT 0,
        PRIMARY KEY (id)
    );
    CREATE UNIQUE INDEX users_username ON users (username);

    CREATE TABLE acls (
        id INTEGER AUTO_INCREMENT,
        username VARCHAR(25) NOT NULL,
        topic VARCHAR(256) NOT NULL,
        rw INTEGER(1) NOT NULL DEFAULT 1,	-- 1: read-only, 2: read-write
        PRIMARY KEY (id)
        );
    CREATE UNIQUE INDEX acls_user_topic ON acls (username, topic(228));

The password is generated using the `np` tool provided by mosquitto-auth-plug, which is included in the image at `/opt/bin`. It can be used either within the container using `docker exec -it <mosquitto-container> /opt/bin/np`. You may also try to copy it from the container onto your Linux host. It should run, since it is only linked against typical Linux libraries, however, I wouldn't do that.

For further information consult the readme and the examples in the mosquitto-auth-plug project (https://github.com/jpmens/mosquitto-auth-plug or https://github.com/wollud1969/mosquitto-auth-plug).