Eclipse Mosquitto: open source MQTT broker with client library and tools

Eclipse Mosquitto: open source MQTT broker with client library and tools

The source is the README of the Eclipse Mosquitto GitHub repository. It describes Mosquitto as an open source implementation of a server (a broker) for versions 5.0, 3.1.1 and 3.1 of the MQTT protocol. Alongside the broker the project ships 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 administering the broker.

The README points to the MQTT community page, the OASIS standards for MQTT v3.1.1 and v5.0, the main homepage at mosquitto.org, the GitHub issue tracker and the source repository. It also mentions a public test server at test.mosquitto.org. Binaries for various platforms are listed at mosquitto.org/download.

Getting started is short. If a binary package is installed, the broker should already be running; if not, typing mosquitto starts it with a very basic configuration. Then mosquitto_sub -t 'test/topic' -v subscribes to a topic, and mosquitto_pub -t 'test/topic' -m 'hello world' publishes a message. Started this way, the broker allows anonymous, unauthenticated access, but only from the local computer, so the README calls it useful only for initial testing.

To let clients on other computers connect, you must provide a configuration file. A binary package will probably already have one somewhere like /etc/mosquitto/mosquitto.conf. If you compiled from source, you write your own and run mosquitto -c /path/to/mosquitto.conf. The config needs a listener and a decision about authentication. The README says it is not advised to run a broker with anonymous access when it is publicly available, and points to the available authentication methods and the dynamic security plugin.

Documentation lives in man pages (online at mosquitto.org/man/), with pages on MQTT features, the mosquitto_passwd utility and the broker's configuration options. Client library API documentation is at mosquitto.org/api/.

For building, the recommended route for end users is the source archive from the download page. On Windows and Mac you build with cmake; on other platforms you just run make. Windows users should also see README-windows.md. Building from the git repository does not include prebuilt documentation: use make binary to skip the man pages, or install docbook-xsl on Debian or Ubuntu.

The dependency list is mostly optional. cJSON is required. Optional pieces are c-ares (enable with WITH_SRV=yes), libedit for the mosquitto_ctrl interactive shell (disable with WITH_EDITLINE=no), libmicrohttpd for broker HTTP API support (WITH_HTTP_API=no), openssl (WITH_TLS=no), sqlite3 for broker persistence (WITH_SQLITE=no), bundled uthash and utlist headers (WITH_BUNDLED_DEPS=no) and xsltproc, needed only when building from git sources (WITH_DOCS=no). pthreads is needed for client library thread support and the mosquitto_loop_start() and mosquitto_loop_stop() functions; without it the library is not guaranteed to be thread safe. The CMake build offers equivalent options and can also enable or disable specific plugins.

Mosquitto can also be installed through the vcpkg dependency manager (clone vcpkg, bootstrap it, run integrate install, then install mosquitto). The vcpkg port is kept up to date by Microsoft team members and community contributors; if it is out of date, the README asks users to open an issue or pull request on the vcpkg repository. Finally, the README says Mosquitto was written by Roger Light, with substantial contributions from others in the community, in code and other help.

Key facts

  • Mosquitto is an open source server for MQTT versions 5.0, 3.1.1 and 3.1, with a C and C++ client library.
  • It bundles mosquitto_pub, mosquitto_rr and mosquitto_sub for publishing and subscribing, plus mosquitto_ctrl, mosquitto_signal and mosquitto_passwd for administration.
  • Started with no configuration, the broker accepts anonymous access only from the local computer; remote clients need a configuration file.
  • cJSON is the only required dependency; TLS, sqlite3 persistence, the HTTP API and others are optional build flags.
  • A public test server runs at test.mosquitto.org, and vcpkg offers an install route kept up to date by Microsoft team members and community contributors.

Why it matters

This is not a news event. The source is a project README, with no new release, change or announcement. What it shows is the scope of the project: one open source package covering an MQTT broker for protocol versions 5.0, 3.1.1 and 3.1, a client library for C and C++, and a set of command-line tools for publishing, subscribing and administration.

Who it affects

Anyone who needs an MQTT server they can run themselves, and developers who want a C or C++ MQTT client library. The README also addresses people who install from binary packages, people who build from source on Windows, Mac or other platforms, and vcpkg users.

How to use it

Install a binary package from mosquitto.org/download, or build from the source archive (cmake on Windows and Mac, make elsewhere), or use vcpkg. Run mosquitto, then mosquitto_sub -t 'test/topic' -v in one terminal and mosquitto_pub -t 'test/topic' -m 'hello world' in another. For access from other machines, write a configuration file with a listener and an authentication choice, and start the broker with mosquitto -c /path/to/mosquitto.conf. The man pages at mosquitto.org/man/ and the API docs at mosquitto.org/api/ cover the details. The public server at test.mosquitto.org is available for trying things out.

How solid is it

The source is the project's own README, so it is authoritative on what the package contains and how to build and start it. It is not an independent evaluation. It gives no performance figures, user counts or benchmarks, and it names no release version or date.

Risks and caveats

The main warning in the README concerns access. The default no-configuration start allows anonymous access from the local computer only, and the README advises against anonymous access on a publicly available broker. Choose an authentication method; it points to the available methods and the dynamic security plugin. Build-wise, pthreads is needed for the library's thread support, and without it the library is not guaranteed to be thread safe. Builds from git do not include the man pages unless docbook-xsl or xsltproc is available. If the vcpkg version is out of date, the README says to file an issue or pull request on the vcpkg repository.

“It is not advised to run your broker with anonymous access when it is publicly available.”

— Eclipse Mosquitto README