# Easegress Configuration for MQTT Proxying of IoT Traffic: A Complete Guide > Configure Easegress for MQTT proxying of IoT traffic with the MQTTProxy object. Expose TCP ports, route MQTT packets, and support bidirectional message flow for seamless IoT communication. - Repository: [MegaEase/easegress](https://github.com/megaease/easegress) - Tags: how-to-guide - Published: 2026-03-07 --- **Easegress configures MQTT proxying through the `MQTTProxy` object kind, which exposes TCP ports for IoT devices, routes MQTT packet types to protocol-specific pipelines, and supports bidirectional message flow via broker mode and HTTP endpoints.** Easegress is a Cloud Native traffic orchestration system that implements a first-class MQTT proxy for handling IoT traffic at scale. The proxy is defined as a top-level resource processed by the protocol-agnostic pipeline engine, enabling seamless integration between MQTT-enabled devices and backend systems like Kafka according to the megaease/easegress source code. ## MQTTProxy Architecture and Core Components The MQTT proxy implementation centers on the `MQTTProxy` spec defined in [`pkg/object/mqttproxy/spec.go`](https://github.com/megaease/easegress/blob/main/pkg/object/mqttproxy/spec.go). This specification describes how the proxy accepts connections, handles encryption, routes packets, and manages broker behavior. ### The MQTTProxy Spec Structure The `Spec` struct in [`pkg/object/mqttproxy/spec.go`](https://github.com/megaease/easegress/blob/main/pkg/object/mqttproxy/spec.go) defines the configuration schema with these key fields: - **Port** – The TCP port (default 1883) where MQTT clients connect - **UseTLS** – Boolean flag to enable TLS encryption - **Certificate** – Array of certificates processed by `Spec.tlsConfig()` into a Go `tls.Config` - **Rules** – Array routing different MQTT packet types to specific pipelines - **BrokerMode** – Boolean enabling bidirectional message distribution - **RetryInterval** – Timing for backend reconnection attempts ### Broker Mode Implementation When `brokerMode: true` is configured, the proxy forwards published messages to both the backend system (e.g., Kafka) and any subscribed MQTT clients. Without broker mode, traffic flows only to the backend. This behavior is implemented in [`pkg/object/mqttproxy/broker.go`](https://github.com/megaease/easegress/blob/main/pkg/object/mqttproxy/broker.go), which manages subscription handling and message distribution to active client sessions. ### Packet Routing via Rules Each rule in the `Rules` array matches a specific `packetType` (Connect, Publish, Subscribe, Unsubscribe, or Disconnect) and routes matching packets to a named pipeline. The rule matching logic resides in [`pkg/object/mqttproxy/mqttproxy.go`](https://github.com/megaease/easegress/blob/main/pkg/object/mqttproxy/mqttproxy.go), where the proxy builds internal URLs and registers handlers for the pipeline engine. ## Configuring TLS for Secure IoT Connections To encrypt traffic between IoT devices and the proxy, set `useTLS: true` and provide certificate data: ```yaml useTLS: true certificate: - name: cert1 cert: |- -----BEGIN CERTIFICATE----- MIIDXTCCAkWgAwIBAgIJAJC1HiIAZAiU... -----END CERTIFICATE----- key: |- -----BEGIN PRIVATE KEY----- MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgw... -----END PRIVATE KEY----- ``` The `Spec.tlsConfig()` method in [`pkg/object/mqttproxy/spec.go`](https://github.com/megaease/easegress/blob/main/pkg/object/mqttproxy/spec.go) (lines 8-23) transforms this YAML configuration into a functional Go `tls.Config` used by the TCP listener. ## Pipeline Integration for MQTT Traffic The MQTT proxy leverages Easegress's protocol-aware pipeline system. Each rule references a pipeline containing MQTT-specific filters that process packets before forwarding. ### Authentication Pipelines for Connect Packets When `packetType: Connect` matches, the pipeline typically contains the `MQTTClientAuth` filter to validate credentials: ```yaml name: pipeline-mqtt-auth kind: Pipeline protocol: MQTT flow: - filter: auth filters: - name: auth kind: MQTTClientAuth salt: mySalt auth: - username: device001 saltedSha256Pass: 1bc1a361f17092bc7af4b2f82bf9194ea9ee2ca49eb2e53e39f555bc1eeaed74 ``` ### Backend Integration Pipelines for Publish Packets Publish packets route to pipelines containing the `KafkaMQTT` filter for backend forwarding: ```yaml name: pipeline-mqtt-publish kind: Pipeline protocol: MQTT flow: - filter: publish-kafka-backend filters: - name: publish-kafka-backend kind: KafkaMQTT backend: ["127.0.0.1:9092"] topic: default: sensor-data-topic ``` ## HTTP Publish API for Backend Services Backend microservices can push messages to subscribed IoT clients via the HTTP endpoint implemented in [`pkg/object/mqttproxy/broker.go`](https://github.com/megaease/easegress/blob/main/pkg/object/mqttproxy/broker.go). The handler `httpTopicsPublishHandler` (lines 150-170) accepts POST requests at `/apis/v1/mqttproxy/{name}/topics/publish`. Send messages using standard HTTP clients: ```bash curl -X POST http://127.0.0.1:2381/apis/v1/mqttproxy/mqttproxy/topics/publish \ -H "Content-Type: application/json" \ -d '{ "topic": "Beijing/Phone/Update", "qos": 1, "payload": "time to update", "base64": false }' ``` The request body requires `topic`, `qos`, and `payload` fields, with an optional `base64` boolean for binary data encoding. ## Practical Configuration Example Deploy a complete MQTT proxy by combining the spec with its referenced pipelines in a single YAML file: ```yaml kind: MQTTProxy name: mqttproxy port: 1883 useTLS: true certificate: - name: iot-cert cert: |- -----BEGIN CERTIFICATE----- ... -----END CERTIFICATE----- key: |- -----BEGIN PRIVATE KEY----- ... -----END PRIVATE KEY----- rules: - when: packetType: Connect pipeline: pipeline-mqtt-auth - when: packetType: Publish pipeline: pipeline-mqtt-publish brokerMode: true connectionLimit: requestRate: 1000 clientPublishLimit: requestRate: 5000 timePeriod: 1 --- name: pipeline-mqtt-auth kind: Pipeline protocol: MQTT flow: - filter: auth filters: - name: auth kind: MQTTClientAuth salt: mySalt auth: - username: test saltedSha256Pass: 1bc1a361f17092bc7af4b2f82bf9194ea9ee2ca49eb2e53e39f555bc1eeaed74 --- name: pipeline-mqtt-publish kind: Pipeline protocol: MQTT flow: - filter: kafka-backend filters: - name: kafka-backend kind: KafkaMQTT backend: ["127.0.0.1:9092"] topic: default: kafka-topic ``` Apply this configuration using the Easegress CLI: ```bash egctl create -f mqtt-proxy.yaml ``` ## Rate Limiting and Traffic Management The MQTT proxy supports granular rate limiting through fields in [`pkg/object/mqttproxy/spec.go`](https://github.com/megaease/easegress/blob/main/pkg/object/mqttproxy/spec.go) using the `RateLimit` struct: - **ConnectionLimit** – Controls new connection establishment rates (`requestRate`, `bytesRate`) - **ClientPublishLimit** – Throttles publish packets per client connection with configurable `timePeriod` These limits prevent resource exhaustion during traffic spikes from high-volume IoT deployments. ## Summary - **MQTTProxy** is a top-level resource kind defined in [`pkg/object/mqttproxy/spec.go`](https://github.com/megaease/easegress/blob/main/pkg/object/mqttproxy/spec.go) that exposes TCP ports (default 1883) for IoT device connections. - **Broker mode** enables bidirectional messaging, forwarding publishes to both backend systems and subscribed MQTT clients via logic in [`pkg/object/mqttproxy/broker.go`](https://github.com/megaease/easegress/blob/main/pkg/object/mqttproxy/broker.go). - **Rules** map MQTT packet types (Connect, Publish, Subscribe) to protocol-specific pipelines containing filters like `MQTTClientAuth` and `KafkaMQTT`. - **TLS encryption** is configured via `useTLS: true` and certificate arrays processed by `Spec.tlsConfig()`. - **Backend integration** works bidirectionally: IoT devices publish through MQTT while backend services push updates via the HTTP endpoint `/apis/v1/mqttproxy/{name}/topics/publish`. ## Frequently Asked Questions ### What is the default port for the Easegress MQTT proxy? The default port is **1883**, the standard MQTT port, configurable via the `port` field in the MQTTProxy spec. You can change this to any available TCP port, commonly using 8883 when `useTLS: true` is enabled for MQTT over TLS. ### How does broker mode affect message routing? When `brokerMode: true` is set, the proxy acts as a full MQTT broker, storing subscriptions in [`pkg/object/mqttproxy/topicmgr.go`](https://github.com/megaease/easegress/blob/main/pkg/object/mqttproxy/topicmgr.go) and forwarding published messages to both the configured backend (e.g., Kafka) and any connected clients subscribed to matching topics. Without broker mode, messages flow only to the backend pipeline, making the proxy act as a simple protocol translator. ### Can the Easegress MQTT proxy authenticate clients with custom credentials? Yes. The `MQTTClientAuth` filter in authentication pipelines validates usernames against salted SHA256 hashes. Configure the `salt` field and `auth` array in the filter configuration within a pipeline referenced by a Connect packet rule, as implemented in the authentication logic referenced by [`pkg/object/mqttproxy/mqttproxy.go`](https://github.com/megaease/easegress/blob/main/pkg/object/mqttproxy/mqttproxy.go). ### How do backend services publish messages to MQTT clients? Backend services POST to the HTTP endpoint `/apis/v1/mqttproxy/{name}/topics/publish` with a JSON body containing the `topic`, `qos`, and `payload`. The handler `httpTopicsPublishHandler` in [`pkg/object/mqttproxy/broker.go`](https://github.com/megaease/easegress/blob/main/pkg/object/mqttproxy/broker.go) processes these requests and distributes the message to subscribed clients through the topic manager, enabling server-side logic to communicate with IoT devices without maintaining MQTT client connections.