## Prerequisite ### My Environment - Ubuntu Server 24.04 - Eclipse Mosquitto v2.0.21 , I use official docker image - Docker 28.0.4 ##### Important Note > - docker commands may require superuser privilege > - each mosquitto container internally creates a user with UID 1883 once started. ## Configuration ### minimal configuration sample ```bash! persistence true persistence_location /mosquitto/data/ log_dest file /mosquitto/log/run-with-myapp.log log_type debug log_timestamp_format %Y-%m-%dT%H:%M:%S # or port 1883 for non-secure connection listener 8883 allow_anonymous false # the file has to exist password_file /mosquitto/config/password-custom # --- Access Control List (ACL) Settings --- # Enable ACL file (if not already enabled) # the file has to exist acl_file /mosquitto/config/acl.conf ``` **CAUTION / FIXME** All file paths referenced inside the container must exist. If any required path is missing, the Docker container will fail and exit silently — without showing any error messages (except the exit code, but not really helpful for troubleshooting), even if all debugging options are enabled on docker side and mosquitto side. ### Configuration for secure connection ```bash! tls_version tlsv1.3 tls_keyform pem # for 2-way authentication require_certificate true # list of CA certificates bundled in one single file # , not just a single CA cert for broker cafile /mosquitto/config/mq-ca-crt-list.pem certfile /mosquitto/config/mq-broker-crt.pem keyfile /mosquitto/config/mq-broker-privkey.pem ``` ## Frequently Used Docker Commands For detail explanation of docker commands please read [Basic Docker Setup Note](https://hackmd.io/@0V3cv8JJRnuK3jMwbJ-EeA/B14K831Dxe) ### First time to create / run the container ```bash! docker --debug run --interactive --tty --publish 1883:8883 --volume "$PWD/mosquitto/config:/mosquitto/config" --volume "$PWD/mosquitto/data:/mosquitto/data" --volume "$PWD/mosquitto/log:/mosquitto/log" --name <CONTAINER_NAME> eclipse-mosquitto:2-openssl ``` > Remind that I use official docker image which exposes ONLY the port `1883` to external world, the port for accessing the application within the container is `8883`, the initial command `docker run` should include the option `--publish 1883:8883`. > - (TODO) maybe I should create my own images - note mosquitto container will create user with UID 1883 as default user, for running commands in the container - the persisted files outside container will have owner with strange UID 1883 due to this user inside container ### Interactive shell environment within the container Once users enter interactive shell environment for the container (by the command `docker exec --interactive --tty`), they can run the commands / tools provided in the container, such as mosquitto utilities like `mosquitto_passwd`, `mosquitto_pub`, and `mosquitto_sub` ## mosquitto authorization > the commands in this section should be run inside a container ### user password setup ```bash! # create a new user, then it will prompt password confirmation mosquitto_passwd -H sha512 /mosquitto/config/passwd_custom <USERNAME_FOR_BROKER> # delete an existing user mosquitto_passwd -H sha512 -D /mosquitto/config/passwd_custom <USERNAME_FOR_BROKER> ``` ## mosquitto basic operations ### message publish / subscribe ```bash! mosquitto_pub -h <IP_OR_DOMAIN> -p 1883 -V mqttv5 -k 73 -u <USERNAME_FOR_BROKER> -P <PASSWORD_FOR_BROKER> -t <ANY_VALID_TOPIC> -m <MSG_PAYLOAD_CHARS> ``` ```shell! mosquitto_sub -h <IP_OR_DOMAIN> -p 1883 -V mqttv5 -k 65 -u <USERNAME_FOR_BROKER> -P <PASSWORD_FOR_BROKER> -t <ANY_VALID_TOPIC> ``` - current loopback and local network (192.168.x.x) should work - TODO, setup real domain name and TLS connection #### Enable secure connection following options should be added to `mosquitto_sub` or `mosquitto_pub` , note server certificate verification (a.k.a one-way authentication) is always enabled if TLS handshake agrees to use certificate. - `--tls-version`, latest version is `tlsv1.3` - `--cafile path/to/ca-cert-for-server.pem` Add extra options below for client certificate verification (a.k.a [two-way authentication or mutual authentication](https://en.wikipedia.org/wiki/Mutual_authentication)) - `--cert /path/to/client-cert-if-server-ask.pem` - `--key /path/to/client-privkey-if-server-ask.pem` ## Reference - [Cedalo - How to Configure Mosquitto MQTT Broker in Docker](https://cedalo.com/blog/mosquitto-docker-configuration-ultimate-guide/?utm_source=chatgpt.com) - [`mosquitto.conf` man page](https://mosquitto.org/man/mosquitto-conf-5.html) - [Tencent Cloud -- SSL One-Way Authentication and Mutual Authentication](https://www.tencentcloud.com/document/product/214/39990)