'\" t
.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "SNI.YAML" "5" "Apr 16, 2024" "9.2" "Apache Traffic Server"
.SH NAME
sni.yaml \- Traffic Server sni rules configuration file
.SH DESCRIPTION
.sp
This file is used to configure aspects of TLS connection handling for both inbound and outbound
connections. With the exception of \fBhost_sni_policy\fP (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 (\fBfqdn\fP).
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 \fI\%remap.config\fP or plugins.
.sp
By default this is named \fI\%sni.yaml\fP\&. The filename can be changed by setting
\fI\%proxy.config.ssl.servername.filename\fP\&. This file is loaded on start up and by
\fI\%traffic_ctl config reload\fP if the file has been modified since process start.
.sp
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 \fB*.\fP followed by the common domain name. (\fB*.yahoo.com\fP for example).
.sp
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 \fI\%https://daniel.haxx.se/blog/2016/08/18/http2\-connection\-coalescing/\fP
for a more detailed description of HTTP/2 connection coalescing.
.TS
center;
|l|l|l|.
_
T{
Key
T}	T{
Direction
T}	T{
Meaning
T}
_
T{
fqdn
T}	T{
Both
T}	T{
Fully Qualified Domain Name. This item is used if the SNI value matches this.
T}
_
T{
ip_allow
T}	T{
Inbound
T}	T{
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.
T}
_
T{
verify_server_policy
T}	T{
Outbound
T}	T{
One of the values \fBDISABLED\fP, \fBPERMISSIVE\fP, or \fBENFORCED\fP\&.
.sp
By default this is \fI\%proxy.config.ssl.client.verify.server.policy\fP\&.
This controls how Traffic Server evaluated the origin certificate.
T}
_
T{
verify_server_properties
T}	T{
Outbound
T}	T{
One of the values \fBNONE\fP, \fBSIGNATURE\fP, \fBNAME\fP, and \fBALL\fP
.sp
By default this is \fI\%proxy.config.ssl.client.verify.server.properties\fP\&.
This controls what Traffic Server checks when evaluating the origin certificate.
T}
_
T{
verify_client
T}	T{
Outbound
T}	T{
One of the values \fBNONE\fP, \fBMODERATE\fP, or \fBSTRICT\fP\&.
If \fBNONE\fP is specified, Traffic Server requests no certificate.  If \fBMODERATE\fP 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 \fBSTRICT\fP is specified
the client must present a certificate during the TLS handshake.
.sp
By default this is \fI\%proxy.config.ssl.client.certification_level\fP\&.
T}
_
T{
verify_client_ca_certs
T}	T{
Both
T}	T{
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 \fBfile\fP and \fBdir\fP\&.  The value for \fBfile\fP must be a file path for a file
containing CA certs.  The value for \fBdir\fP must be a file path for an OpenSSL
X509 hashed directory containing CA certs.  If a given file path does not being
with \fB/\fP , it must be relative to the Traffic Server configuration directory.
\fBverify_client_ca_certs\fP can only be used with capbilities provided by
OpenSSL 1.0.2 or later.
T}
_
T{
host_sni_policy
T}	T{
Inbound
T}	T{
One of the values \fBDISABLED\fP, \fBPERMISSIVE\fP, or \fBENFORCED\fP\&.
.sp
If not specified, the value of \fI\%proxy.config.http.host_sni_policy\fP 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
\fI\%proxy.config.http.host_sni_policy\fP \fI\%records.config\fP documentation.
.sp
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 \fI\%sni.yaml\fP 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.
T}
_
T{
valid_tls_versions_in
T}	T{
Inbound
T}	T{
This specifies the list of TLS protocols that will be offered to user agents during
the TLS negotiation.  This replaces the global settings in
\fI\%proxy.config.ssl.TLSv1\fP, \fI\%proxy.config.ssl.TLSv1_1\fP,
\fI\%proxy.config.ssl.TLSv1_2\fP, and \fI\%proxy.config.ssl.TLSv1_3\fP\&. 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.
T}
_
T{
client_cert
T}	T{
Outbound
T}	T{
The file containing the client certificate to use for the outbound connection.
.sp
If this is relative, it is relative to the path in
\fI\%proxy.config.ssl.client.cert.path\fP\&. If not set
\fI\%proxy.config.ssl.client.cert.filename\fP is used.
T}
_
T{
client_key
T}	T{
Outbound
T}	T{
The file containing the client private key that corresponds to the certificate
for the outbound connection.
.sp
If this is relative, it is relative to the path in
\fI\%proxy.config.ssl.client.private_key.path\fP\&. If not set,
Traffic Server tries to use a private key in client_cert.  Otherwise,
\fI\%proxy.config.ssl.client.private_key.filename\fP is used.
T}
_
T{
client_sni_policy
T}	T{
Outbound
T}	T{
Policy of SNI on outbound connection.
.sp
If not specified, the value of \fI\%proxy.config.ssl.client.sni_policy\fP is used.
T}
_
T{
http2
T}	T{
Inbound
T}	T{
Indicates whether the H2 protocol should be added to or removed from the
protocol negotiation list.  The valid values are \fBon\fP or \fBoff\fP\&.
T}
_
T{
http2_buffer_water_mark
T}	T{
Inbound
T}	T{
Specifies the high water mark for all HTTP/2 frames on an outoging connection.
By default this is \fI\%proxy.config.http2.default_buffer_water_mark\fP\&.
NOTE: Connection coalescing may prevent this taking effect.
T}
_
T{
http2_max_settings_frames_per_minute
T}	T{
Inbound
T}	T{
Specifies how many SETTINGS frames Traffic Server receives per minute at maximum.
By default this is \fI\%proxy.config.http2.max_settings_frames_per_minute\fP\&.
NOTE: Connection coalescing may prevent this from taking effect.
T}
_
T{
http2_max_ping_frames_per_minute
T}	T{
Inbound
T}	T{
Specifies how many PING frames Traffic Server receives per minute at maximum.
By default this is \fI\%proxy.config.http2.max_ping_frames_per_minute\fP\&.
NOTE: Connection coalescing may prevent this from taking effect.
T}
_
T{
http2_max_priority_frames_per_minute
T}	T{
Inbound
T}	T{
Specifies how many PRIORITY frames Traffic Server receives per minute at maximum.
By default this is \fI\%proxy.config.http2.max_priority_frames_per_minute\fP\&.
NOTE: Connection coalescing may prevent this from taking effect.
T}
_
T{
http2_max_rst_stream_frames_per_minute
T}	T{
Inbound
T}	T{
Specifies how many RST_STREAM frames Traffic Server receives per minute at maximum.
By default this is \fI\%proxy.config.http2.max_rst_stream_frames_per_minute\fP\&.
NOTE: Connection coalescing may prevent this from taking effect.
T}
_
T{
disable_h2
T}	T{
Inbound
T}	T{
Deprecated for the more general h2 setting.  Setting disable_h2
to \fBtrue\fP is the same as setting http2 to \fBon\fP\&.
T}
_
T{
tunnel_route
T}	T{
Inbound
T}	T{
Destination as an FQDN and port, separated by a colon \fB:\fP\&.
Match group number can be specified by \fB$N\fP where N should refer to a specified group
in the FQDN, \fBtunnel_route: $1.domain\fP\&.
.sp
This will forward all traffic to the specified destination without first terminating
the incoming TLS connection.
T}
_
T{
forward_route
T}	T{
Inbound
T}	T{
Destination as an FQDN and port, separated by a colon \fB:\fP\&.
.sp
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.
T}
_
T{
partial_blind_route
T}	T{
Inbound
T}	T{
Destination as an FQDN and port, separated by a colon \fB:\fP\&.
.sp
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.
T}
_
T{
tunnel_alpn
T}	T{
Inbound
T}	T{
List of ALPN Protocol Ids for Partial Blind Tunnel.
.sp
ATS negotiates application protocol with the client on behalf of the origin server.
This only works with \fBpartial_blind_route\fP\&.
T}
_
.TE
.SS Pre\-warming TLS Tunnel
.TS
center;
|l|l|.
_
T{
Key
T}	T{
Meaning
T}
_
T{
tunnel_prewarm
T}	T{
Override \fI\%proxy.config.tunnel.prewarm\fP in records.config.
T}
_
T{
tunnel_prewarm_srv
T}	T{
Enable SRV record lookup on pre\-warming. Default is \fBfalse\fP\&.
T}
_
T{
tunnel_prewarm_rate
T}	T{
Rate of how many connections to pre\-warm. Default is \fB1.0\fP\&.
T}
_
T{
tunnel_prewarm_min
T}	T{
Minimum number of pre\-warming queue size (per thread). Default is \fB0\fP\&.
T}
_
T{
tunnel_prewarm_max
T}	T{
Maximum number of pre\-warming queue size (per thread). Default is \fB\-1\fP (unlimited).
T}
_
T{
tunnel_prewarm_connect_timeout
T}	T{
Timeout for TCP/TLS handshake (in seconds).
T}
_
T{
tunnel_prewarm_inactive_timeout
T}	T{
Inactive timeout for connections in the pool (in seconds).
T}
_
.TE
.sp
Client verification, via \fBverify_client\fP, corresponds to setting
\fI\%proxy.config.ssl.client.certification_level\fP for this connection as noted below.
.INDENT 0.0
.TP
.B \fBNONE\fP \-\- \fB0\fP
Do not request a client certificate, ignore it if one is provided.
.TP
.B \fBMODERATE\fP \- \fB1\fP
Request a client certificate and do verification if one is provided. The connection is denied if the verification of the client provided certificate fails.
.TP
.B \fBSTRICT\fP \- \fB2\fP
Request a client certificate and require one to be provided and verified.
If the verification fails the failure is logged to \fI\%diags.log\fP and the connection is
denied.
.UNINDENT
.sp
Upstream (server) verification, via \fBverify_server_policy\fP and \fBverify_server_properties\fP, is similar to client verification
except there is always an upstream certificate. This is equivalent to setting
\fI\%proxy.config.ssl.client.verify.server.policy\fP and \fI\%proxy.config.ssl.client.verify.server.properties\fP for this connection.
.sp
\fBverify_server_policy\fP specifies how Traffic Server will enforce the server certificate verification.
.INDENT 0.0
.TP
.B \fBDISABLED\fP
Do not verify the upstream server certificate.
.TP
.B \fBPERMISSIVE\fP
Do verification of the upstream certificate but do not enforce. If the verification fails the
failure is logged in \fI\%diags.log\fP but the connection is allowed.
.TP
.B \fBENFORCED\fP
Do verification of the upstream certificate. If verification fails, the failure is
logged in \fI\%diags.log\fP and the connection is denied.
.UNINDENT
.sp
In addition \fBverify_server_properties\fP specifies what Traffic Server will check when performing the verification.
.INDENT 0.0
.TP
.B \fBNONE\fP
Do not check anything in the standard Traffic Server verification routine.  Rely entirely on the \fBTS_SSL_VERIFY_SERVER_HOOK\fP for evaluating the origin\(aqs certificate.
.TP
.B \fBSIGNATURE\fP
Check the signature of the origin certificate.
.TP
.B \fBNAME\fP
Verify that the SNI is in the origin certificate.
.TP
.B \fBALL\fP
Verify both the signature and the SNI in the origin certificate.
.UNINDENT
.sp
If \fBtunnel_route\fP 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 \fI\%SNI Routing\fP\&.
.SH EXAMPLES
.sp
Disable HTTP/2 for \fBno\-http2.example.com\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
sni:
\- fqdn: no\-http2.example.com
  http2: off
.EE
.UNINDENT
.UNINDENT
.sp
Require client certificate verification for \fBfoo.com\fP and any server name ending with \fB\&.yahoo.com\fP\&. 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.
.sp
For \fBfoo.com\fP, 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.
.sp
Traffic Server will allow a client certificate to be provided for \fBexample.com\fP and if it is, Traffic Server will require the
certificate to be valid.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
sni:
\- fqdn: example.com
  verify_client: MODERATE
\- fqdn: \(aqfoo.com\(aq
  verify_client: STRICT
  host_sni_policy: PERMISSIVE
\- fqdn: \(aq*.yahoo.com\(aq
  verify_client: STRICT
.EE
.UNINDENT
.UNINDENT
.sp
Disable outbound server certificate verification for \fBtrusted.example.com\fP and require a valid
client certificate.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
sni:
\- fqdn: trusted.example.com
  verify_server_policy: DISABLED
  verify_client: STRICT
.EE
.UNINDENT
.UNINDENT
.sp
Use FQDN captured group to match in \fBtunnel_route\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
sni:
\- fqdn: \(aq*.foo.com\(aq
  tunnel_route: \(aq$1.myfoo\(aq
\- fqdn: \(aq*.bar.*.com\(aq
  tunnel_route: \(aq$2.some.$1.yahoo\(aq
.EE
.UNINDENT
.UNINDENT
.sp
FQDN \fBsome.foo.com\fP will match and the captured string will be replaced in the \fBtunnel_route\fP which will end up being
\fBsome.myfoo\fP\&.
Second part is using multiple groups, having \fBbob.bar.example.com\fP as FQDN, \fBtunnel_route\fP will end up being
\fBbar.some.bob.yahoo\fP\&.
.SH SEE ALSO
.sp
\fI\%SNI Routing\fP
.SH COPYRIGHT
2024, dev@trafficserver.apache.org
.\" Generated by docutils manpage writer.
.