From c9350c1fc6e1d9b13a6b5ad9d5d7df98db42b176 Mon Sep 17 00:00:00 2001
From: Masaori Koshiba <masaori@apache.org>
Date: Tue, 20 Aug 2024 11:43:10 +0900
Subject: [PATCH] Document change of fqdn field (sni.yaml)

---
 doc/admin-guide/files/sni.yaml.en.rst | 30 ++++++++++++++++++++-------
 doc/release-notes/upgrading.en.rst    |  8 +++++--
 2 files changed, 28 insertions(+), 10 deletions(-)

diff --git a/doc/admin-guide/files/sni.yaml.en.rst b/doc/admin-guide/files/sni.yaml.en.rst
index 569d176f9c8..4b6448fab09 100644
--- a/doc/admin-guide/files/sni.yaml.en.rst
+++ b/doc/admin-guide/files/sni.yaml.en.rst
@@ -57,7 +57,26 @@ The following fields make up the key for each item in the configuration file.
 ========================= ========= ========================================================================================
 Key                       Direction Meaning
 ========================= ========= ========================================================================================
-fqdn                      Both      Fully Qualified Domain Name.
+fqdn                      Both      Fully Qualified Domain Name. Matching depends on the order of entries (like :file:`remap.config`)
+
+                                    Wildcard Support:
+                                      1. Allow single left-most ``*``
+                                      2. Do NOT support regex
+                                      3. Allow ``$1`` (capturing) support in the ``tunnel_route`` field
+
+                                      For example:
+                                        Supported:
+                                          - ``*.example.com``
+                                          - ``*``
+
+                                        NOT Supported:
+                                          - ``foo[0-9]+.example.com`` (regex)
+                                          - ``bar.*.example.net`` (``*`` in the middle)
+                                          - ``*.bar.*.com`` (multiple ``*``)
+                                          - ``*.*.baz.com`` (multiple ``*``)
+                                          - ``baz*.example.net`` (partial wildcard)
+                                          - ``*baz.example.net`` (partial wildcard)
+                                          - ``b*z.example.net`` (partial wildcard)
 
 inbound_port_ranges       Inbound   The port ranges for the inbound connection in the form ``port`` or
                                     ``min-max``.
@@ -237,9 +256,8 @@ quic                                     Inbound   Indicates whether QUIC connec
                                                    name. More broadly, you will also need to configure :ts:cv:`proxy.config.http.server_ports` to
                                                    open ports for QUIC.
 
-tunnel_route                             Inbound   Destination as an FQDN and port, separated by a colon ``:``.
-                                                   Match group number can be specified by ``$N`` where N should refer to a specified group
-                                                   in the FQDN, ``tunnel_route: $1.domain``.
+tunnel_route                             Inbound   Destination as an FQDN and port, separated by a colon ``:``. Capturing matched wildcard in
+                                                   the ``fqdn`` field is supported by ``$1``. For example: ``tunnel_route: $1.domain``.
 
                                                    This will forward all traffic to the specified destination without first terminating
                                                    the incoming TLS connection.
@@ -408,13 +426,9 @@ Use FQDN captured group to match in ``tunnel_route``.
    sni:
    - fqdn: '*.foo.com'
      tunnel_route: '$1.myfoo'
-   - fqdn: '*.bar.*.com'
-     tunnel_route: '$2.some.$1.yahoo'
 
 FQDN ``some.foo.com`` will match and the captured string will be replaced in the ``tunnel_route`` which will end up being
 ``some.myfoo``.
-Second part is using multiple groups, having ``bob.bar.example.com`` as FQDN, ``tunnel_route`` will end up being
-``bar.some.bob.yahoo``.
 
 Establish a blind tunnel to the backend server, connecting to the server's port with the destination port specified
 in the Proxy Protocol from the inbound connection. Remember to add any expected values for ``{proxy_protocol_port}`` to
diff --git a/doc/release-notes/upgrading.en.rst b/doc/release-notes/upgrading.en.rst
index 902f12dbc79..ff3b0962ec2 100644
--- a/doc/release-notes/upgrading.en.rst
+++ b/doc/release-notes/upgrading.en.rst
@@ -184,10 +184,14 @@ The following :file:`records.yaml` changes have been made:
 The following changes have been made to the :file:`sni.yaml` file:
 
 - ``disable_h2`` has been removed. Use ``http2`` with :code:`off` instead.
-- The ``ip_allow`` key can now take a reference to a file containing the ip
-  allow rules
+- The ``ip_allow`` key can now take a reference to a file containing the ip allow rules
 - ``valid_tls_versions_in`` has been deprecated. Use ``valid_tls_version_min_in`` and ``valid_tls_version_max_in`` instead.
+- Simplify wildcard support and matching order of the ``fqdn`` field
 
+  * Allow single left-most ``*``
+  * Do NOT support regex
+  * Allow ``$1`` (capturing) support in the ``tunnel_route`` field
+  * Matching depends on the order of entries (like :file:`remap.config`)
 
 Plugins
 -------