mosquitto Documentation

Technical Documentation: eclipse-mosquitto/mosquitto

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

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 Copy Chapter

See the following links for more information on MQTT:

• Community page: http://mqtt.org/
• MQTT v3.1.1 standard: https://docs.oasis-open.org/mqtt/mqtt/v3.1.1/mqtt-v3.1.1.html
• MQTT v5.0 standard: https://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.html

Mosquitto project information is available at the following locations:

• Main homepage: https://mosquitto.org/
• Find existing bugs or submit a new bug: https://github.com/eclipse-mosquitto/mosquitto/issues
• Source code repository: https://github.com/eclipse-mosquitto/mosquitto

There is also a public test server available at https://test.mosquitto.org/

Installing Copy Chapter

See https://mosquitto.org/download/ for details on installing binaries for
various platforms.

Quick start Copy Chapter

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
available and the dynamic security plugin.

Documentation Copy Chapter

Documentation for the broker, clients and client library API can be found in
the man pages, which are available online at https://mosquitto.org/man/. 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 https://mosquitto.org/api/

Building from source Copy Chapter

To build from source the recommended route for end users is to download the
archive from https://mosquitto.org/download/.

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 Copy Section

• 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 Copy Section

You can download and install mosquitto using the 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 on the vcpkg repository.

Credits Copy Chapter

Mosquitto was written by Roger Light [email protected]. There have been
substantial contributions by other people in the community both in terms of
code and other help.

Overview (`dashboard/README.md`) Copy Section

Simple web-based graphical user interface for Mosquitto Copy Section

To develop UI locally.

1. Install tailwind:

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:

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`) Copy Section

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`) Copy Section

Plugins

This directory contains plugins for use with Mosquitto.

Dynamic security Copy Chapter

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 Copy Chapter

This is an example plugin that demonstrates adding MQTT v5 properties to
messages, and how to get client information.

Examples / Authenticate by IP address Copy Chapter

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 Copy Chapter

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 Copy Chapter

This is an example plugin that demonstrates some of the functions for
retrieving client information such as client id and username.

Examples / Connection state Copy Chapter

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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

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`) Copy Section

This is the mosquitto website, it can be built with nikola:

nikola build

Overview (`deps/picohttpparser/README.md`) Copy Section

PicoHTTPParser

Copyright (c) 2009-2014 Kazuho Oku, Tokuhiro Matsuno, Daisuke Murase, Shigeo Mitsunari

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, Starman, Starlet, Furl. It is also the HTTP/1 parser of 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 Copy Chapter

The library exposes four functions: phr_parse_request, phr_parse_response, phr_parse_headers, phr_decode_chunked.

phr_parse_request Copy Section

The example below reads an HTTP request from socket sock using read(2), parses it using phr_parse_request, and prints the details.

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 Copy Section

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 Copy Section

The example below decodes incoming data in chunked-encoding. The data is decoded in-place.

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 Copy Chapter

The benchmark code is from fukamachi/fast-http@6b91103.

The internals of picohttpparser has been described to some extent in my blog entry.

Overview (`docker/1.6-openssl/README.md`) Copy Section

Eclipse Mosquitto Docker Image

Containers built with this Dockerfile build as source from published tarballs.

Mount Points Copy Chapter

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 Copy Chapter

The image runs mosquitto under the mosquitto user and group, which are created
with a uid and gid of 1883.

Configuration Copy Chapter

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 <absolute-path-to-configuration-file>:/mosquitto/config/mosquitto.conf eclipse-mosquitto:<version>

: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 <absolute-path-to-configuration-file>:/mosquitto/config/mosquitto.conf eclipse-mosquitto:<version>

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`) Copy Section

Eclipse Mosquitto Docker Image

Containers built with this Dockerfile build as source from published tarballs.

Mount Points Copy Chapter

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 Copy Chapter

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 Copy Chapter

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:<version> mosquitto -c /mosquitto-no-auth.conf

Configuration Copy Chapter

To use a custom configuration file, mount a local configuration file to /mosquitto/config/mosquitto.conf

docker run -it -p 1883:1883 -v <absolute-path-to-configuration-file>:/mosquitto/config/mosquitto.conf eclipse-mosquitto:<version>

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 <absolute-path-to-configuration-file>:/mosquitto/config/mosquitto.conf eclipse-mosquitto:<version>

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`) Copy Section

Eclipse Mosquitto Docker Image

Containers built with this Dockerfile build as source from published tarballs.

Mount Points Copy Chapter

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 Copy Chapter

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 Copy Chapter

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:<version>

Configuration Copy Chapter

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 <absolute-path-to-config-directory>:/mosquitto/config eclipse-mosquitto:<version>

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 <absolute-path-to-config-directory>:/mosquitto/config eclipse-mosquitto:<version>

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`) Copy Section

Eclipse Mosquitto Docker Image

Containers built with this Dockerfile build as source from published tarballs.

Mount Points Copy Chapter

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 Copy Chapter

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 Copy Chapter

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:<version>

Configuration Copy Chapter

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 <absolute-path-to-config-directory>:/mosquitto/config eclipse-mosquitto:<version>

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 <absolute-path-to-config-directory>:/mosquitto/config eclipse-mosquitto:<version>

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`) Copy Section

Eclipse Mosquitto Docker Image

Containers built with this Dockerfile build as source from published tarballs.

Mount Points Copy Chapter

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 Copy Chapter

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 Copy Chapter

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:<version> mosquitto -c /mosquitto-no-auth.conf

Configuration Copy Chapter

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 <absolute-path-to-configuration-file>:/mosquitto/config/mosquitto.conf eclipse-mosquitto:<version>

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 Copy Chapter

Build and tag the docker image for a specific version:

docker build -t eclipse-mosquitto:<version> --build-arg VERSION="<version>" .

Run Copy Chapter

Run a container using the new image:

docker run -it -p 1883:1883 -v <path-to-configuration-file>:/mosquitto/config/mosquitto.conf -v /mosquitto/data -v /mosquitto/log eclipse-mosquitto:<version>

: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`) Copy Section

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 Copy Chapter

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 Copy Chapter

The image runs mosquitto under the mosquitto user and group, which are created
with a uid and gid of 1883.

Configuration Copy Chapter

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 <absolute-path-to-configuration-file>:/mosquitto/config/mosquitto.conf eclipse-mosquitto:<version>

: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 <absolute-path-to-configuration-file>:/mosquitto/config/mosquitto.conf eclipse-mosquitto:<version>

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`) Copy Section

Mosquitto Dynamic Security

This document describes a topic based mechanism for controlling security in
Mosquitto. JSON commands are published to topics like $CONTROL/<feature>/v1

Clients Copy Chapter

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 Copy Chapter

Broker clients can be defined as belonging to zero or more broker groups.

Roles Copy Chapter

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 Copy Chapter

Set default ACL access Copy Section

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 Copy Section

Gets the default access behaviour for the different ACL types.

Command:

{
	"commands":[
		{
			"command": "getDefaultACLAccess"
		}
	]
}

mosquitto_ctrl example:

mosquitto_ctrl dynsec getDefaultACLAccess

Create Client Copy Chapter

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 Copy Chapter

Command:

{
	"commands":[
		{
			"command": "deleteClient",
			"username": "username to delete"
		}
	]
}

mosquitto_ctrl example:

mosquitto_ctrl dynsec deleteClient username

Enable Client Copy Chapter

Command:

{
	"commands":[
		{
			"command": "enableClient",
			"username": "username to enable"
		}
	]
}

mosquitto_ctrl example:

mosquitto_ctrl dynsec enableClient username

Disable Client Copy Chapter

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 Copy Chapter

Command:

{
	"commands":[
		{
			"command": "getClient",
			"username": "required username"
		}
	]
}

mosquitto_ctrl example:

mosquitto_ctrl dynsec getClient username

List Clients Copy Chapter

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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

Command:

{
	"commands":[
		{
			"command": "setClientPassword",
			"username": "username to change",
			"password": "new password"
		}
	]
}

mosquitto_ctrl example:

mosquitto_ctrl dynsec setClientPassword username password

Add Client Role Copy Chapter

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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

Command:

{
	"commands":[
		{
			"command": "deleteGroup",
			"groupname: "group to delete"
		}
	]
}

mosquitto_ctrl example:

mosquitto_ctrl dynsec deleteGroup groupname

Get Group Copy Chapter

Command:

{
	"commands":[
		{
			"command": "getGroup",
			"groupname: "group to get"
		}
	]
}

mosquitto_ctrl example:

mosquitto_ctrl dynsec getGroup groupname

List Groups Copy Chapter

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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

Command:

{
	"commands":[
		{
			"command": "removeGroupRole",
			"groupname": "group",
			"rolename": "role"
		}
	]
}

mosquitto_ctrl example:

mosquitto_ctrl dynsec removeGroupRole groupname rolename

Set Group for Anonymous Clients Copy Chapter

Command:

{
	"commands":[
		{
			"command": "setAnonymousGroup",
			"groupname": "group"
		}
	]
}

mosquitto_ctrl example:

mosquitto_ctrl dynsec setAnonymousGroup groupname

Get Group for Anonymous Clients Copy Chapter

Command:

{
	"commands":[
		{
			"command": "getAnonymousGroup"
		}
	]
}

mosquitto_ctrl example:

mosquitto_ctrl dynsec getAnonymousGroup

Create Role Copy Chapter

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 Copy Chapter

Command:

{
	"commands":[
		{
			"command": "getRole",
			"rolename": "role",
		}
	]
}

mosquitto_ctrl example:

mosquitto_ctrl dynsec getRole rolename

List Roles Copy Chapter

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 Copy Chapter

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 Copy Chapter

Command:

{
	"commands":[
		{
			"command": "deleteRole",
			"rolename": "role"
		}
	]
}

mosquitto_ctrl example:

mosquitto_ctrl dynsec deleteRole rolename

Add Role ACL Copy Chapter

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 Copy Chapter

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`) Copy Section

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`) Copy Section

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`) Copy Section

{
"@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`) Copy Section

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 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

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 home automation project and
OwnTracks, 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