PROXY Protocol

This is a HiveMQ Enterprise Edition feature. Find out more about HiveMQ Editions.

HiveMQ supports the PROXY protocol for all listeners. The PROXY protocol is a TCP based protocol that allows the transportation of client details like IP address and port over multiple proxies. This is very useful if you are running your HiveMQ brokers behind a load balancer that proxies the TCP connection.
Without the use of the PROXY protocol, useful client information like IP address, port and SSL information is lost since the broker only "sees" the final TCP connection to the load balancer and has no information about the original client.

HiveMQ is compatible with all load balancers and proxies that support the PROXY protocol in version 1 or 2. Custom TLVs are as well supported as standard TLVs (these are used to carry custom information like X.509 client certificate information).

PROXY Protocol cannot be used when TLS is terminated on HiveMQ.

How does the PROXY protocol work?

The PROXY protocol adds meta information about the proxied TCP client (which happens to be an MQTT client in HiveMQ scenarios) at the beginning of the TCP stream, which means the PROXY protocol information is the first information that is sent over the wire, even before the MQTT CONNECT message.

HiveMQ is protocol-agnostic and allows you to connect to the same listener with or without the PROXY header present.

When to use the PROXY protocol?

MQTT 3.1 and 3.1.1 do not provide any headers for metadata that would allow carrying the original client’s IP address to the MQTT broker (like with HTTP’s X-Forwarded-For headers) in case the original TCP connection is proxied by a load balancer.

The use of the PROXY protocol can be beneficial for every deployment in which the MQTT clients do not connect directly to the broker and are using a load balancer or proxy instead. The load balancer or proxy must be configured correctly to send the PROXY protocol information to HiveMQ.

The benefit of using the PROXY protocol is that debug logging utilizes the original client’s IP address forwarded by the proxy. There is no downside in enabling the PROXY protocol. Keep in mind to only enable the PROXY protocol on listeners that aren’t public facing and are only available to trusted resources.

Extension System

With the HiveMQ extension system you have complete access to all PROXY protocol information of MQTT clients. So it’s possible to add custom business logic to your extensions based on the PROXY information.

You can learn more about PROXY information and the extension system in the HiveMQ extension documentation.

Configuration

Both versions, 1 (which is text based) and 2 (which is binary), are supported by HiveMQ transparently. This means you just need to specify that you want to use the PROXY protocol and HiveMQ will automatically detect the used version, when a client connects.

By default the PROXY protocol is disabled for every listener. The following snippet shows how to enable the proxy protocol for specific listeners:

Multiple Listeners

<?xml version="1.0"?>
<hivemq xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

  <listeners>
      <tcp-listener>
          <port>1883</port>
          <bind-address>0.0.0.0</bind-address>
          <proxy-protocol>true</proxy-protocol>
      </tcp-listener>
  </listeners>

</hivemq>

All listeners support the PROXY protocol, so you can also use the PROXY protocol in conjunction with WebSockets or Secure TCP Listener.

PROXY protocol and TLS

If you’re using TLS in conjunction with the PROXY protocol, the TLS handshake needs to be finished before PROXY protocol information is sent.

Custom TLVs

HiveMQ supports custom Type-Length-Values. These TLVs are available since PROXY protocol version 2.

TLVs are (potentially cascaded) key-value pairs that carry arbitrary data like SSL X509 client certificate Common Names or the TLS version used by a client that connected to the proxy. There are pre-defined TLVs in the PROXY protocol spec as well as there is room to create individual custom TLVs. Make sure that your load balancer of choice supports this feature, if you want to use TLVs.