Debian Codegraph @

docs/services/push/mqtt/index.md

raw
1 # MQTT
2
3 MQTT is a lightweight messaging protocol for small sensors and mobile devices, ideal for IoT and low-bandwidth environments. Upstream docs: <https://mqtt.org/>
4
5 ## Features
6
7 - __QoS Levels__: Support for Quality of Service levels 0 (at most once), 1 (at least once), and 2 (exactly once)
8 - __Retained Messages__: Messages can be retained by the broker for new subscribers
9 - __TLS/SSL Support__: Secure connections via the `mqtts://` scheme
10 - __Authentication__: Username/password authentication
11 - __Clean Session__: Control whether the broker maintains session state
12 - __Lazy Initialization__: The MQTT client is initialized on the first send, allowing runtime configuration changes before connection
13
14 ## Getting Started
15
16 MQTT is widely used in IoT, home automation, and real-time messaging applications.
17 The protocol is supported by many popular brokers:
18
19 - __Mosquitto__: A popular open-source MQTT broker
20 - __Home Assistant__: Built-in MQTT support for smart home automation
21 - __EMQX__: Enterprise-grade MQTT broker
22 - __HiveMQ__: Scalable MQTT platform
23
24 To send notifications via MQTT, you need a running MQTT broker and a topic to publish to.
25 Topics use a hierarchical naming scheme with forward slashes (e.g., `home/alerts`, `sensors/temperature`).
26
27 ## URL Formats
28
29 The MQTT service supports two URL schemes for connection security:
30
31 - __`mqtt://`__: Standard unencrypted connection (port 1883 by default)
32
33 !!! Info ""
34 mqtt://[__`username`__[:__`password`__]@]__`host`__[:__`port`__]/__`topic`__
35
36 - __`mqtts://`__: TLS-encrypted connection (port 8883 by default)
37
38 !!! Info ""
39 mqtts://[__`username`__[:__`password`__]@]__`host`__[:__`port`__]/__`topic`__
40
41 --8<-- "docs/services/push/mqtt/config.md"
42
43 !!! Warning "TLS Configuration Options"
44
45 The following options control TLS behavior:
46
47 - __`disabletls`__: When set to `yes`, forces an **unencrypted connection** even if the `mqtts://` scheme is used. This overrides the scheme's implicit TLS requirement.
48
49 - __`disabletlsverification`__: When set to `yes`, disables TLS certificate verification while still using encryption. This is useful for self-signed certificates.
50
51 !!! Danger "Security Warning: Silent TLS Downgrade"
52
53 Setting __`disabletls=yes`__ with `mqtts://` will force an unencrypted connection despite the secure scheme. This is **likely unexpected behavior** and can cause silent downgrades where you believe traffic is encrypted but it is not.
54
55 **Recommendation**: If you intentionally want an unencrypted connection, use `mqtt://` (non-TLS scheme) instead of combining `mqtts://` with `disabletls=yes`.
56
57 !!! Tip "When to Use `disabletls=yes`"
58
59 This option is intended for specific edge cases, such as:
60
61 - **TLS-terminating proxy**: When connecting through a proxy that handles TLS termination, where the connection from client-to-proxy uses TLS but proxy-to-broker is plain MQTT. For example, a reverse proxy like Traefik or nginx that terminates TLS and forwards to an internal MQTT broker.
62 - **Testing environments**: Local development where encryption is not required.
63
64 ## Lazy Initialization
65
66 The MQTT client uses lazy initialization, meaning the connection to the broker is not established until the first message is sent. This design allows runtime configuration changes to take effect before the connection is created.
67
68 ### How It Works
69
70 1. When you call `Initialize()`, the service parses the URL and stores the configuration, but does not create the MQTT client
71 2. On the first call to `Send()`, the client is initialized with the current configuration
72 3. Once initialized, the client is reused for all subsequent sends
73
74 ### Error Behavior
75
76 If the connection attempt during lazy initialization fails, the following behavior applies:
77
78 - The error is returned to the caller immediately
79 - The internal client remains uninitialized after a failed attempt
80 - Subsequent `Send()` calls will retry initialization, allowing for transient failure recovery
81
82 This retry behavior means that temporary network issues or broker unavailability can be resolved on the next `Send()` call without requiring a new call to `Initialize()`.
83
84 ### Runtime Configuration
85
86 This lazy approach allows you to override connection settings (Host, Port, Username, Password, TLS settings) via params on the first `Send()` call:
87
88 ```go title="Example Lazy Initialization Runtime Configuration"
89 // Placeholder MQTT URL (will be overridden on first send)
90 mqttURL := "mqtt://placeholder:1883/topic"
91
92 // Create a logger for the service
93 logger := log.New(os.Stdout, "mqtt: ", log.LstdFlags)
94
95 // The message to send
96 message := "Hello from shoutrrr!"
97
98 // Initialize with a placeholder URL
99 service.Initialize(mqttURL, logger)
100
101 // Override connection settings on first send
102 params := types.Params{
103 "host": "actual-broker.example.com",
104 "username": "actual-user",
105 "password": "actual-password",
106 }
107 service.Send(message, &params)
108 ```
109
110 !!! Note
111 Configuration changes after the first `Send()` call will only affect message-related settings (Topic, QoS, Retained), not connection settings. The client connection cannot be reconfigured after initialization.
112
113 ## Examples
114
115 !!! Example "Basic Notification"
116 ```uri
117 mqtt://broker.example.com/notifications
118 ```
119
120 !!! Example "With Authentication"
121 ```uri
122 mqtt://user:[email protected]:1883/home/alerts
123 ```
124
125 !!! Example "Secure Connection"
126 ```uri
127 mqtts://user:[email protected]:8883/home/alerts
128 ```
129
130 !!! Example "With QoS and Retained Message"
131 ```uri
132 mqtt://broker.example.com/alerts?qos=1&retained=yes
133 ```
134
135 !!! Example "Home Assistant"
136 ```uri
137 mqtt://homeassistant.local:1883/homeassistant/notification
138 ```
139
140 !!! Example "Mosquitto broker with custom client ID"
141 ```uri
142 mqtt://mosquitto.example.com:1883/sensors/alerts?clientid=shoutrrr-alerts&qos=2
143 ```
144
145 !!! Example "Self-signed Certificate"
146 ```uri
147 mqtts://broker.local:8883/secure/alerts?disabletlsverification=yes
148 ```
149
150 !!! Example "Full Configuration"
151 ```uri
152 mqtts://admin:[email protected]:8883/production/alerts?clientid=prod-shoutrrr&qos=1&retained=yes&cleansession=no
153 ```