Stand with Ukraine flag
Try it now Pricing
MQTT Broker
Community Edition Professional Edition Cloud Edge PE Edge IoT Gateway License Server Trendz Analytics Mobile Application PE Mobile Application MQTT Broker
Documentation > Other Features > PROXY Protocol
Getting Started
Installation Architecture API FAQ
On this page

PROXY Protocol

The PROXY Protocol is a simple protocol used to safely transport connection information such as the client’s IP address across multiple layers of proxies or load balancers.

TBMQ supports both PROXY Protocol v1 and v2, enabling it to receive and process the real client IP and port, which is critical for accurate auditing, rate limiting, access control, and understanding the actual source of client connections.

  • PROXY Protocol v1: A human-readable ASCII-based format that prepends connection metadata (e.g., IP addresses and ports) to the TCP stream.
  • PROXY Protocol v2: A more efficient binary format that provides the same information as v1 but with enhanced protocol support and better performance in high-throughput environments.

By using PROXY Protocol, TBMQ can log, filter, and apply policies based on the real IP address of clients, which is otherwise masked by the proxy or load balancer.

How does the PROXY protocol work?

The PROXY Protocol appends meta-information about the original client connection at the very start of the TCP stream. This metadata is sent by the proxy or load balancer before any protocol-specific data, such as the MQTT CONNECT packet.

image

When a client connects to TBMQ through a proxy that supports PROXY Protocol, the connection flow is as follows:

  1. The proxy accepts the TCP connection from the client.
  2. The proxy immediately sends a PROXY Protocol header containing:
    • The client’s source IP and port.
    • The proxy’s destination IP and port.
    • The protocol type (TCP over IPv4 or IPv6).
  3. TBMQ, with PROXY Protocol enabled, reads this header first, extracts the real client information, and then continues processing the MQTT data (starting with the CONNECT message).
  • In PROXY Protocol v1, this header is sent in ASCII format, e.g.: 
    1

    PROXY TCP4 192.0.2.1 198.51.100.1 12345 1883\r\n
  • In PROXY Protocol v2, the header is in a binary format, more compact and efficient for high-performance systems.

This means TBMQ treats the very first bytes of every incoming connection as PROXY Protocol data, before interpreting it as an MQTT connection.

When to use the protocol?

You should enable the PROXY Protocol in TBMQ when:

  • TBMQ is deployed behind a load balancer or reverse proxy (e.g., HAProxy, AWS NLB, NGINX) that supports the PROXY Protocol.
  • You need to capture the real IP address of clients for:
    • Accurate logging of client connection details.
    • Applying IP-based security policies and rate limiting.
    • Detailed auditing and analytics based on the true client origin.

TBMQ stores the client IP address as part of the client session information. This IP address is also used in the Unauthorized Clients feature, where TBMQ tracks connection attempts from clients that fail authentication. Having the correct IP address helps in identifying the source of unauthorized access attempts and improving security monitoring.

Without PROXY Protocol, TBMQ will only see the IP of the proxy or load balancer, making it impossible to distinguish between individual clients behind the proxy. Enabling PROXY Protocol ensures TBMQ receives the actual client IP and port at connection time.

Important: Do not enable PROXY Protocol unless your proxy is properly configured to send PROXY Protocol headers. When enabled, TBMQ expects the PROXY Protocol header at the beginning of each TCP connection.

How to enable the protocol?

To enable PROXY Protocol support in TBMQ, you need to update the configuration settings for MQTT listeners. The PROXY Protocol setting applies globally to all MQTT listeners in TBMQ and cannot be configured per listener. However, future releases may introduce the ability to configure PROXY Protocol on a per-listener basis.

1
2
3
4
5

# MQTT listeners parameters
listener:
  # Enable proxy protocol support. Disabled by default. If enabled, supports both v1 and v2.
  # Useful to get the real IP address of the client in the logs, for session details info and unauthorized clients feature
  proxy_enabled: "${MQTT_PROXY_PROTOCOL_ENABLED:false}"

Set the environment variable MQTT_PROXY_PROTOCOL_ENABLED to “true”.

Important Notes:

  • When proxy_enabled is set to true, TBMQ automatically supports both PROXY Protocol v1 and v2.
  • This setting ensures that TBMQ correctly interprets the PROXY Protocol headers sent at the start of each TCP connection, before any MQTT-specific data.

HAPROXY

To forward the real client IP to TBMQ using PROXY Protocol, configure HAProxy as follows:

1

server tbmq1 192.168.1.100:1883 send-proxy
  • send-proxy: Instructs HAProxy to send PROXY Protocol v1 headers to TBMQ.
  • Replace 192.168.1.100:1883 with your TBMQ broker’s IP and port.

To use PROXY Protocol v2, change to:

1

server tbmq1 192.168.1.100:1883 send-proxy-v2
  • send-proxy-v2: Sends PROXY Protocol v2 headers to TBMQ.

You can find the full HAProxy configuration guide for enabling PROXY Protocol here.

AWS Network Load Balancer (NLB)

To use PROXY Protocol with AWS NLB, enable PROXY Protocol v2:

  1. Ensure your NLB is TCP or TLS type.
  2. Enable PROXY Protocol v2 using the AWS CLI:
1
2
3

aws elbv2 modify-target-group-attributes \
 --target-group-arn <your-target-group-arn> \
 --attributes Key=proxy_protocol_v2.enabled,Value=true

Note: AWS NLB only supports PROXY Protocol v2.

Alternatively, to enable PROXY Protocol v2 with AWS NLB in a Kubernetes environment, add the following annotation to your Service definition:

1

service.beta.kubernetes.io/aws-load-balancer-proxy-protocol: "*"
  • The * enables PROXY Protocol v2 for all source IPs.

See official AWS documentation for more details.

Considerations

  • If PROXY Protocol is enabled in TBMQ but not used by your proxy/load balancer, TBMQ will fail to interpret the initial bytes, potentially rejecting the connection.
  • If PROXY Protocol is disabled in TBMQ but enabled on your proxy/load balancer, TBMQ will misinterpret the PROXY Protocol header as part of the MQTT data, leading to connection errors or protocol parsing failures.
  • Ensure all connections to TBMQ are routed through a properly configured proxy when PROXY Protocol support is enabled.
  • PROXY Protocol should only be enabled if TBMQ is deployed behind a trusted proxy, as it allows the proxy to define client IPs.

Note: TBMQ is not protocol-agnostic regarding PROXY Protocol support. When PROXY Protocol is enabled, all connections must include the PROXY header. Mixing connections with and without the PROXY header on the same listener is not supported. Future releases may introduce more flexible handling to support mixed connection types.