MQTT Support for Rewrite

Last published : Sep 22, 2026
The rewrite feature supports the MQTT protocol. You can configure rewrite policies to take actions based on the parameters in the MQTT client requests and server responses.
Related information

Rewrite action for MQTT

The rewrite action for MQTT indicates the changes made to the MQTT request or response before sending it to a server or client.
Expression:
add rewrite action <name> <rewrite_type> <target> <rewrite_action>

Rewrite type for MQTT

Depending on the type of rewrite expression rule that is used, the following MQTT rewrite types are supported:
  • replace_mqtt
  • insert_before_mqtt
  • insert_after_mqtt
  • delete_mqtt
  • insert_mqtt

Rewrite target for MQTT

In the following sample examples, the MQTT rewrite feature uses policy expressions to indicate the part of the request to be modified (target) and the modification to be performed (string expression):
  • Rewrite a client ID in the connect packet using the replace_mqtt action type.
    add rewrite action rwact1 replace_mqtt MQTT.CONNECT.CLIENTID "\"xyz\""
  • Rewrite a topic in the publish request using the replace_mqtt action type.
    add rewrite action rwact1 replace_mqtt MQTT.PUBLISH.TOPIC "\"testing/test123\""
  • Rewrite to insert a property using the insert_mqtt action type.
    add rewrite action rwact1 insert_mqtt MQTT.NEW_PROPERTY("prop1", "test")
  • Delete a topic using the delete_mqtt action type.
    add rewrite action rwact2 delete_mqtt MQTT.SUBSCRIBE.TOPIC_FILTERS.TOPIC(1)

Rewrite action for MQTT

The following are the predefined rewrite actions for MQTT:
  • MQTT.NEW_KEEPALIVE(interval)
  • MQTT.NEW_PACKET_IDENTIFIER(packetID)
  • MQTT.NEW_REASON_CODE(retCode)
  • MQTT.NEW_PUBLISH(topic_name, payload)
  • MQTT.NEW_CONNECT_USERNAME(username)
  • MQTT.NEW_CONNECT_WILL_MESSAGE(will_topic, will_payload, will_Qos, will_retain)
  • MQTT.NEW_TOPIC(topic, qos)
  • MQTT.NEW_TOPIC(topic)
  • MQTT.NEW_PROPERTY(key, value)
Example for the predefined rewrite action:
add rewrite action rwact1 replace_mqtt MQTT.CONNECT.KEEPALIVE MQTT.NEW_KEEPALIVE(90)
Example for the user defined rewrite action:
add rewrite action rwact1 replace_mqtt MQTT.CONNECT.USERNAME "\"user1\""

Rewrite policy for MQTT

A rewrite policy for MQTT consists of a rule and action. The rule determines the MQTT traffic on which rewrite is applied and the action determines the action to be taken by the NetScaler appliance.
Expression:
add rewrite policy <name> <rewrite_rule> <rewrite_action>
Example:
add rewrite action insert_mqtt_username insert_mqtt MQTT.NEW_CONNECT_USERNAME("user1")
add rewrite policy rewrite_mqtt_username "MQTT.COMMAND.EQ(CONNECT) && MQTT.CONNECT.USERNAME.LENGTH.EQUALS(0) insert_mqtt_username

Bind points for MQTT

You can bind a rewrite policy globally, or to a specific load balancing virtual server or content switching virtual server. The following are the global bind points:
  • MQTT_REQ_DEFAULT
  • MQTT_REQ_OVERRIDE
  • MQTT_RES_DEFAULT
  • MQTT_RES_OVERRIDE
Expression:
  • bind rewrite global <policyName> <priority> [-type MQTT_REQ_OVERRIDE | MQTT_REQ_DEFAULT | MQTT_RES_OVERRIDE | MQTT_RES_DEFAULT]
  • bind lb|cs vserver <virtualServerName> -policyName <policyName> -priority <positiveInteger> -type REQUEST|RESPONSE
Example:
  • bind rewrite global pol1 10 -type MQTT_REQ_DEFAULT
  • add/bind lb vserver v1 -policyName pol1 -type reqUEST -priority 10

Configure a rewrite policy for MQTT

To configure a rewrite policy, follow the steps and type the commands at the command prompt:
  1. Enable the rewrite feature on the NetScaler appliance.
    enable ns feature REWRITE
  2. Add a rewrite action.
    add rewrite action rwact1 replace_mqtt MQTT.CONNECT.KEEPALIVE MQTT.NEW_KEEPALIVE(10)
  3. Add a rewrite policy.
    add rewrite policy pol1 MQTT.COMMAND.EQ(CONNECT) rwact1
  4. Configure an MQTT load balancing virtual server.
    add lb vserver v1 MQTT 1.1.1.1 1883
  5. Bind the rewrite policy globally, or to a specific load balancing virtual server.
    bind rewrite global pol1 10 -type MQTT_REQ_DEFAULT
    add/bind lb vserver v1 -policyName pol1 -type REQUEST -priority 10

Use case 1: Replace the user name in the MQTT CONNECT message with the certificate name

The administrator can configure an MQTT rewrite policy to replace the user name with the client's certificate name.
Let us consider an example. The client request has an MQTT CONNECT message, which contains the user name as "admin". This user name must be replaced with the serial number (16 digit) that is extracted from the client certificate (cert name).
The following figure shows the workflow:
Use case 1
  1. A Transport Control Protocol (TCP) request is sent to the load balancer.
  2. In the load balancer, the user name is replaced with the certificate name.
  3. The request is forwarded to the MQTT broker.
  4. This new user name is used for authorization through the webhook payload.
Sample Configuration:
add rewrite action mqtt_rw_unameact1 replace_mqtt MQTT.CONNECT.USERNAME CLIENT.SSL.CLIENT_CERT.SERIALNUMBER
add rewrite policy mqtt_rw_uname_pol1 "MQTT.COMMAND.EQ(CONNECT)" mqtt_rw_unameact1
bind cs vserver mqtt_frontend_cs -policyName mqtt_rw_uname_pol1 -priority 10 -gotoPriorityExpression END -type REQUEST

Use case 2: Provide subscription to a new TOPIC

The administrator can provide a subscription to a new TOPIC. Let us consider an example. A client request has subscription to TOPIC 1. The administrator can configure a rewrite policy to provide subscription to a new TOPIC 2. The subscription can be inserted before or after.
Sample Configuration:
  • add rewrite action act2 insert_before_mqtt MQTT.TOPIC_FILTERS.TOPIC(1) MQTT.NEW_TOPIC(topic2, 2)
  • add rewrite policy policy2 “MQTT.COMMAND.EQ(SUBSCRIBE) && MQTT.SUBSCRIBE. TOPIC_FILTERS.TOPIC.CONTAINS(\"test\")" act2