MQTT broker#

An MQTT broker is a service to which MQTT clients connect. These clients publish data to specific topics and they can subscribe to one or more topics to receive messages. A topic is like an "address" for a particular message. For example, a topic for a device that publishes a temperature reading of your living room may be temperature/indoors/living, whereas a device which publishes weather data could do so to weather/germany/frankfurt. In the particular case of OwnTracks, we use a topic branch called owntracks/username/device, but you can override that name if you prefer to. The reason we've chosen that structure is to accomodate friends and family on a single broker, taking into consideration that a particular user might have more than one device.

Private broker#

You set up a private broker under your control. This sounds more difficult than it actually is, and there are some very nice brokers you can use free of charge on your own infrastructure. As an example, we've written up how to install Mosquitto on a Raspberry Pi.

RasPi#

Mosquitto on a Raspbi

The hardest bit is installing an OS, say, Raspbian Wheezy, onto an SD card, but there are many tutorials on how to do that. A basic install will suffice, and after logging in with Raspbian's default username and password, we're going to suggest you use our quicksetup to configure most of what you need automatically.

Bridging#

If you want to connect two (or more) brokers (e.g. yours and that of your friend) you can, and we've written up how you can bridge brokers.

Logging#

Before doing anything else, please consult the manual to determine where your Mosquitto logs are being written to. It's hard stabbing around in the dark when a glance at a log file can give you valuable tips on what is actually happening.

Mosquitto typically logs via syslog, and syslog's configuration defines where the log messages are actually written to. Your syslog may be called syslog, rsyslog, syslog-ng, or anything else for that matter. In case of doubt, check the files in /var/log; one of them ought to have what you're looking for (e..g messages, syslog, localmessages, or even debugmessages), very likely /var/log/mosquitto/mosquitto.log.

Mosquitto typically logs each connection request, a publish, a subscribe request, etc.

A successful publish of an OwnTracks location could look somewhat like this:

mosquitto[1366]: Received PUBLISH from jane-5s-m-o (d0, q2, r1, m7, 'owntracks/jane/5s', ... (159 bytes))
mosquitto[1366]: Sending PUBREC to jane-5s-m-o (Mid: 7)
mosquitto[1366]: Received PUBREL from jane-5s-m-o (Mid: 7)
mosquitto[1366]: Sending PUBCOMP to jane-5s-m-o (Mid: 7)

Proxy and firewall configuration#

If your MQTT broker sits behind a proxy or firewall (such as HAProxy in a pfSense deployment), you need to ensure that idle timeout settings do not interfere with MQTT's persistent connections.

MQTT clients maintain long-lived TCP connections to the broker, using periodic keepalive messages to stay connected. OwnTracks clients send keepalive packets every 3600 seconds (one hour) by default. If your proxy or firewall has a shorter idle timeout, it will close these "silent" connections prematurely, causing frequent disconnections.

HAProxy configuration example:

If you are using HAProxy (e.g., on pfSense), configure the following timeouts on both the frontend and backend handling MQTT traffic (in TCP mode):

  • Client timeout: Set to at least 4200000 ms (70 minutes)
  • Server timeout: Set to at least 4200000 ms (70 minutes)
  • Connection timeout: Leave at default (only covers initial connection establishment)

Both the client and server timeouts must exceed your MQTT client keepalive setting, with a safety margin. Mosquitto itself waits 1.5 times the keepalive interval before declaring a client dead.

Important notes:

  • These timeout settings are per frontend/backend, so other services behind your proxy remain unaffected.
  • The httpclose option in HAProxy is irrelevant when operating in TCP mode.
  • After saving configuration changes, clients must reconnect for new timeouts to take effect.
  • If disconnections continue to occur only on cellular connections, consider lowering the client keepalive to 120–300 seconds to stay ahead of carrier NAT idle timeouts.

Consult your proxy or firewall documentation for the specific steps to adjust these settings.

OwnTracks#

So, you've configured your broker and you are familiar with the mosquitto command-line clients, so now it's time to see if you can get OwnTracks to speak to your broker.