MQTT ingress

The MQTT stream modules parse bounded MQTT 3.1.1 and selected MQTT 5 packets at the nginx edge. They expose CONNECT identity, can rewrite selected CONNECT fields, and attach accepted records to nginz-iotd.

Basic configuration

stream {
  server {
    listen 1883;

    mqtt_preread on;
    mqtt_iotd on;
    mqtt_iotd_operating_profile tracked;
    mqtt_iotd_rings /nginz-iot-production 4096 1024 1024 1 1;
  }
}

Use $mqtt_preread_clientid and $mqtt_preread_username in compatible stream policies after preread. mqtt_set_connect can set clientid, username, or password through an nginx complex value when a controlled rewrite is required.

Operating profiles

• tracked is the production Core default and retains delivery state required for QoS 1 and reconnect behavior.
• hybrid tracks a deterministic share of tenant/topic space and is restricted to the Evaluation lane.
• live_fast uses memory storage and accepted acknowledgements. The legacy Evaluation profile name is retained for compatibility; Free permits real production use. Current source retains outbound ownership and reconnect state in memory, while restart durability requires a selected durable profile.

The nginx setting must match mqtt.operating_profile in nginz-iotd. Mixed-profile attachment fails closed.

Packet path

After CONNECT, the stream filter shapes PUBLISH, SUBSCRIBE, UNSUBSCRIBE, DISCONNECT, and PINGREQ into broker commands. Worker-level delivery polling emits CONNACK, PUBACK, SUBACK, UNSUBACK, PUBLISH, PINGRESP, and DISCONNECT frames from nginz-iotd.

Payloads through 512 bytes travel inline. Bytes 513 through the configured max_payload_size use pointer-free payload references. The default ceiling is 65,536 bytes; the hard ceiling is 262,144 bytes.

Supported boundary

The current-source broker profile supports MQTT 3.1.1 QoS 0/1/2 and a selected MQTT 5 QoS 0/1 subset, retained messages, Wills, persistent sessions, shared subscriptions and bounded metadata. MQTT 5 application User Properties, Response Topic and Correlation Data have declared forwarding/recovery bounds. Enhanced authentication and Subscription Identifier remain unavailable. See MQTT coverage and check the installed image.

See MQTT profile for the exact packet, property, and peer boundary.