Provided by: trafficserver_9.2.3+ds-1+deb12u1build4_amd64 
NAME
sni.yaml - Traffic Server sni rules configuration file
DESCRIPTION
This file is used to configure aspects of TLS connection handling for both inbound and outbound
connections. With the exception of host_sni_policy (see the description below), the configuration is
driven by the SNI values provided by the inbound connection. The file consists of a set of configuration
items, each identified by an SNI value (fqdn). When an inbound TLS connection is made, the SNI value
from the TLS negotiation is matched against the items specified by this file and if there is a match, the
values specified in that item override the defaults. This is done during the inbound connection
processing; some outbound properties can be overridden again later, such as via remap.config or plugins.
By default this is named sni.yaml. The filename can be changed by setting
proxy.config.ssl.servername.filename. This file is loaded on start up and by traffic_ctl config reload if
the file has been modified since process start.
The configuration file is YAML-based. After parsing the configuration, a list of tables will be the
result. Each table is a set of key / value pairs that create a configuration item. This configuration
file accepts wildcard entries. To apply an SNI based setting on all the server names with a common upper
level domain name, the user needs to enter the fqdn in the configuration with a *. followed by the common
domain name. (*.yahoo.com for example).
For some settings, there is no guarantee that they will be applied to a connection under certain
conditions. An established TLS connection may be reused for another server name if it’s used for HTTP/2.
This also means that settings for server name A may affects requests for server name B as well. See
https://daniel.haxx.se/blog/2016/08/18/http2-connection-coalescing/ for a more detailed description of
HTTP/2 connection coalescing.
───────────────────────────────────────────────────────────────────────────────────────────────────────────
Key Direction Meaning
───────────────────────────────────────────────────────────────────────────────────────────────────────────
fqdn Both Fully Qualified Domain Name.
This item is used if the SNI
value matches this.
───────────────────────────────────────────────────────────────────────────────────────────────────────────
ip_allow Inbound Specify a list of client IP
address, subnets, or ranges
what are allowed to complete
the connection. This list is
comma separated. IPv4 and
IPv6 addresses can be
specified. Here is an
example list:
192.168.1.0/24,192.168.10.1-4.
This would allow connections
from clients in the
19.168.1.0 network or in the
range from 192.168.10.1 to
192.168.1.4.
───────────────────────────────────────────────────────────────────────────────────────────────────────────
verify_server_policy Outbound One of the values DISABLED,
PERMISSIVE, or ENFORCED.
By default this is
proxy.config.ssl.client.verify.server.policy.
This controls how Traffic
Server evaluated the origin
certificate.
───────────────────────────────────────────────────────────────────────────────────────────────────────────
verify_server_properties Outbound One of the values NONE, SIGNATURE, NAME, and
ALL
By default this is
proxy.config.ssl.client.verify.server.properties.
This controls what Traffic Server checks when
evaluating the origin certificate.
───────────────────────────────────────────────────────────────────────────────────────────────────────────
verify_client Outbound One of the values NONE, MODERATE, or STRICT. If
NONE is specified, Traffic Server requests no
certificate. If MODERATE is specified Traffic
Server will verify a certificate that is
presented by the client, but it will not fail the
TLS handshake if no certificate is presented. If
STRICT is specified the client must present a
certificate during the TLS handshake.
By default this is
proxy.config.ssl.client.certification_level.
───────────────────────────────────────────────────────────────────────────────────────────────────────────
verify_client_ca_certs Both Specifies an alternate set of certificate
authority certs to use to verify the client cert.
The value must be either a file path, or a nested
set of key / value pairs. If the value is a file
path, it must specify a file containing the CA
certs. Otherwise, there should be up to two
nested pairs. The possible keys are file and
dir. The value for file must be a file path for
a file containing CA certs. The value for dir
must be a file path for an OpenSSL X509 hashed
directory containing CA certs. If a given file
path does not being with / , it must be relative
to the Traffic Server configuration directory.
verify_client_ca_certs can only be used with
capbilities provided by OpenSSL 1.0.2 or later.
───────────────────────────────────────────────────────────────────────────────────────────────────────────
host_sni_policy Inbound One of the values DISABLED, PERMISSIVE, or
ENFORCED.
If not specified, the value of
proxy.config.http.host_sni_policy is used. This
controls how policy impacting mismatches between
host header and SNI values are dealt with. For
details about hos this configuration behaves, see
the corresponding
proxy.config.http.host_sni_policy records.config
documentation.
Note that this particular configuration will be
inspected at the time the HTTP Host header field
is processed. Further, this policy check will be
keyed off of the Host header field value rather
than the SNI in this sni.yaml file. This is done
because the Host header field is ultimately the
resource that will be retrieved from the origin
and the administrator will intend to guard this
resource rather than the SNI, which a malicious
user may alter to some other server value whose
policies are more lenient than the host he is
trying to access.
───────────────────────────────────────────────────────────────────────────────────────────────────────────
valid_tls_versions_in Inbound This specifies the list of TLS protocols that
will be offered to user agents during the TLS
negotiation. This replaces the global settings
in proxy.config.ssl.TLSv1,
proxy.config.ssl.TLSv1_1,
proxy.config.ssl.TLSv1_2, and
proxy.config.ssl.TLSv1_3. The potential values
are TLSv1, TLSv1_1, TLSv1_2, and TLSv1_3. You
must list all protocols that Traffic Server
should offer to the client when using this key.
This key is only valid for OpenSSL 1.1.0 and
later and BoringSSL. Older versions of OpenSSL do
not provide a hook early enough to update the SSL
object. It is a syntax error for Traffic Server
built against earlier versions.
───────────────────────────────────────────────────────────────────────────────────────────────────────────
client_cert Outbound The file containing the client certificate to use
for the outbound connection.
If this is relative, it is relative to the path
in proxy.config.ssl.client.cert.path. If not set
proxy.config.ssl.client.cert.filename is used.
───────────────────────────────────────────────────────────────────────────────────────────────────────────
client_key Outbound The file containing the client private key that
corresponds to the certificate for the outbound
connection.
If this is relative, it is relative to the path
in proxy.config.ssl.client.private_key.path. If
not set, Traffic Server tries to use a private
key in client_cert. Otherwise,
proxy.config.ssl.client.private_key.filename is
used.
───────────────────────────────────────────────────────────────────────────────────────────────────────────
client_sni_policy Outbound Policy of SNI on outbound connection.
If not specified, the value of
proxy.config.ssl.client.sni_policy is used.
───────────────────────────────────────────────────────────────────────────────────────────────────────────
http2 Inbound Indicates whether the H2 protocol should be added
to or removed from the protocol negotiation list.
The valid values are on or off.
───────────────────────────────────────────────────────────────────────────────────────────────────────────
http2_buffer_water_mark Inbound Specifies the high water mark for all HTTP/2
frames on an outoging connection. By default
this is
proxy.config.http2.default_buffer_water_mark.
NOTE: Connection coalescing may prevent this
taking effect.
───────────────────────────────────────────────────────────────────────────────────────────────────────────
http2_max_settings_frames_per_minute Inbound Specifies how many SETTINGS frames Traffic Server
receives per minute at maximum. By default this
is
proxy.config.http2.max_settings_frames_per_minute.
NOTE: Connection coalescing may prevent this from
taking effect.
───────────────────────────────────────────────────────────────────────────────────────────────────────────
http2_max_ping_frames_per_minute Inbound Specifies how many PING frames Traffic Server
receives per minute at maximum. By default this
is
proxy.config.http2.max_settings_frames_per_minute.
NOTE: Connection coalescing may prevent this from
taking effect.
───────────────────────────────────────────────────────────────────────────────────────────────────────────
http2_max_priority_frames_per_minute Inbound Specifies how many PRIORITY frames Traffic Server
receives per minute at maximum. By default this
is
proxy.config.http2.max_settings_frames_per_minute.
NOTE: Connection coalescing may prevent this from
taking effect.
───────────────────────────────────────────────────────────────────────────────────────────────────────────
http2_max_rst_stream_frames_per_minute Inbound Specifies how many RST_STREAM frames Traffic
Server receives per minute at maximum. By default
this is
proxy.config.http2.max_settings_frames_per_minute.
NOTE: Connection coalescing may prevent this from
taking effect.
───────────────────────────────────────────────────────────────────────────────────────────────────────────
disable_h2 Inbound Deprecated for the more general h2 setting.
Setting disable_h2 to true is the same as setting
http2 to on.
───────────────────────────────────────────────────────────────────────────────────────────────────────────
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.
This will forward all traffic to the specified
destination without first terminating the incoming
TLS connection.
───────────────────────────────────────────────────────────────────────────────────────────────────────────
forward_route Inbound Destination as an FQDN and port, separated by a
colon :.
This is similar to tunnel_route, but it terminates
the TLS connection and forwards the decrypted
traffic. Traffic Server will not interpret the
decrypted data, so the contents do not need to be
HTTP.
───────────────────────────────────────────────────────────────────────────────────────────────────────────
partial_blind_route Inbound Destination as an FQDN and port, separated by a
colon :.
This is similar to forward_route in that Traffic
Server terminates the incoming TLS connection. In
addition partial_blind_route creates a new TLS
connection to the specified origin. It does not
interpret the decrypted data before passing it to
the origin TLS connection, so the contents do not
need to be HTTP.
───────────────────────────────────────────────────────────────────────────────────────────────────────────
tunnel_alpn Inbound List of ALPN Protocol Ids for Partial Blind
Tunnel.
ATS negotiates application protocol with the
client on behalf of the origin server. This only
works with partial_blind_route.
┌────────────────────────────────────────┬───────────┬────────────────────────────────────────────────────┐
│ │ │ │
--
EXAMPLES
Disable HTTP/2 for no-http2.example.com.
sni:
- fqdn: no-http2.example.com
http2: off
Require client certificate verification for foo.com and any server name ending with .yahoo.com.
Therefore, client request for a server name ending with yahoo.com (e.g., def.yahoo.com, abc.yahoo.com
etc.) will cause Traffic Server require and verify the client certificate.
For foo.com, if the user agent sets the host header to foo.com but the SNI to some other value, Traffic
Server will warn about the mismatch but continue to process the request. Mismatches for the other
domains will cause Traffic Server to warn and return 403.
Traffic Server will allow a client certificate to be provided for example.com and if it is, Traffic
Server will require the certificate to be valid.
sni:
- fqdn: example.com
verify_client: MODERATE
- fqdn: 'foo.com'
verify_client: STRICT
host_sni_policy: PERMISSIVE
- fqdn: '*.yahoo.com'
verify_client: STRICT
Disable outbound server certificate verification for trusted.example.com and require a valid client
certificate.
sni:
- fqdn: trusted.example.com
verify_server_policy: DISABLED
verify_client: STRICT
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.
SEE ALSO
SNI Routing
COPYRIGHT
2024, dev@trafficserver.apache.org
9.2 Apr 01, 2024 SNI.YAML(5)