[master] 9db64085f Document .via and .authority VCL backend attributes

[Nils Goroll]

commit 9db64085f1fdc20dd95be86212c2d29d15156dbf
Author: Nils Goroll <nils.goroll at uplex.de>
Date:   Tue May 24 12:19:39 2022 +0200

    Document .via and .authority VCL backend attributes

diff --git a/doc/changes.rst b/doc/changes.rst
index 4d0012a5d..7d63ec4b1 100644
--- a/doc/changes.rst
+++ b/doc/changes.rst
@@ -77,6 +77,14 @@ Varnish Cache NEXT (2023-03-15)
 
 * Backend implementations are in charge of logging their headers.
 
+* Support for backend connections through a proxy with a PROXY2
+  preamble has been added:
+
+  * VCL ``backend``\ s gained attributes ``.via`` and ``.authority``
+
+  * The ``VRT_new_backend_clustered()`` and ``VRT_new_backend()``
+    signatures have been changed
+
 ================================
 Varnish Cache 7.2.0 (2022-09-15)
 ================================
diff --git a/doc/sphinx/reference/vcl-backend.rst b/doc/sphinx/reference/vcl-backend.rst
index 048f25cdd..cd4307639 100644
--- a/doc/sphinx/reference/vcl-backend.rst
+++ b/doc/sphinx/reference/vcl-backend.rst
@@ -142,6 +142,59 @@ Send a BLOB on all newly opened connections to the backend::
 
     .preamble = :SGVsbG8gV29ybGRcbgo=:;
 
+.. _backend_definition_via:
+
+Attribute ``.via``
+------------------
+
+.. _PROXY2: https://raw.githubusercontent.com/haproxy/haproxy/master/doc/proxy-protocol.txt
+
+Name of another *proxy* backend through which to make the connection
+to the *destination* backend using the `PROXY2`_ protocol, for example::
+
+  backend proxy {
+    .path = "/path/to/proxy2_endpoint";
+  }
+  backend destination {
+    .host = "1.2.3.4";
+    .via = proxy;
+  }
+
+The *proxy* backend can also use a ``.host``\ /\ ``.port`` definition
+rather than ``.path``.
+
+Use of the ``.path`` attribute for the *destination* backend is not
+supported.
+
+The ``.via`` attribute is unrelated to ``.proxy_header``. If both are
+used, a second header is sent as per ``.proxy_header`` specification.
+
+As of this release, the *proxy* backend used with ``.via`` can not be a
+director and the protocol is fixed to `PROXY2`_.
+
+Implementation detail:
+
+If ``.via = <proxy>`` is used, a `PROXY2`_ preamble is created with
+the *destination* backend's address information as ``dst_addr``\ /\
+``dst_port`` and, optionally, other TLV attributes. The connection is
+then made to the *proxy* backend's endpoint (``path`` or ``host``\ /\
+``port``). This is technically equivalent to specifying a ``backend
+destination_via_proxy`` with a ``.preamble`` attribute containing the
+appropriate `PROXY2`_ preamble for the *destination* backend.
+
+Attribute ``.authority``
+------------------------
+
+The HTTP authority to use when connecting to this backend. If unset,
+``.host_header`` or ``.host`` are used.
+
+``.authority = ""`` disables sending an authority.
+
+As of this release, the attribute is only used by ``.via`` connections
+as a ``PP2_TYPE_AUTHORITY`` Type-Length-Value (TLV) in the `PROXY2`_
+preamble.
+
+
 Attribute ``.probe``
 --------------------
 
diff --git a/doc/sphinx/users-guide/vcl-backends.rst b/doc/sphinx/users-guide/vcl-backends.rst
index f6d7bcb09..76ef15e1c 100644
--- a/doc/sphinx/users-guide/vcl-backends.rst
+++ b/doc/sphinx/users-guide/vcl-backends.rst
@@ -150,6 +150,58 @@ more tight, maybe relying on the ``==`` operator in stead, like this::
     }
 
 
+Connecting Through a Proxy
+--------------------------
+
+.. _PROXY2: https://raw.githubusercontent.com/haproxy/haproxy/master/doc/proxy-protocol.txt
+.. _haproxy: http://www.haproxy.org/
+.. _SNI: https://en.wikipedia.org/wiki/Server_Name_Indication
+
+As of this release, Varnish can connect to an actual *destination*
+through a *proxy* using the `PROXY2`_ protocol. Other protocols may be
+added.
+
+For now, a typical use case of this feature is to make TLS-encrypted
+connections through a TLS *onloader*. The *onloader* needs to support
+dynamic connections with the destination address information taken
+from a `PROXY2`_ preamble. For example with `haproxy`_ Version 2.2 or
+higher, this snippet can be used as a basis for configuring an
+*onloader*::
+
+     # to review and adjust:
+     # - maxconn
+     # - bind ... mode ...
+     # - ca-file ...
+     #
+     listen sslon
+            mode    tcp
+            maxconn 1000
+            bind    /path/to/sslon accept-proxy mode 777
+            stick-table type ip size 100
+            stick   on dst
+            server  s00 0.0.0.0:443 ssl ca-file /etc/ssl/certs/ca-bundle.crt alpn http/1.1 sni fc_pp_authority
+            server  s01 0.0.0.0:443 ssl ca-file /etc/ssl/certs/ca-bundle.crt alpn http/1.1 sni fc_pp_authority
+            server  s02 0.0.0.0:443 ssl ca-file /etc/ssl/certs/ca-bundle.crt alpn http/1.1 sni fc_pp_authority
+            # ...
+            # A higher number of servers improves TLS session caching
+
+Varnish running on the same server/namespace can then use the
+*onloader* with the ``.via`` feature (see :ref:`backend_definition_via`)::
+
+  backend sslon {
+    .path = "/path/to/sslon";
+  }
+
+  backend destination {
+    .host = "my.https.service";
+    .port = "443";
+    .via = sslon;
+  }
+
+The ``.authority`` attribute can be used to specify the `SNI`_ for the
+connection if it differs from ``.host``.
+
+
 .. _users-guide-advanced_backend_servers-directors: