Proxy Protocol Filter (proto)

This extension has the qualified name envoy.filters.listener.proxy_protocol


This extension is intended to be robust against untrusted downstream traffic. It assumes that the upstream is trusted.


This extension extends and can be used with the following extension category:

This extension must be configured with one of the following type URLs:

PROXY protocol listener filter.


[extensions.filters.listener.proxy_protocol.v3.ProxyProtocol proto]

  "rules": [],
  "allow_requests_without_proxy_protocol": ...,
  "pass_through_tlvs": {...},
  "disallowed_versions": []

(repeated extensions.filters.listener.proxy_protocol.v3.ProxyProtocol.Rule) The list of rules to apply to requests.


(bool) Allow requests through that don’t use proxy protocol. Defaults to false.


This breaks conformance with the specification. Only enable if ALL traffic to the listener comes from a trusted source. For more information on the security implications of this feature, see


Requests of 12 or fewer bytes that match the proxy protocol v2 signature and requests of 6 or fewer bytes that match the proxy protocol v1 signature will timeout (Envoy is unable to differentiate these requests from incomplete proxy protocol requests).


(config.core.v3.ProxyProtocolPassThroughTLVs) This config controls which TLVs can be passed to filter state if it is Proxy Protocol V2 header. If there is no setting for this field, no TLVs will be passed through.


If this is configured, you likely also want to set core.v3.ProxyProtocolConfig.pass_through_tlvs, which controls pass-through for the upstream.


(repeated config.core.v3.ProxyProtocolConfig.Version) The PROXY protocol versions that won’t be matched. Useful to limit the scope and attack surface of the filter.

When the filter receives PROXY protocol data that is disallowed, it will reject the connection. By default, the filter will match all PROXY protocol versions. See for details.


When used in conjunction with the allow_requests_without_proxy_protocol, the filter will not attempt to match signatures for the disallowed versions. For example, when disallowed_versions=V2, allow_requests_without_proxy_protocol=true, and an incoming request matches the V2 signature, the filter will allow the request through without any modification. The filter treats this request as if it did not have any PROXY protocol information.


[extensions.filters.listener.proxy_protocol.v3.ProxyProtocol.KeyValuePair proto]

  "metadata_namespace": ...,
  "key": ...

(string) The namespace — if this is empty, the filter’s namespace will be used.


(string, REQUIRED) The key to use within the namespace.


[extensions.filters.listener.proxy_protocol.v3.ProxyProtocol.Rule proto]

A Rule defines what metadata to apply when a header is present or missing.

  "tlv_type": ...,
  "on_tlv_present": {...}

(uint32) The type that triggers the rule - required TLV type is defined as uint8_t in proxy protocol. See the spec for details.


(extensions.filters.listener.proxy_protocol.v3.ProxyProtocol.KeyValuePair) If the TLV type is present, apply this metadata KeyValuePair.