Document the new PROXY-related options for dig

This commit adds new documentation for +[no]proxy and +[no]proxy-plain
dig options.

diff --git a/bin/dig/dig.rst b/bin/dig/dig.rst
index 32029417f5ca9b87334881dc8e61f2cc3ca41b07..71dce3ec36e0c955ffa53042eaf73ca1907a93c2 100644 (file)
--- 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.