mirror of
https://github.com/coredns/coredns.git
synced 2026-10-17 15:55:47 -04:00
3909cc187c
The proxyproto plugin parsed PROXY protocol v2 headers only to recover the real client address; the TLV vector was discarded, so downstream plugins had no way to read values such as the AWS VPC endpoint ID, SSL client CN, or vendor-specific custom TLVs. Add an opt-in `tlv_metadata` option. When set, the connection's raw PPv2 TLV vector is captured and the plugin, acting as a metadata.Provider, publishes it under the `proxyproto/tlv` label as a hex-encoded string. Consumers decode and split it with proxyproto.SplitTLVs. The option is off by default, so existing deployments skip the extra per-connection processing and behave exactly as before. PROXY protocol v1 connections, which carry no TLVs, are unaffected. Capture spans all transports: dns:// (UDP and TCP), tls:// (DoT), https:// (DoH), grpc://, quic:// (DoQ), and https3:// (DoH3). QUIC-based transports require udp_session_tracking, since the PPv2 header arrives as a standalone first datagram ahead of the QUIC handshake. Includes unit tests for capture, the metadata provider (direct and through the real metadata chain), v1 compatibility, and option parsing, plus README and man page updates. Fixes #8633 Signed-off-by: Mekias Yohannes <mekias@amazon.com> Co-authored-by: Mekias Yohannes <mekias@amazon.com>
144 lines
4.9 KiB
Markdown
144 lines
4.9 KiB
Markdown
# proxyproto
|
|
|
|
## Name
|
|
|
|
*proxyproto* - add [PROXY protocol](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt) support.
|
|
|
|
## Description
|
|
|
|
This plugin adds support for the PROXY protocol version 1 and 2. It allows CoreDNS to receive
|
|
connections from a load balancer or proxy that uses the PROXY protocol to forward the original
|
|
client's IP address and port information.
|
|
|
|
## Syntax
|
|
|
|
~~~ txt
|
|
proxyproto {
|
|
allow <CIDR...>
|
|
default <use|ignore|reject|skip>
|
|
udp_session_tracking <duration> [max_sessions]
|
|
tlv_metadata
|
|
}
|
|
~~~
|
|
|
|
If `allow` is unspecified, PROXY protocol headers are accepted from all IP addresses.
|
|
The `default` option controls how connections from sources not listed in `allow` are handled.
|
|
If `default` is unspecified, it defaults to `ignore`.
|
|
The possible values are:
|
|
|
|
- `use`: accept and use PROXY protocol headers from these sources
|
|
- `ignore`: accept and ignore PROXY protocol headers from other sources
|
|
- `reject`: reject connections with PROXY protocol headers from other sources
|
|
- `skip`: skip PROXY protocol processing for connections from other sources, treating them as normal connections preserving the PROXY protocol headers.
|
|
|
|
The `udp_session_tracking <duration> [max_sessions]` option enables UDP session state tracking
|
|
for Cloudflare Spectrum's PROXY Protocol v2 over UDP. Spectrum sends the PPv2 header as a
|
|
standalone first datagram (with no DNS payload). Subsequent datagrams from the same client arrive
|
|
without any header. When this option is set to a positive duration, the real client address from
|
|
the header-only datagram is cached (keyed by the Spectrum-side remote address) for that duration
|
|
and automatically applied to all subsequent headerless datagrams within that window. The TTL is
|
|
refreshed on each matching packet. The optional `max_sessions` argument caps the number of
|
|
concurrent sessions in the LRU cache (default: 10240). This option has no effect for TCP
|
|
connections.
|
|
|
|
The `tlv_metadata` option exposes the PROXY Protocol v2 [TLV](https://www.haproxy.org/download/2.3/doc/proxy-protocol.txt)
|
|
(Type-Length-Value) vector from the header to downstream plugins via the
|
|
[*metadata*](../metadata/README.md) plugin. When set, and the *metadata* plugin is enabled, the
|
|
raw TLV vector is published under the label `proxyproto/tlv` as a hex-encoded string. Consumers
|
|
decode the hex and split it with `proxyproto.SplitTLVs` from
|
|
`github.com/pires/go-proxyproto` to read individual TLVs (e.g. the AWS VPC endpoint ID, SSL
|
|
client CN, or vendor-specific custom TLVs). This option is opt-in: without it, TLVs are not
|
|
captured and no extra per-connection processing occurs. It applies to all transports: `dns://`
|
|
(UDP and TCP), `tls://` (DoT), `https://` (DoH), `grpc://`, `quic://` (DoQ), and `https3://`
|
|
(DoH3).
|
|
|
|
For the QUIC-based transports (`quic://` and `https3://`), the PPv2 header arrives as a
|
|
standalone first datagram ahead of the QUIC handshake, so TLV capture additionally requires
|
|
`udp_session_tracking` to be enabled; the cached session links the subsequent headerless QUIC
|
|
datagrams to the header's source and TLVs.
|
|
|
|
## Metadata
|
|
|
|
When the `tlv_metadata` option and the *metadata* plugin are both enabled, the following metadata
|
|
label is made available:
|
|
|
|
- `proxyproto/tlv`: the raw PPv2 TLV vector, hex-encoded. Only set when the request's connection
|
|
carried a PPv2 header with at least one TLV.
|
|
|
|
## Examples
|
|
|
|
In this configuration, we allow PROXY protocol connections from all IP addresses:
|
|
|
|
~~~ corefile
|
|
. {
|
|
proxyproto
|
|
forward . /etc/resolv.conf
|
|
}
|
|
~~~
|
|
|
|
In this configuration, we only allow PROXY protocol connections from the specified CIDR ranges
|
|
and ignore proxy protocol headers from other sources:
|
|
|
|
~~~ corefile
|
|
. {
|
|
proxyproto {
|
|
allow 192.168.1.1/32 192.168.0.1/32
|
|
}
|
|
forward . /etc/resolv.conf
|
|
}
|
|
~~~
|
|
|
|
In this configuration, we only allow PROXY protocol headers from the specified CIDR ranges and reject
|
|
connections without valid PROXY protocol headers from those sources:
|
|
|
|
~~~ corefile
|
|
. {
|
|
proxyproto {
|
|
allow 192.168.1.1/32
|
|
default reject
|
|
}
|
|
forward . /etc/resolv.conf
|
|
}
|
|
~~~
|
|
|
|
In this configuration, we enable UDP session tracking for Cloudflare Spectrum's PPv2-over-UDP
|
|
with a 28-second TTL (slightly shorter than Spectrum's 30-second UDP idle timeout) and the
|
|
default session cap of 10240:
|
|
|
|
~~~ corefile
|
|
. {
|
|
proxyproto {
|
|
allow 192.168.1.1/32
|
|
udp_session_tracking 28s
|
|
}
|
|
forward . /etc/resolv.conf
|
|
}
|
|
~~~
|
|
|
|
In this configuration, the session cap is raised to 20480:
|
|
|
|
~~~ corefile
|
|
. {
|
|
proxyproto {
|
|
allow 192.168.1.1/32
|
|
udp_session_tracking 28s 20000
|
|
}
|
|
forward . /etc/resolv.conf
|
|
}
|
|
~~~
|
|
|
|
In this configuration, PPv2 TLVs are exposed to downstream plugins as metadata. The *metadata*
|
|
plugin must also be enabled. Here the *log* plugin records the raw TLV vector:
|
|
|
|
~~~ corefile
|
|
. {
|
|
metadata
|
|
proxyproto {
|
|
allow 192.168.1.1/32
|
|
tlv_metadata
|
|
}
|
|
forward . /etc/resolv.conf
|
|
log . "{remote} {/proxyproto/tlv}"
|
|
}
|
|
~~~
|