# Technical Documentation: eclipse-mosquitto/mosquitto
> ℹ️ **Provenance:** Multi-Tier Ingestion · [CodeWiki Reference](https://codewiki.google/github.com/eclipse-mosquitto/mosquitto)
### Overview (`README.md`)
Eclipse Mosquitto
=================
Mosquitto is an open source implementation of a server for version 5.0, 3.1.1,
and 3.1 of the MQTT protocol. It also includes a C and C++ client library,
the `mosquitto_pub` `mosquitto_rr`, and `mosquitto_sub` utilities for
publishing and subscribing, and the `mosquitto_ctrl`, `mosquitto_signal`, and
`mosquitto_passwd` applications for helping administer the broker.
## Links
See the following links for more information on MQTT:
- Community page:
- MQTT v3.1.1 standard:
- MQTT v5.0 standard:
Mosquitto project information is available at the following locations:
- Main homepage:
- Find existing bugs or submit a new bug:
- Source code repository:
There is also a public test server available at
## Installing
See for details on installing binaries for
various platforms.
## Quick start
If you have installed a binary package the broker should have been started
automatically. If not, it can be started with a very basic configuration:
mosquitto
Then use `mosquitto_sub` to subscribe to a topic:
mosquitto_sub -t 'test/topic' -v
And to publish a message:
mosquitto_pub -t 'test/topic' -m 'hello world'
Note that starting the broker like this allows anonymous/unauthenticated access
but only from the local computer, so it's only really useful for initial testing.
If you want to have clients from another computer connect, you will need to
provide a configuration file. If you have installed from a binary package, you
will probably already have a configuration file at somewhere like
`/etc/mosquitto/mosquitto.conf`. If you've compiled from source, you can write
your config file then run as `mosquitto -c /path/to/mosquitto.conf`.
To start your config file you define a listener and you will need to think
about what authentication you require. It is not advised to run your broker
with anonymous access when it is publicly available.
For details on how to do this, look at the
[authentication methods](https://mosquitto.org/documentation/authentication-methods/)
available and the [dynamic security plugin](https://mosquitto.org/documentation/dynamic-security/).
## Documentation
Documentation for the broker, clients and client library API can be found in
the man pages, which are available online at . There
are also pages with an introduction to the features of MQTT, the
`mosquitto_passwd` utility for dealing with username/passwords, and a
description of the configuration file options available for the broker.
Detailed client library API documentation can be found at
## Building from source
To build from source the recommended route for end users is to download the
archive from .
On Windows and Mac, use `cmake` to build. On other platforms, just run `make`
to build. For Windows, see also `README-windows.md`.
If you are building from the git repository then the documentation will not
already be built. Use `make binary` to skip building the man pages, or install
`docbook-xsl` on Debian/Ubuntu systems.
### Build Dependencies
* cJSON - required
* c-ares (libc-ares-dev on Debian based systems) - optional, enable with
`WITH_SRV=yes`
* libedit - for mosquitto_ctrl interactive shell - optional, disable with
`WITH_EDITLINE=no`
* libmicrohttpd - for broker http api support - optional, disable with
`WITH_HTTP_API=no`
* openssl (libssl-dev on Debian based systems) - optional, disable with
`WITH_TLS=no`
* pthreads - for client library thread support. This is required to support the
`mosquitto_loop_start()` and `mosquitto_loop_stop()` functions. If compiled
without pthread support, the library isn't guaranteed to be thread safe.
* sqlite3 - for persistence support in the broker - optional, disable with
`WITH_SQLITE=no`
* uthash / utlist - bundled versions of these headers are provided, disable
their use with `WITH_BUNDLED_DEPS=no`
* xsltproc (xsltproc and docbook-xsl on Debian based systems) - only needed
when building from git sources - disable with `WITH_DOCS=no`
Equivalent options for enabling/disabling features are available when using the
CMake build. It is also possible to enable/disable building of specific plugins
in the CMake build.
### Building mosquitto - Using vcpkg
You can download and install mosquitto using the [vcpkg](https://github.com/Microsoft/vcpkg) dependency manager:
git clone https://github.com/Microsoft/vcpkg.git
cd vcpkg
./bootstrap-vcpkg.sh
./vcpkg integrate install
./vcpkg install mosquitto
The mosquitto port in vcpkg is kept up to date by Microsoft team members and
community contributors. If the version is out of date, please [create an issue
or pull request](https://github.com/Microsoft/vcpkg) on the vcpkg repository.
## Credits
Mosquitto was written by Roger Light . There have been
substantial contributions by other people in the community both in terms of
code and other help.
---
### Overview (`dashboard/README.md`)
### Simple web-based graphical user interface for Mosquitto
To develop UI locally.
1) Install tailwind:
```sh
npm -g install tailwindcss@3
```
2) Go into `src` and run tailwind to generate a CSS file based on tailwind classes used in `index.html`:
```sh
tailwindcss -i ./css/styles.css -o ./tailwind/styles.css
```
3) Run mosquitto http api mock
4) Change mosquitto api endponits in `src/consts.js`
5) Go into `src` and run a simple http server, e.g. `python3 -m http.server 3000`
Dependencies (in `src/lib` directory):
* chartjs 4.3.0 (https://cdnjs.com/libraries/Chart.js/4.3.0)
* chartjs-plugin-zoom 2.2.0 (https://cdnjs.com/libraries/chartjs-plugin-zoom)
* hammer.js 2.0.8 (https://cdnjs.com/libraries/hammer.js)
---
### Overview (`docker/README.md`)
# Docker Images
This directory contains Docker files for Mosquitto.
The `2.0` directory contains the latest version of Mosquitto for that
series, it uses libressl. The `2.0-openssl` directory is identical except that
it uses openssl instead of libressl, and enables TLS-PSK and TLS v1.3 cipher
support.
The `1.6` directory contains the version of Mosquitto based on the 1.6 branch.
It uses libressl. The `1.6-openssl` directory is identical except that it uses
openssl instead of libressl, and enables TLS-PSK support.
The `1.5` directory contains the version of Mosquitto based on the 1.5 branch.
It uses libressl. The `1.5-openssl` directory is identical except that it uses
openssl instead of libressl, and enables TLS-PSK support.
The `generic` directory contains a generic Dockerfile that can be used to build
arbitrary versions of Mosquitto based on the released tarballs as follows:
```
cd generic
docker build -t eclipse-mosquitto:1.5.1 --build-arg VERSION="1.5.1" .
docker run --rm -it eclipse-mosquitto:1.5.1
```
The `local` directory can be used to build an image based on the files in the
working directory by using `make localdocker` from the root of the repository.
---
### Overview (`plugins/README.md`)
# Plugins
This directory contains plugins for use with Mosquitto.
## Dynamic security
This is a fully functioning plugin that implements authentication and access
control, with configuration via a $CONTROL topic. See the readme in
dynamic-security for more information.
## Examples / Add properties
This is an **example** plugin that demonstrates adding MQTT v5 properties to
messages, and how to get client information.
## Examples / Authenticate by IP address
This is an **example** plugin that demonstrates a basic authentication callback
that allows clients based on their IP address. Password based authentication is
preferred over this very simple type of access control.
## Examples / Client lifetime stats
This is an **example** plugin that collects counts of how long client sessions
last, in different time buckets of 0, 1, 2, 5, 10, 20, 50, 100, 200, 500, 1k,
2k, 5k, 10k, 20k, 50k, 100k, 200k, 500k, 1M, 2M, 5M, 10M, 20M, 50M, 100M, 200M,
500M seconds. It periodically publishes the counts at
`$SYS/broker/client/lifetimes/`.
## Examples / Client properties
This is an **example** plugin that demonstrates some of the functions for
retrieving client information such as client id and username.
## Examples / Connection state
This is an **example** plugin to demonstrate the use of the connect and
disconnect events. It publishes messages to
$SYS/broker/connection/client//state for every client that connects
to the broker, to indicate the connection state of that client.
## Examples / Deferred authentication
This is an **example** plugin to demonstrate how a plugin can carry out
delayed basic authentication. This method should be used where the plugin
sends an authentication request to an external server so that if there is a
delay in getting a response it does not block the broker. The plugin may spawn
extra threads to handle the authentication requests, but the call to
`mosquitto_complete_basic_auth()` must happen in the main Mosquitto thread.
## Examples / Message timestamp
This is an **example** plugin to demonstrate how it is possible to attach MQTT
v5 properties to messages after they have been received, and before they are
sent on to subscribers.
This plugin attaches a user-property property to each message which contains
the ISO-8601 timestamp of the time the message was received by the broker. This
means it is possible for MQTT v5 clients to see how old a retained message is,
for example.
## Examples / Payload modification
This is an **example** plugin to demonstrate how it is possible to modify the
payload of messages after they have been received, and before they are sent on
to subscribers.
If you are considering using this feature, you should be very certain you have
verified the payload is the correct format before modifying it.
This plugin adds the text string "hello " to the beginning of each payload, so
with anything other than simple plain text messages it will corrupt the payload
contents.
## Examples / Payload size stats
This is an **example** plugin that collects counts of payload message sizes, in
time buckets of 0, 1, 2, 5, 10, 20, 50, 100, 200, 500, 1k, 2k, 5k, 10k, 20k,
50k, 100k, 200k, 500k, 1M, 2M, 5M, 10M, 20M, 50M, 100M, 200M, 500M bytes. It
periodically publishes the counts at `$SYS/broker/publish/sizes/`.
## Examples / Print IP on publish
This is an **example** plugin that prints out client ID and IP address of any
client that publishes on a particular topic.
## Examples / Topic modification
This is an **example** plugin to demonstrate how it is possible to modify the
topic of messages after they have been received, and before they are sent on
to subscribers.
This plugin removes the `/uplink` end part of topics that match the pattern
`device/+/data/uplink`, so devices publishing to `device/0001/data/uplink` will
effectively be publishing to `device/0001/data`.
## Examples / Wildcard temp
This is an **example** plugin that denies access to the `#` subscription topic
only. This prevents clients from discovering which topics are active and
reduces outgoing bandwidth. If clients connect with username `wildcard` and
subscribes to `#` they will be allowed 20 seconds of access, after which the
subscription will be silently removed.
---
### Overview (`www/README.md`)
This is the mosquitto website, it can be built with `nikola`:
`nikola build`
---
### Overview (`deps/picohttpparser/README.md`)
PicoHTTPParser
=============
Copyright (c) 2009-2014 [Kazuho Oku](https://github.com/kazuho), [Tokuhiro Matsuno](https://github.com/tokuhirom), [Daisuke Murase](https://github.com/typester), [Shigeo Mitsunari](https://github.com/herumi)
PicoHTTPParser is a tiny, primitive, fast HTTP request/response parser.
Unlike most parsers, it is stateless and does not allocate memory by itself.
All it does is accept pointer to buffer and the output structure, and setups the pointers in the latter to point at the necessary portions of the buffer.
The code is widely deployed within Perl applications through popular modules that use it, including [Plack](https://metacpan.org/pod/Plack), [Starman](https://metacpan.org/pod/Starman), [Starlet](https://metacpan.org/pod/Starlet), [Furl](https://metacpan.org/pod/Furl). It is also the HTTP/1 parser of [H2O](https://github.com/h2o/h2o).
Check out [test.c] to find out how to use the parser.
The software is dual-licensed under the Perl License or the MIT License.
Usage
-----
The library exposes four functions: `phr_parse_request`, `phr_parse_response`, `phr_parse_headers`, `phr_decode_chunked`.
### phr_parse_request
The example below reads an HTTP request from socket `sock` using `read(2)`, parses it using `phr_parse_request`, and prints the details.
```c
char buf[4096], *method, *path;
int pret, minor_version;
struct phr_header headers[100];
size_t buflen = 0, prevbuflen = 0, method_len, path_len, num_headers;
ssize_t rret;
while (1) {
/* read the request */
while ((rret = read(sock, buf + buflen, sizeof(buf) - buflen)) == -1 && errno == EINTR)
;
if (rret <= 0)
return IOError;
prevbuflen = buflen;
buflen += rret;
/* parse the request */
num_headers = sizeof(headers) / sizeof(headers[0]);
pret = phr_parse_request(buf, buflen, &method, &method_len, &path, &path_len,
&minor_version, headers, &num_headers, prevbuflen);
if (pret > 0)
break; /* successfully parsed the request */
else if (pret == -1)
return ParseError;
/* request is incomplete, continue the loop */
assert(pret == -2);
if (buflen == sizeof(buf))
return RequestIsTooLongError;
}
printf("request is %d bytes long\n", pret);
printf("method is %.*s\n", (int)method_len, method);
printf("path is %.*s\n", (int)path_len, path);
printf("HTTP version is 1.%d\n", minor_version);
printf("headers:\n");
for (i = 0; i != num_headers; ++i) {
printf("%.*s: %.*s\n", (int)headers[i].name_len, headers[i].name,
(int)headers[i].value_len, headers[i].value);
}
```
### phr_parse_response, phr_parse_headers
`phr_parse_response` and `phr_parse_headers` provide similar interfaces as `phr_parse_request`. `phr_parse_response` parses an HTTP response, and `phr_parse_headers` parses the headers only.
### phr_decode_chunked
The example below decodes incoming data in chunked-encoding. The data is decoded in-place.
```c
struct phr_chunked_decoder decoder = {}; /* zero-clear */
char *buf = malloc(4096);
size_t size = 0, capacity = 4096, rsize;
ssize_t rret, pret;
/* set consume_trailer to 1 to discard the trailing header, or the application
* should call phr_parse_headers to parse the trailing header */
decoder.consume_trailer = 1;
do {
/* expand the buffer if necessary */
if (size == capacity) {
capacity *= 2;
buf = realloc(buf, capacity);
assert(buf != NULL);
}
/* read */
while ((rret = read(sock, buf + size, capacity - size)) == -1 && errno == EINTR)
;
if (rret <= 0)
return IOError;
/* decode */
rsize = rret;
pret = phr_decode_chunked(&decoder, buf + size, &rsize);
if (pret == -1)
return ParseError;
size += rsize;
} while (pret == -2);
/* successfully decoded the chunked data */
assert(pret >= 0);
printf("decoded data is at %p (%zu bytes)\n", buf, size);
```
Benchmark
---------
The benchmark code is from [fukamachi/fast-http@6b91103](https://github.com/fukamachi/fast-http/tree/6b9110347c7a3407310c08979aefd65078518478).
The internals of picohttpparser has been described to some extent in [my blog entry]( http://blog.kazuhooku.com/2014/11/the-internals-h2o-or-how-to-write-fast.html).
---
### Overview (`docker/1.6-openssl/README.md`)
# Eclipse Mosquitto Docker Image
Containers built with this Dockerfile build as source from published tarballs.
## Mount Points
A docker mount point has been created in the image to be used for configuration.
```
/mosquitto/config
```
Two docker volumes have been created in the image to be used for persistent storage and logs.
```
/mosquitto/data
/mosquitto/log
```
## User/Group
The image runs mosquitto under the mosquitto user and group, which are created
with a uid and gid of 1883.
## Configuration
When creating a container from the image, the default configuration values are used.
To use a custom configuration file, mount a **local** configuration file to `/mosquitto/config/mosquitto.conf`
```
docker run -it -p 1883:1883 -v :/mosquitto/config/mosquitto.conf eclipse-mosquitto:
```
:boom: if the mosquitto configuration (mosquitto.conf) was modified
to use non-default ports, the docker run command will need to be updated
to expose the ports that have been configured, for example:
```
docker run -it -p 1883:1883 -p 8080:8080 -v :/mosquitto/config/mosquitto.conf eclipse-mosquitto:
```
Configuration can be changed to:
* persist data to `/mosquitto/data`
* log to `/mosquitto/log/mosquitto.log`
i.e. add the following to `mosquitto.conf`:
```
persistence true
persistence_location /mosquitto/data/
log_dest file /mosquitto/log/mosquitto.log
```
**Note**: For any volume used, the data will be persistent between containers.
---
### Overview (`docker/2.0-openssl/README.md`)
# Eclipse Mosquitto Docker Image
Containers built with this Dockerfile build as source from published tarballs.
## Mount Points
A docker mount point has been created in the image to be used for configuration.
```
/mosquitto/config
```
Two docker volumes have been created in the image to be used for persistent storage and logs.
```
/mosquitto/data
/mosquitto/log
```
## User/Group
The image runs mosquitto under the mosquitto user and group, which are created
with a uid and gid of 1883.
## Running without a configuration file
Mosquitto 2.0 requires you to configure listeners and authentication before it
will allow connections from anything other than the loopback interface. In the
context of a container, this means you would normally need to provide a
configuration file with your settings.
If you wish to run mosquitto without any authentication, and without setting
any other configuration options, you can do so by using a configuration
provided in the container for this purpose:
```
docker run -it -p 1883:1883 eclipse-mosquitto: mosquitto -c /mosquitto-no-auth.conf
```
## Configuration
To use a custom configuration file, mount a **local** configuration file to `/mosquitto/config/mosquitto.conf`
```
docker run -it -p 1883:1883 -v :/mosquitto/config/mosquitto.conf eclipse-mosquitto:
```
Your configuration file must include a `listener`, and you must configure some
form of authentication or allow unauthenticated access. If you do not do this,
clients will be unable to connect.
File based authentication and authorisation:
```
listener 1883
password_file /mosquitto/data/mosquitto.password_file
acl_file /mosquitto/data/mosquitto.aclfile
```
Plugin based authentication and authorisation:
```
listener 1883
plugin /usr/lib/mosquitto_dynamic_security.so
plugin_opt_config_file /mosquitto/data/mosquitto-dynsec.json
```
Unauthenticated access:
```
listener 1883
allow_anonymous true
```
:boom: if the mosquitto configuration (mosquitto.conf) was modified
to use non-default ports, the docker run command will need to be updated
to expose the ports that have been configured, for example:
```
docker run -it -p 1883:1883 -p 8080:8080 -v :/mosquitto/config/mosquitto.conf eclipse-mosquitto:
```
**Important**: The default configuration only listens on the loopback
interface. This means that there is no way to access Mosquitto in the docker
container without using a custom configuration containing at least a listener.
You also need to make a decision to allow anonymous connections or to set up a
different method of client authentication.
i.e. to configure a Mosquitto docker container as if it was running locally,
add the following to `mosquitto.conf`:
```
listener 1883
allow_anonymous true
```
Configuration can be changed to:
* persist data to `/mosquitto/data`
* log to `/mosquitto/log/mosquitto.log`
i.e. add the following to `mosquitto.conf`:
```
persistence true
persistence_location /mosquitto/data/
log_dest file /mosquitto/log/mosquitto.log
```
**Note**: For any volume used, the data will be persistent between containers.
---
### Overview (`docker/2.1-alpine/README.md`)
# Eclipse Mosquitto Docker Image
Containers built with this Dockerfile build as source from published tarballs.
## Mount Points
A docker mount point has been created in the image to be used for configuration.
```
/mosquitto/config
```
Two docker volumes have been created in the image to be used for persistent storage and logs.
```
/mosquitto/data
/mosquitto/log
```
## User/Group
The image runs mosquitto under the mosquitto user and group, which are created
with a uid and gid of 1883.
## Running without a configuration file
Mosquitto 2.0 and up requires you to configure listeners and authentication
before it will allow connections from anything other than the loopback
interface. In the context of a container, this means you would normally need to
provide a configuration file with your settings.
However, this container provides a default configuration which listens on port
1883 for unauthenticated access, and port 9883 for the local http dashboard.
If you wish to run mosquitto without any authentication, and without setting
any other configuration options, you can run without a configuration by binding
the appropriate network ports:
```
docker run -it -p 1883:1883 -p localhost:9883:9883 eclipse-mosquitto:
```
## Configuration
To use a custom configuration file, create a **local** config directory with a
mosquitto.conf inside, then mount this directory to `/mosquitto/config`
```
docker run -it -p 1883:1883 -v :/mosquitto/config eclipse-mosquitto:
```
Your configuration file must include a `listener`, and you must configure some
form of authentication or allow unauthenticated access. If you do not do this,
clients will be unable to connect.
File based authentication and authorisation:
```
listener 1883
plugin /usr/lib/mosquitto_password_file.so
plugin_opt_password_file /mosquitto/data/mosquitto.password_file
plugin /usr/lib/mosquitto_acl_file.so
plugin_opt_acl_file /mosquitto/data/mosquitto.aclfile
```
Plugin based authentication and authorisation:
```
listener 1883
plugin /usr/lib/mosquitto_dynamic_security.so
plugin_opt_config_file /mosquitto/data/mosquitto-dynsec.json
```
Unauthenticated access:
```
listener 1883
allow_anonymous true
```
:boom: if the mosquitto configuration (mosquitto.conf) was modified
to use non-default ports, the docker run command will need to be updated
to expose the ports that have been configured, for example:
```
docker run -it -p 1883:1883 -p 8080:8080 -v :/mosquitto/config eclipse-mosquitto:
```
Configuration can be changed to:
* persist data to `/mosquitto/data`
* log to `/mosquitto/log/mosquitto.log`
i.e. add the following to `mosquitto.conf`:
```
persistence_location /mosquitto/data/
plugin /usr/lib/mosquitto_persist_sqlite.so
log_dest file /mosquitto/log/mosquitto.log
```
**Note**: For any volume used, the data will be persistent between containers.
---
### Overview (`docker/2.1-ubuntu/README.md`)
# Eclipse Mosquitto Docker Image
Containers built with this Dockerfile build as source from published tarballs.
## Mount Points
A docker mount point has been created in the image to be used for configuration.
```
/mosquitto/config
```
Two docker volumes have been created in the image to be used for persistent storage and logs.
```
/mosquitto/data
/mosquitto/log
```
## User/Group
The image runs mosquitto under the mosquitto user and group, which are created
with a uid and gid of 1883.
## Running without a configuration file
Mosquitto 2.0 and up requires you to configure listeners and authentication
before it will allow connections from anything other than the loopback
interface. In the context of a container, this means you would normally need to
provide a configuration file with your settings.
However, this container provides a default configuration which listens on port
1883 for unauthenticated access, and port 9883 for the local http dashboard.
If you wish to run mosquitto without any authentication, and without setting
any other configuration options, you can run without a configuration by binding
the appropriate network ports:
```
docker run -it -p 1883:1883 -p localhost:9883:9883 eclipse-mosquitto:
```
## Configuration
To use a custom configuration file, create a **local** config directory with a
mosquitto.conf inside, then mount this directory to `/mosquitto/config`
```
docker run -it -p 1883:1883 -v :/mosquitto/config eclipse-mosquitto:
```
Your configuration file must include a `listener`, and you must configure some
form of authentication or allow unauthenticated access. If you do not do this,
clients will be unable to connect.
File based authentication and authorisation:
```
listener 1883
plugin /usr/lib/mosquitto_password_file.so
plugin_opt_password_file /mosquitto/data/mosquitto.password_file
plugin /usr/lib/mosquitto_acl_file.so
plugin_opt_acl_file /mosquitto/data/mosquitto.aclfile
```
Plugin based authentication and authorisation:
```
listener 1883
plugin /usr/lib/mosquitto_dynamic_security.so
plugin_opt_config_file /mosquitto/data/mosquitto-dynsec.json
```
Unauthenticated access:
```
listener 1883
allow_anonymous true
```
:boom: if the mosquitto configuration (mosquitto.conf) was modified
to use non-default ports, the docker run command will need to be updated
to expose the ports that have been configured, for example:
```
docker run -it -p 1883:1883 -p 8080:8080 -v :/mosquitto/config eclipse-mosquitto:
```
Configuration can be changed to:
* persist data to `/mosquitto/data`
* log to `/mosquitto/log/mosquitto.log`
i.e. add the following to `mosquitto.conf`:
```
persistence_location /mosquitto/data/
plugin /usr/lib/mosquitto_persist_sqlite.so
log_dest file /mosquitto/log/mosquitto.log
```
**Note**: For any volume used, the data will be persistent between containers.
---
### Overview (`docker/generic/README.md`)
# Eclipse Mosquitto Docker Image
Containers built with this Dockerfile build as source from published tarballs.
## Mount Points
A docker mount point has been created in the image to be used for configuration.
```
/mosquitto/config
```
Two docker volumes have been created in the image to be used for persistent storage and logs.
```
/mosquitto/data
/mosquitto/log
```
## User/Group
The image runs mosquitto under the mosquitto user and group, which are created
with a uid and gid of 1883.
## Running without a configuration file
Mosquitto 2.0 requires you to configure listeners and authentication before it
will allow connections from anything other than the loopback interface. In the
context of a container, this means you would normally need to provide a
configuration file with your settings.
If you wish to run mosquitto without any authentication, and without setting
any other configuration options, you can do so by using a configuration
provided in the container for this purpose:
```
docker run -it -p 1883:1883 eclipse-mosquitto: mosquitto -c /mosquitto-no-auth.conf
```
## Configuration
When creating a container from the image, the default configuration values are used.
To use a custom configuration file, mount a **local** configuration file to `/mosquitto/config/mosquitto.conf`
```
docker run -it -p 1883:1883 -v :/mosquitto/config/mosquitto.conf eclipse-mosquitto:
```
Configuration can be changed to:
* persist data to `/mosquitto/data`
* log to `/mosquitto/log/mosquitto.log`
i.e. add the following to `mosquitto.conf`:
```
persistence true
persistence_location /mosquitto/data/
log_dest file /mosquitto/log/mosquitto.log
```
**Note**: For any volume used, the data will be persistent between containers.
## Build
Build and tag the docker image for a specific version:
```
docker build -t eclipse-mosquitto: --build-arg VERSION="" .
```
## Run
Run a container using the new image:
```
docker run -it -p 1883:1883 -v :/mosquitto/config/mosquitto.conf -v /mosquitto/data -v /mosquitto/log eclipse-mosquitto:
```
:boom: if the mosquitto configuration (mosquitto.conf) was modified
to use non-default ports, the docker run command will need to be updated
to expose the ports that have been configured.
**Important**: The default configuration only listens on the
loopback interface. This means that there is no way to access Mosquitto in the
docker container without using a custom configuration containing at least
a listener. You also need to make a decision to allow anonymous connections or
to set up a different method of client authentication.
i.e. to configure a Mosquitto docker container as if it was running locally,
add the following to `mosquitto.conf`:
```
listener 1883
allow_anonymous true
```
---
### Overview (`docker/local/README.md`)
# Eclipse Mosquitto Docker Image
Containers built with this Dockerfile build from a source tarball "mosq.tar.gz"
placed in the local directory. Running `make localdocker` from the root of the
repository will generate the source tar and build the docker image.
## Mount Points
A docker mount point has been created in the image to be used for configuration.
```
/mosquitto/config
```
Two docker volumes have been created in the image to be used for persistent storage and logs.
```
/mosquitto/data
/mosquitto/log
```
## User/Group
The image runs mosquitto under the mosquitto user and group, which are created
with a uid and gid of 1883.
## Configuration
When creating a container from the image, the default configuration values are used.
To use a custom configuration file, mount a **local** configuration file to `/mosquitto/config/mosquitto.conf`
```
docker run -it -p 1883:1883 -v :/mosquitto/config/mosquitto.conf eclipse-mosquitto:
```
:boom: if the mosquitto configuration (mosquitto.conf) was modified
to use non-default ports, the docker run command will need to be updated
to expose the ports that have been configured, for example if you use port 8080
for websockets as well as port 1883:
```
docker run -it -p 1883:1883 -p 8080:8080 -v :/mosquitto/config/mosquitto.conf eclipse-mosquitto:
```
Configuration can be changed to:
* persist data to `/mosquitto/data`
* log to `/mosquitto/log/mosquitto.log`
i.e. add the following to `mosquitto.conf`:
```
persistence true
persistence_location /mosquitto/data/
log_dest file /mosquitto/log/mosquitto.log
```
**Note**: For any volume used, the data will be persistent between containers.
---
### Overview (`plugins/dynamic-security/README.md`)
# Mosquitto Dynamic Security
This document describes a topic based mechanism for controlling security in
Mosquitto. JSON commands are published to topics like `$CONTROL//v1`
## Clients
When a client connects to Mosquitto, it can optionally provide a username. The
username maps the client instance to a client on the broker, if it exists.
Multiple clients can make use of the same username, and hence the same broker
client.
## Groups
Broker clients can be defined as belonging to zero or more broker groups.
## Roles
Roles can be applied to a client or a group, and define what that client/group
is allowed to do, for example what topics it may or may not publish or
subscribe to.
## Commands
### Set default ACL access
Sets the default access behaviour for the different ACL types, assuming there
are no matching ACLs for a topic.
By default, publishClientSend and subscribe default to deny, and
publishClientReceive and unsubscribe default to allow.
Command:
```
{
"commands":[
{
"command": "setDefaultACLAccess",
"acls":[
{ "acltype": "publishClientSend", "allow": false },
{ "acltype": "publishClientReceive", "allow": true },
{ "acltype": "subscribe", "allow": false },
{ "acltype": "unsubscribe", "allow": true }
]
}
]
}
```
mosquitto_ctrl example:
```
mosquitto_ctrl dynsec setDefaultACLAccess subscribe deny
```
### Get default ACL access
Gets the default access behaviour for the different ACL types.
Command:
```
{
"commands":[
{
"command": "getDefaultACLAccess"
}
]
}
```
mosquitto_ctrl example:
```
mosquitto_ctrl dynsec getDefaultACLAccess
```
## Create Client
Command:
```
{
"commands":[
{
"command": "createClient",
"username": "new username",
"password": "new password",
"clientid": "", # Optional
"textname": "", # Optional
"textdescription": "", # Optional
"groups": [
{ "groupname": "group", "priority": 1 }
], # Optional, groups must exist
"roles": [
{ "rolename": "role", "priority": -1 }
] # Optional, roles must exist
}
]
}
```
mosquitto_ctrl example:
```
mosquitto_ctrl dynsec createClient username password
```
## Delete Client
Command:
```
{
"commands":[
{
"command": "deleteClient",
"username": "username to delete"
}
]
}
```
mosquitto_ctrl example:
```
mosquitto_ctrl dynsec deleteClient username
```
## Enable Client
Command:
```
{
"commands":[
{
"command": "enableClient",
"username": "username to enable"
}
]
}
```
mosquitto_ctrl example:
```
mosquitto_ctrl dynsec enableClient username
```
## Disable Client
Stop a client from being able to log in, and kick any clients with matching
username that are currently connected.
Command:
```
{
"commands":[
{
"command": "disableClient",
"username": "username to disable"
}
]
}
```
mosquitto_ctrl example:
```
mosquitto_ctrl dynsec disableClient username
```
## Get Client
Command:
```
{
"commands":[
{
"command": "getClient",
"username": "required username"
}
]
}
```
mosquitto_ctrl example:
```
mosquitto_ctrl dynsec getClient username
```
## List Clients
Command:
```
{
"commands":[
{
"command": "listClients",
"verbose": false,
"count": -1, # -1 for all, or a positive integer for a limited count
"offset": 0 # Where in the list to start
}
]
}
```
mosquitto_ctrl example:
```
mosquitto_ctrl dynsec listClients 10 20
```
## Modify Existing Client
Command:
```
{
"commands":[
{
"command": "modifyClient",
"username": "username to modify"
"clientid": "new clientid, or empty string to clear", # Optional
"password": "new password", # Optional
"textname": "", # Optional
"textdescription": "", # Optional
"roles": [
{ "rolename": "role", "priority": 1 }
], # Optional
"groups": [
{ "groupname": "group", "priority": 1 }
], # Optional
}
]
}
```
Modifying clients isn't currently possible with mosquitto_ctrl.
## Set Client id
Command:
```
{
"commands":[
{
"command": "setClientId",
"username": "username to change",
"clientid": "new clientid" # Optional, if blank or missing then client id will be removed.
}
]
}
```
mosquitto_ctrl example:
```
mosquitto_ctrl dynsec setClientId username clientId
```
## Set Client Password
Command:
```
{
"commands":[
{
"command": "setClientPassword",
"username": "username to change",
"password": "new password"
}
]
}
```
mosquitto_ctrl example:
```
mosquitto_ctrl dynsec setClientPassword username password
```
## Add Client Role
Command:
```
{
"commands":[
{
"command": "addClientRole",
"username": "client to add role to",
"rolename": "role to add",
"priority": -1 # Optional priority
}
]
}
```
mosquitto_ctrl example:
```
mosquitto_ctrl dynsec addClientRole username rolename
```
## Remove Client Role
Command:
```
{
"commands":[
{
"command": "removeClientRole",
"username": "client to remove role from",
"rolename": "role to remove"
}
]
}
```
mosquitto_ctrl example:
```
mosquitto_ctrl dynsec removeClientRole username rolename
```
## Add Client to a Group
Command:
```
{
"commands":[
{
"command": "addGroupClient",
"groupname": "group to add client to",
"username": "client to add to group",
"priority": -1 # Priority of the group for the client
}
]
}
```
mosquitto_ctrl example:
```
mosquitto_ctrl dynsec addGroupClient groupname username
```
## Create Group
Command:
```
{
"commands":[
{
"command": "createGroup",
"groupname": "new group",
"roles": [
{ "rolename": "role", "priority": 1 }
] # Optional, roles must exist
}
]
}
```
mosquitto_ctrl example:
```
mosquitto_ctrl dynsec createGroup groupname
```
## Delete Group
Command:
```
{
"commands":[
{
"command": "deleteGroup",
"groupname: "group to delete"
}
]
}
```
mosquitto_ctrl example:
```
mosquitto_ctrl dynsec deleteGroup groupname
```
## Get Group
Command:
```
{
"commands":[
{
"command": "getGroup",
"groupname: "group to get"
}
]
}
```
mosquitto_ctrl example:
```
mosquitto_ctrl dynsec getGroup groupname
```
## List Groups
Command:
```
{
"commands":[
{
"command": "listGroups",
"verbose": false,
"count": -1, # -1 for all, or a positive integer for a limited count
"offset": 0 # Where in the list to start
}
]
}
```
mosquitto_ctrl example:
```
mosquitto_ctrl dynsec listGroups
```
## Modify Group
Command:
```
{
"commands":[
{
"command": "modifyGroup",
"groupname": "group to modify",
"textname": "", # Optional
"textdescription": "", # Optional
"roles": [
{ "rolename": "role", "priority": 1 }
], # Optional
"clients": [
{ "username": "client", "priority": 1 }
] # Optional
}
]
}
```
Modifying groups isn't currently possible with mosquitto_ctrl.
## Remove Client from a Group
Command:
```
{
"commands":[
{
"command": "removeGroupClient",
"groupname": "group to remove client from",
"username": "client to remove from group"
}
]
}
```
mosquitto_ctrl example:
```
mosquitto_ctrl dynsec removeGroupClient groupname username
```
## Add Group Role
Command:
```
{
"commands":[
{
"command": "addGroupRole",
"groupname": "group to add role to",
"rolename": "role to add",
"priority": -1 # Optional priority
}
]
}
```
mosquitto_ctrl example:
```
mosquitto_ctrl dynsec addGroupRole groupname rolename
```
## Remove Group Role
Command:
```
{
"commands":[
{
"command": "removeGroupRole",
"groupname": "group",
"rolename": "role"
}
]
}
```
mosquitto_ctrl example:
```
mosquitto_ctrl dynsec removeGroupRole groupname rolename
```
## Set Group for Anonymous Clients
Command:
```
{
"commands":[
{
"command": "setAnonymousGroup",
"groupname": "group"
}
]
}
```
mosquitto_ctrl example:
```
mosquitto_ctrl dynsec setAnonymousGroup groupname
```
## Get Group for Anonymous Clients
Command:
```
{
"commands":[
{
"command": "getAnonymousGroup"
}
]
}
```
mosquitto_ctrl example:
```
mosquitto_ctrl dynsec getAnonymousGroup
```
## Create Role
Command:
```
{
"commands":[
{
"command": "createRole",
"rolename": "new role",
"textname": "", # Optional
"textdescription": "", # Optional
"acls": [
{ "acltype": "subscribePattern", "topic": "topic/#", "priority": -1, "allow": true}
] # Optional
}
]
}
```
mosquitto_ctrl example:
```
mosquitto_ctrl dynsec createRole rolename
```
## Get Role
Command:
```
{
"commands":[
{
"command": "getRole",
"rolename": "role",
}
]
}
```
mosquitto_ctrl example:
```
mosquitto_ctrl dynsec getRole rolename
```
## List Roles
Command:
```
{
"commands":[
{
"command": "listRoles",
"verbose": false,
"count": -1, # -1 for all, or a positive integer for a limited count
"offset": 0 # Where in the list to start
}
]
}
```
mosquitto_ctrl example:
```
mosquitto_ctrl dynsec listRoles
```
## Modify Role
Command:
```
{
"commands":[
{
"command": "modifyRole",
"rolename": "role to modify"
"textname": "", # Optional
"textdescription": "", # Optional
"acls": [
{ "acltype": "subscribePattern", "topic": "topic/#", "priority": -1, "allow": true }
] # Optional
}
]
}
```
Modifying roles isn't currently possible with mosquitto_ctrl.
## Delete Role
Command:
```
{
"commands":[
{
"command": "deleteRole",
"rolename": "role"
}
]
}
```
mosquitto_ctrl example:
```
mosquitto_ctrl dynsec deleteRole rolename
```
## Add Role ACL
Command:
```
{
"commands":[
{
"command": "addRoleACL",
"rolename": "role",
"acltype": "subscribePattern",
"topic": "topic/#",
"priority": -1,
"allow": true
}
]
}
```
mosquitto_ctrl example:
```
mosquitto_ctrl dynsec addRoleACL rolename subscribeLiteral topic/# deny
```
## Remove Role ACL
Command:
```
{
"commands":[
{
"command": "removeRoleACL",
"rolename": "role",
"acltype": "subscribePattern",
"topic": "topic/#"
}
]
}
```
mosquitto_ctrl example:
```
mosquitto_ctrl dynsec removeRoleACL rolename subscribeLiteral topic/#
```
---
### Overview (`plugins/sparkplug-aware/README.md`)
# Mosquitto Sparkplug Aware
This plugin implements the requirements of the Sparkplug 3.0 specification
"awareness".
It is not tested with the official TCK, because that is only capable of testing
one brand of broker, and hence it is not possible to validate any other broker.
See https://github.com/eclipse-sparkplug/sparkplug/issues/478
---
### Doc Historical Old Regex (`doc/historical/old-regex.txt`)
This is the description of the regex used previously for topic/subscription
matching. It is reproduced here for posterity.
When a message is ready to be published at the broker, we need to check all
of the subscriptions to see which ones the message should be sent to. This
would be easy without wildcards, but requires a bit more work with them.
The regex used to do the matching is of the form below for a topic of a/b/c:
^(?:(?:(a|\+)(?!$))(?:(?:/(?:(b|\+)(?!$)))(?:(?:/(?:c|\+))|/#)?|/#)?|#)$
In general, we're matching (a or +) followed by (the next levels of
hierarchy or #).
More specifically, all the levels of hierarchy must match, unless the last
level is #.
^(?: # Must start at beginning of string
(?: # (Level 1 hierarchy)
(a|\+)(?!$) # Match a or +, but only if not EOL.
) # AND
(?:
(?: # (Level 2 hierarchy)
/ # Match /
(?: # AND
(b|\+)(?!$) # Match b or +, but only if not EOL.
)
) # AND
(?:
(?: # (Level 3 hierarchy)
/ # Match /
(?: # AND
c|\+ # Match c or +.
)
)
| # OR (instead of level 3)
/# # Match /# at level 3
)? # Level 3 exist 1/0 times
| # OR (instead of level 2)
/# # Match /# at level 2
)? # Level 2 exist 1/0 times
| # OR (instead of level 1)
# # Match # at level 1
)$ # Must end on EOL.
---
### Doc Joss Paper Codemeta.Json (`doc/joss-paper/codemeta.json`)
{
"@context": "https://raw.githubusercontent.com/codemeta/codemeta/master/codemeta.jsonld",
"@type": "Code",
"author": [
{
"@id": "http://orcid.org/0000-0001-9218-7797",
"@type": "Person",
"email": "",
"name": "Roger A. Light",
"affiliation": ""
}
],
"identifier": "",
"codeRepository": "https://github.com/eclipse/mosquitto",
"datePublished": "2017-05-17",
"dateModified": "2017-05-17",
"dateCreated": "2017-05-17",
"description": "Broker and client implementation of the MQTT protocol.",
"keywords": "IoT, MQTT, messaging, pubsub",
"license": "EPL 2.0 / EDL 2.0",
"title": "Mosquitto",
"version": "v1.4.11"
}
---
### Doc Joss Paper Paper (`doc/joss-paper/paper.md`)
---
title: 'Mosquitto: server and client implementation of the MQTT protocol'
tags:
- Internet of Things
- MQTT
- Pubsub
- Messaging
authors:
- name: Roger A Light
orcid: 0000-0001-9218-7797
date: 17 May 2017
bibliography: paper.bib
---
# Summary
Mosquitto provides standards compliant server and client implementations of the
[MQTT](http://mqtt.org/) messaging protocol. MQTT uses a publish/subscribe
model, has low network overhead and can be implemented on low power devices
such microcontrollers that might be used in remote Internet of Things sensors.
As such, Mosquitto is intended for use in all situations where there is a need
for lightweight messaging, particularly on constrained devices with limited
resources.
The Mosquitto project is a member of the [Eclipse Foundation](http://eclipse.org/)
There are three parts to the project.
* The main `mosquitto` server
* The `mosquitto_pub` and `mosquitto_sub` client utilities that are one method of communicating with an MQTT server
* An MQTT client library written in C, with a C++ wrapper
Mosquitto allows research directly related to the MQTT protocol itself, such as
comparing the performance of MQTT and the Constrained Application Protocol
(CoAP) [@Thangavel_2014] or investigating the use of OAuth in MQTT
[@Fremantle_2014]. Mosquitto supports other research activities as a useful
block for building larger systems and has been used to evaluate MQTT for use in
Smart City Services [@Antonic_2015], and in the development of an environmental
monitoring system [@Bellavista_2017]. Mosquitto has also been used to support
research less directly as part of a scheme for remote control of an experiment
[@Schulz_2014].
Outside of academia, Mosquitto is used in other open source projects such as
the [openHAB](http://www.openhab.org/) home automation project and
[OwnTracks](http://owntracks.org/), the personal location tracking project, and
has been integrated into commercial products.
# References
---
--- METRICS ---
- Files Extracted: 17
- Estimated Token Budget: ~11589 tokens
- Canonical Reference: https://codewiki.google/github.com/eclipse-mosquitto/mosquitto