MOSQUITTO(8)

📦
version 2.1.2 · 13 versions
, in alpine 3.24, fedora 44

Bestie, welcome to the MOSQUITTO(8) page from the Mosquitto manual 💖 — we’re folding that header in like a cute little name tag so we can get straight to the tea.

💖 NAME 💖

mosquitto — an MQTT broker. That’s the whole vibe: she brokers MQTT, and she’s iconic for it 💅

✨ SYNOPSIS ✨

mosquitto [-c config file] [-d | --daemon] [-p port number] [-q] [-v]
          [--tls-keylog file]

🦋 DESCRIPTION 🦋

mosquitto is a broker for the MQTT protocol version 5.0/3.1.1/3.1. Literally the main character of the mosquitto project.

It is part of the overall mosquitto project. See mosquitto(7) for an overview of all man pages. iykyk, there are more pages where this came from.

🎀 OPTIONS 🎀

  • -c, --config-file — Load configuration from a file. If not given, then the broker will listen on port 1883 bound to the loopback interface, and the default values as described in mosquitto.conf(5) are used.
Important: See the -p option for a description of changes in behaviour from 1.6.x to 2.0.
  • -d, --daemon — Run mosquitto in the background as a daemon. All other behaviour remains the same. background mode, no cap.
  • -p, --port — Listen on the port specified. May be specified up to 10 times to open multiple sockets listening on different ports.
Important: In version 1.6.x and earlier, the listener defined by -p (or the default port of 1883) would be bound to all interfaces and so be accessible from any network. It could also be used in combination with -c. From version 2.0 onwards, the listeners defined with -p are bound to the loopback interface only, and so can only be connected to from the local machine. If both -p is used and a listener is defined in a configuration file, then the -p options are IGNORED.
  • -q, --quiet — Available from version 2.1.

Disable all logging. This is equivalent to setting log_type to none in the configuration file. This overrides any logging options given in the configuration file and also overrides --verbose. quiet mode goes brrr — no logs, bestie.

  • --test-config — Available from version 2.1.

Load the config file specified with -c, and verify that it is valid but do not start the broker. The broker exit code will be 0 if the config was valid, or non-zero if no config file was specified or the config file was invalid. a lil config vibe check, no broker launch.

  • --tls-keylog file — Available from version 2.1.

Log TLS connection information to file. This option allows tools such as tcpdump, wireshark and mqttshark to decrypt TLS traffic and inspect the MQTT traffic. In Wireshark this can be done by setting the (Pre)-Master-Secret log filename option for the Transport Layer Security protocol.

Debugging only, bestie: This option should be used for debugging only, it must not be used in production. fr fr, do not ship this.
  • -v, --verbose — Use verbose logging. This is equivalent to setting log_type to all in the configuration file. This overrides any logging options given in the configuration file. maximum yappage enabled.

🌸 CONFIGURATION 🌸

The broker can be configured using a configuration file as described in mosquitto.conf(5) and this is the main point of information for mosquitto. The files required for SSL/TLS support are described in mosquitto-tls(7). config file girlies know.

🫶 PLATFORM LIMITATIONS 🫶

Some versions of Windows have limitations on the number of concurrent connections due to the Windows API being used. In modern versions of Windows, e.g. Windows 10 or Windows Server 2019, this is approximately 8192 connections. In earlier versions of Windows, this limit is 2048 connections. Windows said “we have limits,” and we respect that.

👑 MQTT SUPPORT 👑

Mosquitto supports MQTT v5.0, v3.1.1, and v3.1.

🦋 MQTT v5.0 🦋

Mosquitto provides full MQTT v5.0 support, but some features are not used directly. The following sections describe the new features and explain where Mosquitto does not make use of a feature.

💫 Features 💫

  • Enhanced authentication — Basic MQTT authentication uses username/password checks. Enhanced authentication allows different authentication schemes to be integrated into MQTT, and even those schemes with multiple step processes. Clients request a particular type of authentication and if the broker is configured for that scheme the authentication continues. Mosquitto supports enhanced authentication through plugins. plug-in girlies, this one’s for you.
  • Error handling — Most MQTT packets now have the concept of a reason code which indicates success or failure, and what the failure was. Mosquitto provides full support for reason codes, but does not make use of the reason string feature which can be used to provide a human readable error string to explain the reason code. reason codes, yes; reason strings, not used.
  • Flow control — The number of "in flight" messages for QoS 1 and QoS 2 can be controlled by both the client and the broker.
  • Request / response — MQTT v5.0 adds a request/response pattern that allows a client to publish a message and instruct the subscribers of that message where to publish a response.
  • Server redirection — Server redirection is the concept of telling a client to connect to a different MQTT broker, either on CONNECT or with a broker initiated DISCONNECT. Mosquitto does not currently make use of this feature.
  • Shared subscriptions — When multiple clients subscribe to the same shared subscription, only one client out of the group will receive each message which allows for distributing work loads.

🎀 Packet properties 🎀

MQTT v5.0 allows properties to be added to packets to control certain behaviour. Unless noted, Mosquitto supports the properties listed below.

CONNECT

  • Authentication data
  • Authentication method
  • Maximum packet size
  • Receive maximum
  • Request problem information - supported but not used
  • Request response information - supported but not used
  • Session expiry interval
  • Topic alias maximum
  • User property

Last will and testament

  • Content type
  • Correlation data
  • Message expiry interval
  • Payload format indicator
  • Response topic
  • User property
  • Will delay interval

CONNACK

  • Assigned client identifier
  • Authentication data
  • Authentication method
  • Maximum packet size
  • Maximum qos
  • Reason string - supported but not used
  • Receive maximum
  • Response information - supported but not used
  • Retain available
  • Server keep alive
  • Server reference - supported but not used
  • Session expiry interval
  • Shared subscription available
  • Subscription identifiers available
  • Topic alias maximum
  • User property
  • Wildcard subscription available

PUBLISH

  • Content type
  • Correlation data
  • Message expiry interval
  • Payload format indicator
  • Response topic
  • Subscription identifier
  • Topic alias
  • User property

PUBACK / PUBREC / PUBREL / PUBCOMP / SUBACK / SUBSCRIBE / SUBACK

  • Reason string - supported but not used
  • User property

SUBSCRIBE

  • Subscription identifier
  • User property

DISCONNECT

  • Reason string - supported but not used
  • Server reference - supported but not used
  • Session expiry interval
  • User property

AUTH

  • Authentication method
  • Authentication data
  • Reason string - supported but not used
  • User property

🌈 MQTT v3.1.1 🌈

Mosquitto provides full MQTT v3.1.1 support. full support, periodt.

⭐ MQTT v3.1 ⭐

Mosquitto provides full MQTT v3.1 support. another one, fully supported.

💀 MQTT v3 💀

MQTT v3 is an obsolete version of the protocol that does not support username/password authentication and used the clean start flag in the CONNECT packet which applied only to the start of a session. An MQTT v3 client will be able to successfully connect to a Mosquitto instance that does not require authentication. obsolete but still able to slide in when auth is off.

💅 BROKER STATUS 🫶

okay bestie, so — clients can literally just subscribe to topics in the $SYS hierarchy and get the tea about the broker itself. no cap, it's the broker's finsta. 🎀

the ones marked static are sent only once per client, on subscription — like a "welcome, here's my whole deal" moment. every other topic refreshes every sys_interval seconds. and if sys_interval is 0? yeah, updates are just... not sent. silence. 💀

⚠️ shell warning, listen up: if you're using a command line client and your shell thinks $ means an environment variable (it does, bestie, it literally does), you have to wrap the topic in single quotes — '$SYS/...' — or escape the dollar sign like \$SYS/.... otherwise $SYS gets treated as an environment variable and you'll be sitting there like "why is nothing happening 😭". guard your vibes. ✨
  • $SYS/broker/bytes/received — the total number of bytes received since the broker started. running total, since day one. 🧮
  • $SYS/broker/bytes/sent — the total number of bytes sent since the broker started. the outgoing receipts. 📤
  • $SYS/broker/clients/connected, $SYS/broker/clients/active (deprecated) — how many clients are connected right now. note that active is the deprecated twin, iykyk. 👥
  • $SYS/broker/clients/expired — the number of disconnected persistent clients that got expired and removed via the persistent_client_expiration option. like the broker cleaning out its closet. 🧹
  • $SYS/broker/clients/disconnected, $SYS/broker/clients/inactive (deprecated) — the total number of persistent clients (those with clean session disabled) that are registered on the broker but are currently disconnected. they're on the roster, just not in the room. 🪑
  • $SYS/broker/clients/maximum — the maximum number of clients that have ever been connected to the broker at the same time. the peak attendance record. 👑
  • $SYS/broker/clients/total — the total number of connected and disconnected client sessions currently registered on the broker. everyone invited, present or not. 🌈
  • $SYS/broker/connection/# — when bridges are configured to/from the broker, common practice is to provide a status topic that indicates the state of the connection, and that's provided within $SYS/broker/connection/ by default. value 1 = connection is active, 0 = not active. see the Bridges section below for more bridge lore. 🌉🦋
  • $SYS/broker/connections/socket/count — the total number of socket connections made to the broker, whether or not the MQTT connections were ultimately successful. effort counts, babes. 🔌
  • $SYS/broker/heap/current — the current size of the heap memory in use by mosquitto. heads up: this topic may be unavailable depending on compile time options. 🙈
  • $SYS/broker/heap/maximum — the largest amount of heap memory ever used by mosquitto. also may be unavailable depending on compile time options. 📈
  • $SYS/broker/load/connections/+ — the moving average of the number of CONNECT packets received by the broker over different time intervals. the final + can be 1min, 5min or 15min, and the value returned is the number of connections received in 1 minute, averaged over 1, 5 or 15 minutes. ✨
  • $SYS/broker/load/bytes/received/+ — the moving average of the number of bytes received by the broker over different time intervals. final + can be 1min, 5min or 15min; the value is the number of bytes received in 1 minute, averaged over 1, 5 or 15 minutes. 🌸
  • $SYS/broker/load/bytes/sent/+ — the moving average of the number of bytes sent by the broker over different time intervals. final + can be 1min, 5min or 15min; the value is the number of bytes sent in 1 minute, averaged over 1, 5 or 15 minutes. 💌
  • $SYS/broker/load/messages/received/+ — the moving average of the number of all types of MQTT messages received by the broker over different time intervals. final + can be 1min, 5min or 15min; the value is the number of messages received in 1 minute, averaged over 1, 5 or 15 minutes. 📥
  • $SYS/broker/load/messages/sent/+ — the moving average of the number of all types of MQTT messages sent by the broker over different time intervals. final + can be 1min, 5min or 15min; the value is the number of messages send in 1 minute, averaged over 1, 5 or 15 minutes. 📤
  • $SYS/broker/load/publish/dropped/+ — the moving average of the number of publish messages dropped by the broker over different time intervals. this one shows the rate at which durable clients that are disconnected are losing messages — so yeah, look at it. final + can be 1min, 5min or 15min; the value is the number of messages dropped in 1 minute, averaged over 1, 5 or 15 minutes. 💀
  • $SYS/broker/load/publish/received/+ — the moving average of the number of publish messages received by the broker over different time intervals. final + can be 1min, 5min or 15min; the value is the number of publish messages received in 1 minute, averaged over 1, 5 or 15 minutes. 🍓
  • $SYS/broker/load/publish/sent/+ — the moving average of the number of publish messages sent by the broker over different time intervals. final + can be 1min, 5min or 15min; the value is the number of publish messages sent in 1 minute, averaged over 1, 5 or 15 minutes. 🧚
  • $SYS/broker/load/sockets/+ — the moving average of the number of socket connections opened to the broker over different time intervals. final + can be 1min, 5min or 15min; the value is the number of socket connections in 1 minute, averaged over 1, 5 or 15 minutes. 🔥
  • $SYS/broker/messages/received — the total number of messages of any type received since the broker started. 🧾
  • $SYS/broker/messages/sent — the total number of messages of any type sent since the broker started. ✉️
  • $SYS/broker/mqtt/connect/received — the total number of MQTT CONNECT messages received since the broker started. 🤝
  • $SYS/broker/mqtt/connack/sent — the total number of MQTT CONNACK messages sent since the broker started. 🫶
  • $SYS/broker/mqtt/publish/dropped, $SYS/broker/publish/messages/dropped — the total number of MQTT PUBLISH messages dropped due to inflight/queuing limits. see the max_inflight_messages and max_queued_messages options in mosquitto.conf(5) for the full story. 💅
  • $SYS/broker/mqtt/publish/received, $SYS/broker/publish/messages/received — the total number of MQTT PUBLISH messages received since the broker started. 📨
  • $SYS/broker/mqtt/publish/sent, $SYS/broker/publish/messages/sent — the total number of MQTT PUBLISH messages sent since the broker started. 🚀
  • $SYS/broker/mqtt/puback/received — the total number of MQTT PUBACK messages received since the broker started. ✅
  • $SYS/broker/mqtt/puback/sent — the total number of MQTT PUBACK messages sent since the broker started. ✅
  • $SYS/broker/mqtt/pubrec/received — the total number of MQTT PUBREC messages received since the broker started. 📬
  • $SYS/broker/mqtt/pubrec/sent — the total number of MQTT PUBREC messages sent since the broker started. 📬
  • $SYS/broker/mqtt/pubrel/received — the total number of MQTT PUBREL messages received since the broker started. 🔓
  • $SYS/broker/mqtt/pubrel/sent — the total number of MQTT PUBREL messages sent since the broker started. 🔓
  • $SYS/broker/mqtt/pubcomp/received — the total number of MQTT PUBCOMP messages received since the broker started. 🏁
  • $SYS/broker/mqtt/pubcomp/sent — the total number of MQTT PUBCOMP messages sent since the broker started. 🏁
  • $SYS/broker/mqtt/subscribe/received — the total number of MQTT SUBSCRIBE messages received since the broker started. 👀
  • $SYS/broker/mqtt/suback/sent — the total number of MQTT SUBACK messages sent since the broker started. 👍
  • $SYS/broker/mqtt/unsubscribe/received — the total number of MQTT UNSUBSCRIBE messages received since the broker started. 🚪
  • $SYS/broker/mqtt/unsuback/sent — the total number of MQTT UNSUBACK messages sent since the broker started. 🚪
  • $SYS/broker/mqtt/pingreq/received — the total number of MQTT PINGREQ messages received since the broker started. 🏓
  • $SYS/broker/mqtt/pingresp/sent — the total number of MQTT PINGRESP messages sent since the broker started. 🏓
  • $SYS/broker/mqtt/disconnect/received — the total number of MQTT DISCONNECT messages received since the broker started. 👋
  • $SYS/broker/mqtt/disconnect/sent — the total number of MQTT DISCONNECT messages sent since the broker started. 👋
  • $SYS/broker/mqtt/auth/received — the total number of MQTT AUTH messages received since the broker started. 🔐
  • $SYS/broker/mqtt/auth/sent — the total number of MQTT AUTH messages sent since the broker started. 🔐
  • $SYS/broker/packet/out/count — the current number of packets queued for delivery across all clients. a large and increasing value here may indicate messages are being sent faster than the network can handle — so like, red flag, bestie. 🚩
  • $SYS/broker/packet/out/bytes — the current number of bytes in packets queued for delivery across all clients. a large and increasing value here may indicate messages are being sent faster than the network can handle. same warning, same vibe. 🚩
  • $SYS/broker/publish/bytes/received — the total number of PUBLISH payload bytes received since the broker started. 📦
  • $SYS/broker/publish/bytes/sent — the total number of PUBLISH payload bytes sent since the broker started. 📦
  • $SYS/broker/retained messages/count — the total number of retained messages active on the broker. (yes, the topic name literally has a space in it, don't come for me, that's just how it is 💀) 🗂️
  • $SYS/broker/store/messages/count, $SYS/broker/messages/stored (deprecated) — the number of messages currently held in the message store. this includes retained messages and messages queued for durable clients. 🗄️
  • $SYS/broker/store/messages/bytes — the number of bytes currently held by message payloads in the message store. includes retained messages and messages queued for durable clients. 🧮
  • $SYS/broker/shared_subscriptions/count — the total number of shared subscriptions active on the broker. 🤝
  • $SYS/broker/subscriptions/count — the total number of subscriptions active on the broker. 📋
  • $SYS/broker/version — the version of the broker. static. the classic "what's your sign" of topics. ⭐

🦋 WILDCARD TOPIC SUBSCRIPTIONS

Okay so here's the thing bestie — mosquitto doesn't just let you subscribe to boring exact topics, it lets you use two wildcards and honestly? It's giving main character energy. 💅

Wildcard numero uno: + — this one matches a single level of hierarchy. That's it, one level, no more, no less.

So say your topic is a/b/c/d. The way that these subscriptions will match is:

  • a/b/c/d
  • +/b/c/d
  • a/+/c/d
  • a/+/+/d
  • +/+/+/+

And the way that these will not match (sorry bestie 😭):

  • a/b/c
  • b/+/c/d
  • +/+/+

Wildcard numero dos: # — this one is the greedy icon it is and matches all subsequent levels of hierarchy. Obsessed.

Same topic, a/b/c/d, and these example subscriptions will match:

  • a/b/c/d
  • #
  • a/#
  • a/b/#
  • a/b/c/#
  • +/b/c/#
🚨 Lowkey important: the $SYS hierarchy does not match a subscription of #. If you want to observe the entire $SYS hierarchy, you gotta subscribe to $SYS/#. No cap.

Also, wildcards must only ever be used on their own — so a subscription of a/b+/c is not valid use of a wildcard. And the # wildcard must only ever be used as the final character of a subscription. Periodt. ✨

🌉 BRIDGES

So you can connect multiple brokers together with the bridging functionality and it's genuinely so useful. Like, when is it useful? When you wanna share info between locations but not, like, all of the info. 🫶

The example they give: a bunch of users are each running a broker to help record power usage (plus a number of other reasons). The power usage could be shared by bridging all of the user brokers to a common broker — which lets the power usage of all the users get collected and compared. And the other information stays local to each broker. Chef's kiss. 👑

For the actual deets on configuring bridges, go see mosquitto.conf(5).

📡 SIGNALS

On POSIX systems, Mosquitto can receive signals and act on them, as described below. To send signals, use like:

kill -HUP <process id of mosquitto>

SIGHUP

Upon receiving the SIGHUP signal, mosquitto will attempt to reload configuration file data — assuming that the -c argument was provided when mosquitto was started. Heads up though: not all configuration parameters can be reloaded without restarting. See mosquitto.conf(5) for details.

If TLS certificates are in use, then mosquitto will also reload certificate on receiving a SIGHUP.

The logs will also be closed and reopened. 🗂️

SIGRTMIN

Upon receiving the SIGRTMIN signal, mosquitto will close and reopen the logs to support log rotation. Rotate that log, slay. 🔄

SIGUSR1

Upon receiving the SIGUSR1 signal, mosquitto will write the persistence database to disk. This signal is only acted upon if persistence is enabled. 💾

SIGUSR2

The SIGUSR2 signal causes mosquitto to print out the current subscription tree, along with information about where retained messages exist. This is intended as a testing feature only and may be removed at any time. 🙈 Don't get too attached.

🌸 ENVIRONMENT VARIABLES

  • MOSQUITTO_UNSAFE_ALLOW_SYMLINKS — By default, sensitive file with a path including a symbolic link will be refused to be loaded. Set this environment variable to any value to allow load files through symbolic links. Note that making use of this variable could expose you to symlink attacks and so it should only be used in cases where you are absolutely sure this is not a risk.
💀 Fr fr, that one's a real warning. Like, the name literally has UNSAFE in it. Read the room.

📁 FILES

  • /etc/mosquitto/mosquitto.conf — Configuration file. See mosquitto.conf(5).
  • /var/lib/mosquitto/mosquitto.db — Persistent message data storage location if persist enabled.
  • /etc/hosts.allow, /etc/hosts.deny — Host access control via tcp-wrappers as described in hosts_access(5).

🐛 BUGS

mosquitto bug information can be found at:

https://github.com/eclipse-mosquitto/mosquitto/issues

If you found one, go tell them — they wanna know, bestie. 🫶

👀 SEE ALSO

mosquitto(7), mqtt(7), mosquitto-tls(7), mosquitto.conf(5), mosquitto_ctrl(1), mosquitto_passwd(1), mosquitto_pub(1), mosquitto_rr(1), mosquitto_sub(1), libmosquitto(3)

💖 THANKS

Thanks to Andy Stanford-Clark for being one of the people who came up with MQTT in the first place. Thanks to Andy and Nicholas O'Leary for providing clarifications of the protocol.

Thanks also to everybody at the Ubuntu UK Podcast and Linux Outlaws for organising OggCamp, where Andy gave a talk that inspired mosquitto. 🌈 Literally the origin story, iconic.

✍️ AUTHOR

Roger Light <roger@atchoo.org>

And that's a wrap, bestie! 💅✨ This whole glow-up is brought to you by the Mosquitto Project, dated 02/09/2026, and it lives at MOSQUITTO(8) — go forth and broker responsibly. 🎀🦋

📦 where this page comes from