MQTT(7)

💅 MQTT(7) — like, the conventions & miscellaneous page, bestie

okay so first things first, this whole page lives under the MQTT manual section (section 7, the "conventions and miscellaneous" girlies), and it's brought to you by the Mosquitto Project. yes we're doing the manual page thing. stay with me, it's gonna slay.

---

✨ NAME ✨

mqtt — MQ Telemetry Transport. that's the whole name, that's the vibe. 🦋

✨ SYNOPSIS ✨

MQTT

literally just MQTT. no flags, no args, no drama. iconic behavior honestly. 💅

✨ DESCRIPTION ✨

so MQTT is a lightweight publish/subscribe messaging protocol — lowkey the blueprint. it's genuinely useful for low power sensors, but no cap it works for so many scenarios, it's not just a sensor thing.

this manual walks you through some of the features of MQTT version 3.1.1/3.1, so you (the end user) can get the absolute most out of the protocol. 🫶 for the full, complete, all-the-tea info on MQTT, go look at https://mqtt.org/ — that's where the rest lives.

---

🌸 PUBLISH/SUBSCRIBE 🌸

the MQTT protocol is built on one principle and it's very main character: you publish messages and you subscribe to topics. aka "pub/sub". 📬

here's the whole situation:

• multiple clients connect to a broker and subscribe to topics they're interested in
• clients also connect to that broker and publish messages to topics
• many clients can subscribe to the same topics and do whatever they want with the info — their choice, their era

the broker and MQTT act as a simple, common interface for everything to connect to. which means: if you've got clients that dump subscribed messages into a database, to Twitter, or even just a plain text file — then adding new sensors or other data input to that database, Twitter, whatever, becomes genuinely so simple. it's giving plug and play. ✨

---

🎀 TOPICS/SUBSCRIPTIONS 🎀

messages in MQTT get published on topics. and here's the cute part: there is no need to configure a topic — just publishing on it is enough. no setup arc, no registration form, we simply go. 💖

topics are treated as a hierarchy, using a slash (/) as a separator. same energy as a filesystem, which means you can arrange common themes sensibly. for example, multiple computers can all publish their hard drive temperature info on this topic, with their own computer name and hard drive name swapped in as appropriate:

• sensors/COMPUTER_NAME/temperature/HARDDRIVE_NAME

clients receive messages by creating subscriptions. a subscription can be to an explicit topic (in which case only messages to that exact topic get received), or it can include wildcards. there are exactly two, and they are + and #.

💫 the + wildcard

+ can be used as a wildcard for a single level of hierarchy. so you could take the topic above and get info on all computers and hard drives like this:

• sensors/+/temperature/+

another example — for a topic of "a/b/c/d", these example subscriptions will match:

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

and these subscriptions will not match (sorry bestie):

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

🔥 the # wildcard

# can be used as a wildcard for all remaining levels of hierarchy. and because of that, it must be the final character in a subscription. rules are rules. 👑

with a topic of "a/b/c/d", these example subscriptions will match:

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

🙈 the zero-length level lore

zero length topic levels are valid, which leads to some slightly non-obvious behaviour. hear me out:

• a topic of "a//topic" would correctly match against a subscription of "a/+/topic"
• zero length topic levels can exist at both the beginning and the end of a topic string
• so "/a/topic" would match against a subscription of "+/a/topic", "#" or "/#"
• and a topic "a/topic/" would match against a subscription of "a/topic/+" or "a/topic/#"

like yes it's a little unhinged but it's also correct. iykyk. 💀

---

💜 QUALITY OF SERVICE 💜

MQTT defines three levels of Quality of Service (QoS). the QoS defines how hard the broker/client will try to make sure a message is actually received. 💌

the rules:

• messages may be sent at any QoS level
• clients may attempt to subscribe to topics at any QoS level
• this means the client chooses the maximum QoS it will receive

examples, because examples ate:

• if a message is published at QoS 2 and a client is subscribed with QoS 0 → the message is delivered to that client with QoS 0
• if a second client is also subscribed to the same topic but with QoS 2 → it receives the same message, but with QoS 2
• if a client is subscribed with QoS 2 and a message is published on QoS 0 → the client receives it on QoS 0

higher levels of QoS are more reliable, but they come with higher latency and higher bandwidth requirements. tradeoffs, always tradeoffs. 😭

• 0 — the broker/client will deliver the message once, with no confirmation
• 1 — the broker/client will deliver the message at least once, with confirmation required
• 2 — the broker/client will deliver the message exactly once by using a four step handshake

---

⭐ RETAINED MESSAGES ⭐

all messages may be set to be retained. what that means: the broker keeps the message even after it's been sent to all current subscribers. 🫶

then, if a new subscription is made that matches the topic of the retained message, that message gets sent to the client. it's basically a "last known good" mechanism, and it's lowkey genius.

why you care: if a topic is only updated infrequently, then without a retained message a newly subscribed client may have to wait a long time to get an update. with a retained message, the client gets an instant update. instant. periodt. 🔥

---

🧚 CLEAN SESSION / DURABLE CONNECTIONS 🧚

on connection, a client sets the "clean session" flag — sometimes also known as the "clean start" flag. two names, same flag, we love a versatile icon.

• if clean session is set to false, the connection is treated as durable. this means when the client disconnects, any subscriptions it has will remain, and any subsequent QoS 1 or 2 messages will be stored until it connects again in the future. it waits for you. 🥹
• if clean session is true, then all subscriptions will be removed for the client when it disconnects. clean slate, no baggage.

---

🌈 WILLS 🌈

when a client connects to a broker, it may inform the broker that it has a will. this is a message the client wishes the broker to send when the client disconnects unexpectedly. 💀✨

the will message has a topic, a QoS and a retain status, just the same as any other message. no special treatment, it's just built different by being ominous.

---

👑 SEE ALSO 👑

mosquitto(7), mosquitto(8), mosquitto_pub(1), mosquitto_sub(1)

---

💖 AUTHOR 💖

Roger Light <roger@atchoo.org> — the legend themselves 🫶

---

and that's the page bestie!! 💅 this gorgeous little artifact comes to you courtesy of the Mosquitto Project, dated 02/09/2026, living as always in the MQTT(7) section. now go publish something iconic. 🦋🎀🌸