From e87f980d42d90ac64105d13b3badb6dffab72553 Mon Sep 17 00:00:00 2001 From: Artem Boldariev Date: Wed, 18 Oct 2023 16:51:06 +0300 Subject: [PATCH] Document the new PROXY-related options for dig This commit adds new documentation for +[no]proxy and +[no]proxy-plain dig options. --- bin/dig/dig.rst | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/bin/dig/dig.rst b/bin/dig/dig.rst index 32029417f5..71dce3ec36 100644 --- a/bin/dig/dig.rst +++ b/bin/dig/dig.rst @@ -507,6 +507,44 @@ abbreviation is unambiguous; for example, :option:`+cd` is equivalent to mandatory. Responses to padded queries may also be padded, but only if the query uses TCP or DNS COOKIE. +.. option:: +proxy[=src_addr[#src_port]-dst_addr[#dst_port]], +noproxy + + When this option is set, :program:`dig` adds PROXYv2 headers to the + queries. When source and destination addresses are specified, the + headers contain them and use the ``PROXY`` command. It means for + the remote peer that the queries were sent on behalf of another + node and that the PROXYv2 header reflects the original connection + endpoints. The default source port is ``0`` and destination port is + `53`. + + For encrypted DNS transports, to prevent accidental information + leakage, encryption is applied to the PROXYv2 headers: the headers + are sent right after the handshake process has been completed. + + For plain DNS transports, no encryption is applied to the PROXYv2 + headers. + + If the addressees are omitted, PROXYv2 headers, that use the + ``LOCAL`` command set, are added instead. For the remote peer, that + means that the queries were sent on purpose without being relayed, + so the real connection endpoint addresses must be used. + +.. option:: +proxy-plain[=src_addr[#src_port]-dst_addr[#dst_port], +noproxy-plain + + The same as ``+[no]proxy``, but instructs ``dig`` to send PROXYv2 + headers ahead of any encryption, before any handshake messages are + sent. That makes :program:`dig` behave exactly how it is described + in the PROXY protocol specification, but not all software expects + such behaviour. + + Please consult the software documentation to find out if you need + this option. (for example, ``dnsdist`` expects encrypted PROXYv2 + headers sent over TLS when encryption is used, while ``HAProxy`` + and many other software packages expect plain ones). + + For plain DNS transports the option is effectively an alias for the + ``+[no]proxy`` described above. + .. option:: +qid=value This option specifies the query ID to use when sending queries.