This is an automated email from the ASF dual-hosted git repository.
bneradt pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/trafficserver.git
The following commit(s) were added to refs/heads/master by this push:
new 27a993a27d Clarify SRV origin selection documentation (#13419)
27a993a27d is described below
commit 27a993a27d636a60b1d591f05c630aa0be7cf9c4
Author: Brian Neradt <[email protected]>
AuthorDate: Wed Jul 29 11:53:48 2026 -0500
Clarify SRV origin selection documentation (#13419)
SRV origin discovery is difficult to find outside the records
reference, and the existing port description contradicts Traffic Server
behavior. This can cause operators to miss the feature or constrain SRV
records unnecessarily.
This documents lookup-name construction, SRV target and port selection,
fallback behavior, HostDB caching, and the feature's use from remap
replacement URLs.
Fixes: #12440
---
doc/admin-guide/files/records.yaml.en.rst | 24 +++++++++++++++++-------
doc/admin-guide/files/remap.config.en.rst | 8 ++++++++
2 files changed, 25 insertions(+), 7 deletions(-)
diff --git a/doc/admin-guide/files/records.yaml.en.rst
b/doc/admin-guide/files/records.yaml.en.rst
index f14b03b544..fdaa7fc059 100644
--- a/doc/admin-guide/files/records.yaml.en.rst
+++ b/doc/admin-guide/files/records.yaml.en.rst
@@ -3272,13 +3272,23 @@ DNS
:overridable:
Enables (``1``) or disables (``0``) the use of SRV records for origin server
- lookup. |TS| will use weights found in the SRV record as a weighted round
- robin in origin selection. Note that |TS| will lookup
- ``_$scheme._$internet_protocol.$origin_name``. For instance, if the origin
is
- set to ``https://my.example.com``, |TS| would lookup
``_https._tcp.my.example.com``.
- Also note that the port returned in the SRV record MUST match the port being
- used for the origin (e.g. if the origin scheme is http and a default port,
there
- should be a SRV record with port 80).
+ lookup. |TS| constructs the service name
+ ``_$scheme._tcp.$origin_name`` from the scheme and host in the origin URL
+ (the replacement URL after remapping). For example, this rule::
+
+ map http://www.example.com/ https://origin.example.com/
+
+ causes |TS| to query ``_https._tcp.origin.example.com``. Given these
records::
+
+ _https._tcp.origin.example.com. 300 IN SRV 10 1 8443 server1.example.com.
+ _https._tcp.origin.example.com. 300 IN SRV 10 1 8443 server2.example.com.
+
+ |TS| resolves the selected target and connects to its SRV port, ``8443`` in
+ this example. The selected SRV port overrides any port in the origin URL.
+ |TS| honors SRV priority and weight when selecting among records. If the SRV
+ lookup returns no usable records, |TS| falls back to resolving the origin
+ host directly. SRV results are cached in HostDB according to
+ :ts:cv:`proxy.config.hostdb.ttl_mode`.
.. ts:cv:: CONFIG proxy.config.dns.dedicated_thread INT 0
diff --git a/doc/admin-guide/files/remap.config.en.rst
b/doc/admin-guide/files/remap.config.en.rst
index cd07998e83..fcde8b34dd 100644
--- a/doc/admin-guide/files/remap.config.en.rst
+++ b/doc/admin-guide/files/remap.config.en.rst
@@ -111,6 +111,14 @@ Traffic Server recognizes three space-delimited fields:
``type``,
where ``scheme`` is ``http``, ``https``, ``ws`` or ``wss``.
+ To select an origin host and port dynamically through DNS, enable
+ :ts:cv:`proxy.config.srv_enabled`. |TS| then queries the SRV
+ service derived from the replacement URL before resolving the replacement
+ host directly. For example, an ``https://origin.example.com/`` replacement
+ causes a query for ``_https._tcp.origin.example.com``. When a usable SRV
+ record is found, its target and port are used for the origin connection;
+ otherwise, |TS| falls back to the replacement host and port.
+
.. note:: A remap rule for requests that upgrade from HTTP to WebSocket
still require a remap rule with the ``ws`` or ``wss`` scheme.
