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.
┌───────────────────────────────────────┬───────────┬────────────────────────────────────────────────────┐
├───────────────────────────────────────┼───────────┼────────────────────────────────────────────────────┤
├───────────────────────────────────────┼───────────┼────────────────────────────────────────────────────┤
└───────────────────────────────────────┴───────────┴────────────────────────────────────────────────────┘
│verify_server_policy │ Outbound │ One of the values DISABLED, │
│ │ │ PERMISSIVE, or ENFORCED. │
│ │ │ proxy.config.ssl.client.verify.server.policy. │
├───────────────────────────────────────┼───────────┼────────────────────────────────────────────────────┤
│verify_server_properties │ Outbound │ One of the values NONE, SIGNATURE, NAME, and │
│ │ │ ALL │
│ │ │ proxy.config.ssl.client.verify.server.properties. │
├───────────────────────────────────────┼───────────┼────────────────────────────────────────────────────┤
│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 │
│ │ │ STRICT is specified the client must present a │
│ │ │ proxy.config.ssl.client.certification_level. │
├───────────────────────────────────────┼───────────┼────────────────────────────────────────────────────┤
│ │ │ 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 │
│ │ │ path does not being with / , it must be relative │
│ │ │ verify_client_ca_certs can only be used with │
└───────────────────────────────────────┴───────────┴────────────────────────────────────────────────────┘
│host_sni_policy │ Inbound │ One of the values DISABLED, PERMISSIVE, or │
│ │ │ ENFORCED. │
│ │ │ proxy.config.http.host_sni_policy is used. This │
│ │ │ proxy.config.http.host_sni_policy records.config │
│ │ │ than the SNI in this sni.yaml file. This is done │
├───────────────────────────────────────┼───────────┼────────────────────────────────────────────────────┤
│ │ │ in proxy.config.ssl.TLSv1, │
│ │ │ proxy.config.ssl.TLSv1_1, │
│ │ │ proxy.config.ssl.TLSv1_2, and │
│ │ │ proxy.config.ssl.TLSv1_3. The potential values │
├───────────────────────────────────────┼───────────┼────────────────────────────────────────────────────┤
│ │ │ in proxy.config.ssl.client.cert.path. If not set │
│ │ │ proxy.config.ssl.client.cert.filename is used. │
├───────────────────────────────────────┼───────────┼────────────────────────────────────────────────────┤
│ │ │ in proxy.config.ssl.client.private_key.path. If │
│ │ │ proxy.config.ssl.client.private_key.filename is │
├───────────────────────────────────────┼───────────┼────────────────────────────────────────────────────┤
│ │ │ proxy.config.ssl.client.sni_policy is used. │
└───────────────────────────────────────┴───────────┴────────────────────────────────────────────────────┘
│ │ │ The valid values are on or off. │
├───────────────────────────────────────┼───────────┼────────────────────────────────────────────────────┤
│ │ │ proxy.config.http2.default_buffer_water_mark. │
├───────────────────────────────────────┼───────────┼────────────────────────────────────────────────────┤
│ │ │ proxy.config.http2.max_settings_frames_per_minute. │
├───────────────────────────────────────┼───────────┼────────────────────────────────────────────────────┤
│ │ │ proxy.config.http2.max_settings_frames_per_minute. │
├───────────────────────────────────────┼───────────┼────────────────────────────────────────────────────┤
│ │ │ proxy.config.http2.max_settings_frames_per_minute. │
├───────────────────────────────────────┼───────────┼────────────────────────────────────────────────────┤
│ │ │ proxy.config.http2.max_settings_frames_per_minute. │
├───────────────────────────────────────┼───────────┼────────────────────────────────────────────────────┤
│ │ │ Setting disable_h2 to true is the same as setting │
│ │ │ http2 to on. │
├───────────────────────────────────────┼───────────┼────────────────────────────────────────────────────┤
│ │ │ colon :. Match group number can be specified by │
│ │ │ $N where N should refer to a specified group in │
│ │ │ the FQDN, tunnel_route: $1.domain. │
├───────────────────────────────────────┼───────────┼────────────────────────────────────────────────────┤
│ │ │ colon :. │
└───────────────────────────────────────┴───────────┴────────────────────────────────────────────────────┘
│ │ │ colon :. │
├───────────────────────────────────────┼───────────┼────────────────────────────────────────────────────┤
│ │ │ works with partial_blind_route. │
└───────────────────────────────────────┴───────────┴────────────────────────────────────────────────────┘
Pre-warming TLS Tunnel
┌────────────────────────────────┬──────────────────────────────────┐
│Key │ Meaning │
├────────────────────────────────┼──────────────────────────────────┤
│tunnel_prewarm │ Override │
│ │ proxy.config.tunnel.prewarm in │
│ │ records.config. │
├────────────────────────────────┼──────────────────────────────────┤
│tunnel_prewarm_srv │ Enable SRV record lookup on │
│ │ pre-warming. Default is false. │
├────────────────────────────────┼──────────────────────────────────┤
│tunnel_prewarm_rate │ Rate of how many connections to │
│ │ pre-warm. Default is 1.0. │
├────────────────────────────────┼──────────────────────────────────┤
│tunnel_prewarm_min │ Minimum number of pre-warming │
│ │ queue size (per thread). Default │
│ │ is 0. │
├────────────────────────────────┼──────────────────────────────────┤
│tunnel_prewarm_max │ Maximum number of pre-warming │
│ │ queue size (per thread). Default │
│ │ is -1 (unlimited). │
├────────────────────────────────┼──────────────────────────────────┤
│tunnel_prewarm_connect_timeout │ Timeout for TCP/TLS handshake │
│ │ (in seconds). │
├────────────────────────────────┼──────────────────────────────────┤
│tunnel_prewarm_inactive_timeout │ Inactive timeout for connections │
│ │ in the pool (in seconds). │
└────────────────────────────────┴──────────────────────────────────┘
Client verification, via verify_client, corresponds to setting
proxy.config.ssl.client.certification_level for this connection as noted below.
NONE -- 0
Do not request a client certificate, ignore it if one is provided.
MODERATE - 1
Request a client certificate and do verification if one is provided. The connection
is denied if the verification of the client provided certificate fails.
STRICT - 2
Request a client certificate and require one to be provided and verified. If the
verification fails the failure is logged to diags.log and the connection is denied.
Upstream (server) verification, via verify_server_policy and verify_server_properties, is
similar to client verification except there is always an upstream certificate. This is
equivalent to setting proxy.config.ssl.client.verify.server.policy and
proxy.config.ssl.client.verify.server.properties for this connection.
verify_server_policy specifies how Traffic Server will enforce the server certificate
verification.
DISABLED
Do not verify the upstream server certificate.
PERMISSIVE
Do verification of the upstream certificate but do not enforce. If the verification
fails the failure is logged in diags.log but the connection is allowed.
ENFORCED
Do verification of the upstream certificate. If verification fails, the failure is
logged in diags.log and the connection is denied.
In addition verify_server_properties specifies what Traffic Server will check when
performing the verification.
NONE Do not check anything in the standard Traffic Server verification routine. Rely
entirely on the TS_SSL_VERIFY_SERVER_HOOK for evaluating the origin's certificate.
SIGNATURE
Check the signature of the origin certificate.
NAME Verify that the SNI is in the origin certificate.
ALL Verify both the signature and the SNI in the origin certificate.
If tunnel_route is specified, none of the certificate verification will be done because
the TLS negotiation will be tunneled to the upstream target, making those values
irrelevant for that configuration item. This option is explained in more detail in SNI
Routing.
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