Extending the MQTT Protocol
Last month we deployed a change to Adafruit IO’s MQTT broker that allowed us to rate limit connection attempts. Although we don’t like to throttle or ban users, the change was necessary to protect Adafruit IO from abuse, and ensure the overall health of the service.
This presented a problem: How do we inform users when they have been throttled or banned? Ideally the
MQTT protocol would allow for us to inform the user using a standard response, but currently the connection
acknowledgement packet (CONNACK
) has a limited set of response codes.
The MQTT v3.1.1 protocol has the following values defined for the CONNACK
packet response code:
Value |
Return Code Response |
Description |
0 |
0x00 Connection Accepted |
Connection accepted |
1 |
0x01 Connection Refused, unacceptable protocol version |
The Server does not support the level of the MQTT protocol requested by the Client |
2 |
0x02 Connection Refused, identifier rejected |
The Client identifier is correct UTF-8 but not allowed by the Server |
3 |
0x03 Connection Refused, Server unavailable |
The Network Connection has been made but the MQTT service is unavailable |
4 |
0x04 Connection Refused, bad user name or password |
The data in the user name or password is malformed |
5 |
0x05 Connection Refused, not authorized |
The Client is not authorized to connect |
6-255 |
|
Reserved for future use |
The current set of codes didn’t allow us to clearly communicate the reason for disconnects
to our users. We have extended the list of codes in the CONNACK
packet to include connection throttle (0x06) and ban (0x07).
Value |
Return Code Response |
Description |
6 |
0x06 Connection Refused, throttled |
Client has exceeded connection rate limit. Please try again later. |
7 |
0x07 Connection Refused, banned |
The client has been banned by the server administrator. |
We have submitted these two new codes to the OASIS MQTT Technical Committee for comment, and we are adding support to our MQTT client libraries. If you would like to comment on these changes, please visit our IO forum and share your thoughts.