records.yaml — Apache Traffic Server documentation

records.yaml — Apache Traffic Server documentation
Administrator’s Guide
Configuration Files
records.yaml
View page source
records.yaml
Important
From ATS 10 we have moved from the old
records.config
format style in flavour of the new
YAML style. Please check
Converting records.config to records.yaml
for information about migrating from the
old style to the new YAML base config.
The
records.yaml
file (by default, located in
/usr/local/etc/trafficserver/
) is a YAML base configuration file used by
the Traffic Server software. After you modify
records.yaml
, run the command
traffic_ctl
config
reload
to apply the changes.
Note
The configuration directory, containing the
SYSCONFDIR
value specified at build time
relative to the installation prefix, contains Traffic Server configuration files.
The
$TS_ROOT
environment variable can be used alter the installation prefix at run time.
The directory must allow read/write access for configuration reloads.
YAML structure
All fields are located inside the
records`
root node. ATS supports reading multiple documents from
the same YAML stream, subsequent documents overrides earlier fields. If there is any error reading a
particular node the default value(s) will be used.
records
diags
debug
enabled
tags
http|dns
# ...
# rest of the fields.
# ...
Important
Internally, ATS uses record names as
Configuration Variables
Data Type
There is no need to manually set the record type, it can be done if desired.
The types accepted are:
Type
Description
float
Floating point, expressed as a decimal number without units or
exponents.
int
Integers, expressed with or without unit prefixes (as described
below).
str
String of characters up to the first newline. No quoting necessary.
Non core records
Records that aren’t part of the core ATS needs to set the field type, this for now
is the only way to know the field type.
We expect non core records to set the type (!!int, !!float, etc).
records
plugin_x
my_field_1
!!int
'1'
my_field_2
!!float
'1.2'
my_field_3
'my
string'
Values
The
field_value
must conform to the variable’s type. For
str
, this
is simply any character data until the first newline.
For integer (
int
) fields, values are expressed as any normal integer,
e.g.
32768
. They can also be expressed using more human readable values
using standard unit prefixes, e.g.
32K
. The following prefixes are
supported for all
int
type configurations:
Prefix
Description
Equivalent in Bytes
Kilobytes
1,024 bytes
Megabytes
1,048,576 bytes (1024
Gigabytes
1,073,741,824 bytes (1024
Terabytes
1,099,511,627,776 bytes (1024
Floating point variables (
float
) must be expressed as a regular decimal
number. Unit prefixes are not supported, nor are alternate notations (scientific,
exponent, etc.).
Additional Attributes
Deprecated
A variable marked as
Deprecated
is still functional but should be avoided
as it may be removed in a future release without warning.
Reloadable
A variable marked as
Reloadable
can be updated via the command:
traffic_ctl
config
reload
This updates configuration parameters without restarting Traffic Server or interrupting
the processing of requests.
Overridable
A variable marked as
Overridable
can be changed on a per-remap basis using
plugins (like the
Configuration Remap Plugin
), affecting operations within
the current transaction only. Remap config files still uses the legacy
records.config
style.
Examples
In the following example, the field
proxy_name
is a
str
datatype with the
value
my_server
. This means that the name of the Traffic Server proxy is
my_server
records
proxy_name
my_server
If the server name should be
that_server
the line would be:
records
proxy_name
that_server
In the following example, the field is a yes/no flag. A value of
(zero)
disables the option; a value of
enables the option.
records
arm
enabled
In the following example, the field sets the time to wait for a
DNS response to 10 seconds.
records
hostdb
lookup_timeout
10
In the following example the field sets the field with a
float
value.
records
exec_thread
autoconfig
scale
1.0
The last examples configures a 64GB RAM cache, using a human readable
prefix.
records
cache
ram_cache
size
64G
Environment Overrides
Every
records.yaml
configuration variable can be overridden
by a corresponding environment variable. This can be useful in
situations where you need a static
records.yaml
but still
want to tweak one or two settings. The override variable is formed
by converting the
records.yaml
variable name to upper
case, and replacing any dot separators with an underscore.
Overriding a variable from the environment is permanent and will
not be affected by future configuration changes made in
records.yaml
or applied with
traffic_ctl
For example, we could override the
proxy.config.product_company
variable
like this:
$ PROXY_CONFIG_PRODUCT_COMPANY=example traffic_server &
$ traffic_ctl config get proxy.config.product_company
Configuration Variables
The following list describes the configuration variables available in
the
records.yaml
file.
System Variables
proxy.config.product_company
Scope
CONFIG
Type
STRING
Default
Apache Software Foundation
yaml:
records
product_company
Apache Software Foundation
The name of the organization developing Traffic Server.
proxy.config.product_vendor
Scope
CONFIG
Type
STRING
Default
Apache
yaml:
records
product_vendor
Apache
The name of the vendor providing Traffic Server.
proxy.config.product_name
Scope
CONFIG
Type
STRING
Default
|TS|
yaml:
records
product_name
'|TS|'
The name of the product.
proxy.config.proxy_name
Scope
CONFIG
Type
STRING
Default
build_machine
Reloadable
Yes
yaml:
records
proxy_name
build_machine
The name of the Traffic Server node.
proxy.config.bin_path
Scope
CONFIG
Type
STRING
Default
bin
yaml:
records
bin_path
bin
The location of the Traffic Server
bin
directory.
proxy.config.memory.max_usage
Scope
CONFIG
Type
INT
Default
Units
bytes
yaml:
records
memory
max_usage
Throttle incoming connections if resident memory usage exceeds this value.
Setting the option to 0 disables the feature.
proxy.config.syslog_facility
Scope
CONFIG
Type
STRING
Default
LOG_DAEMON
yaml:
records
syslog_facility
LOG_DAEMON
The facility used to record system log files. Refer to
Understanding Traffic Server Logs
for more in-depth discussion
of the contents and interpretations of log files.
proxy.config.output.logfile.name
Scope
CONFIG
Type
STRING
Default
traffic.out
yaml:
records
output
logfile
name
traffic.out
This is used for log rolling configuration so Traffic Server knows the path of the
output file that should be rolled. This configuration takes the name of the
file receiving
traffic_server
process output that is set via the
--bind_stdout
and
--bind_stderr
command-line options
proxy.config.output.logfile.name
is used only to identify the name of
the output file for log rolling purposes and does not override the values
set via
--bind_stdout
and
--bind_stderr
If a filename is passed to this option, then it will be interpreted relative
to
proxy.config.log.logfile_dir
. If a different location is desired,
then pass an absolute path to this configuration.
proxy.config.output.logfile_perm
Scope
CONFIG
Type
STRING
Default
rw-r–r–
yaml:
records
output
logfile_perm
rw-r--r--
The log file permissions for the file receiving Traffic Server output, the path of
which is configured via the
--bind_stdout
and
--bind_stderr
command-line options
. The standard UNIX file
permissions are used (owner, group, other). Permissible values are:
Value
Description
No permissions.
Read permission.
Write permission.
Execute permission.
Permissions are subject to the umask settings for the Traffic Server process. This
means that a umask setting of
002
will not allow write permission for
others, even if specified in the configuration file. Permissions for
existing log files are not changed when the configuration is modified.
proxy.config.output.logfile.rolling_enabled
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
yaml:
records
output
logfile
rolling_enabled
Specifies how the output log is rolled. You can specify the following values:
Value
Description
Disables output log rolling.
Enables output log rolling at specific intervals (specified with the
proxy.config.output.logfile.rolling_interval_sec
variable).
The clock starts ticking on Traffic Server boot.
Enables output log rolling when the output log reaches a specific size
(specified with
proxy.config.output.logfile.rolling_size_mb
).
Enables output log rolling at specific intervals or when the output log
reaches a specific size (whichever occurs first).
proxy.config.output.logfile.rolling_interval_sec
Scope
CONFIG
Type
INT
Default
3600
Units
seconds
Reloadable
Yes
yaml:
records
output
logfile
rolling_interval_sec
3600
Specifies how often the output log is rolled, in seconds. The timer starts on Traffic Server startup.
proxy.config.output.logfile.rolling_size_mb
Scope
CONFIG
Type
INT
Default
100
Units
megabytes
Reloadable
Yes
yaml:
records
output
logfile
rolling_size_mb
100
Specifies at what size to roll the output log at.
proxy.config.output.logfile.rolling_min_count
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
yaml:
records
output
logfile
rolling_min_count
Specifies the minimum count of rolled output logs to keep. This value will be used to decide the
order of auto-deletion (if enabled). A default value of 0 means auto-deletion will try to keep
output logs as much as possible. See
Log Rotation and Retention
for guidance.
Thread Variables
proxy.config.exec_thread.autoconfig.enabled
Scope
CONFIG
Type
INT
Default
yaml:
records
exec_thread
autoconfig
enabled
When enabled (the default,
), Traffic Server scales threads according to the
available CPU cores. See the config option below.
proxy.config.exec_thread.autoconfig.scale
Scope
CONFIG
Type
FLOAT
Default
1.0
yaml:
records
exec_thread
autoconfig
scale
1.0
Factor by which Traffic Server scales the number of threads. The multiplier is usually
the number of available CPU cores. By default this is scaling factor is
1.0
proxy.config.exec_thread.limit
Scope
CONFIG
Type
INT
Default
yaml:
records
exec_thread
limit
The number of threads Traffic Server will create if
proxy.config.exec_thread.autoconfig.enabled
is set to
, otherwise this option is ignored.
proxy.config.exec_thread.listen
Scope
CONFIG
Type
INT
Default
yaml:
records
exec_thread
listen
If enabled (
) all the exec_threads listen for incoming connections.
proxy.config.accept_threads
should be disabled to enable this variable. If a unix domain path is
configured as a server port and this setting is enabled, each exec thread
will create its own domain socket with a
-id>
suffix added to the
end of the path.
proxy.config.exec_thread.loop_time_update_probability
Scope
CONFIG
Type
INT
Default
10
Reloadable
Yes
yaml:
records
exec_thread
loop_time_update_probability
10
This dynamically loadable setting controls the rate that exec thread loop timestamps are
updated after processing an event given as a percentage from 0 to 100. 0
would mean the timestamp is only updated once per event loop, 100 percent
means the timestamp is updated after any potential operation that could take
time (i.e. processing an event or waiting on IO). The timestamp is used for
queuing events and comparing timestamps for processing. Updating more often
might improve event timer accuracy and event loop metrics, but increases the
number of times that the current time is obtained from the OS. See also
proxy.config.system_clock
proxy.config.accept_threads
Scope
CONFIG
Type
INT
Default
yaml:
records
accept_threads
The number of accept threads. If disabled (
), then accepts will be done
in each of the worker threads.
accept_threads
exec_thread.listen
Effect
All worker threads accept new connections and share listen fd.
New connections are accepted on a dedicated accept thread and distributed to worker threads in round robin fashion.
All worker threads listen on the same port using SO_REUSEPORT. Each thread has its own listen fd and new connections are accepted on all the threads.
By default,
proxy.config.accept_threads
is set to 1 and
proxy.config.exec_thread.listen
is set to 0.
proxy.config.thread.default.stacksize
Scope
CONFIG
Type
INT
Default
1048576
yaml:
records
thread
default
stacksize
1048576
Default thread stack size, in bytes, for all threads (default is 1 MB).
proxy.config.exec_thread.affinity
Scope
CONFIG
Type
INT
Default
yaml:
records
exec_thread
affinity
Bind threads to specific processing units.
Value
Effect
Assign threads to machine.
Assign threads to NUMA nodes [default].
Assign threads to sockets.
Assign threads to cores.
Assign threads to processing units.
Note
This option only has an affect when Traffic Server has been compiled with
--enable-hwloc
proxy.config.exec_thread.watchdog.timeout_ms
Scope
CONFIG
Type
INT
Default
Units
milliseconds
yaml:
records
exec_thread
watchdog
timeout_ms
Set the timeout for the exec thread watchdog in milliseconds. If an exec thread
does not heartbeat within this time period, the watchdog will log a warning message.
If this value is zero, the watchdog is disabled.
The default of this watchdot timeout is set to 0 (disabled) for ATS 10.2 for
compatibility. We recommend that administrators set a reasonable
value, such as 1000, for production configurations, in order to
catch hung plugins, or server overload scenarios.
proxy.config.system.file_max_pct
Scope
CONFIG
Type
FLOAT
Default
0.9
yaml:
records
system
file_max_pct
0.9
Set the maximum number of file handles for the traffic_server process as a percentage of the fs.file-max proc value in Linux. The default is 90%.
proxy.config.crash_log_helper
Scope
CONFIG
Type
STRING
Default
traffic_crashlog
yaml:
records
crash_log_helper
traffic_crashlog
This option directs
traffic_server
to spawn a crash
log helper at startup. The value should be the path to an
executable program. If the path is not absolute, it is located
relative to configured
bin
directory. Any user-provided
program specified here must behave in a fashion compatible with
traffic_crashlog
. Specifically, it must implement
the
traffic_crashlog
--wait
behavior.
This setting not reloadable because the helper must be spawned
before
traffic_server
drops privilege. If this variable
is set to
NULL
, no helper will be spawned.
proxy.config.restart.stop_listening
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
yaml:
records
restart
stop_listening
This option specifies whether Traffic Server should close listening sockets while shutting down gracefully.
Value
Description
Listening sockets will be kept open.
Listening sockets will be closed when Traffic Server starts shutting down.
proxy.config.stop.shutdown_timeout
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
yaml:
records
stop
shutdown_timeout
The shutdown timeout(in seconds) to apply when stopping Traffic
Server, in which ATS can initiate graceful shutdowns. In order
to effect graceful shutdown, the value specified should be greater
than 0. Value of 0 will not effect an abrupt shutdown. Abrupt
shutdowns can be achieved with out specifying –drain;
(traffic_ctl server stop /restart). Stopping Traffic Server here means sending
traffic_server
a signal either by
bin/trafficserver stop
or
kill
proxy.config.thread.max_heartbeat_mseconds
Scope
CONFIG
Type
INT
Default
60
Units
milliseconds
yaml:
records
thread
max_heartbeat_mseconds
60
Set the maximum heartbeat in milliseconds for threads, ranges from 0 to 1000.
This controls the maximum amount of time the event loop will wait for I/O activity.
On a system that is not busy, this option can be set to a higher value to decrease
the spin around overhead. If experiencing unexpected delays, setting a lower value
should improve the situation. Note that this setting should only be used by expert
system tuners, and will not be beneficial with random fiddling.
Network
proxy.config.net.additional_accepts
Scope
CONFIG
Type
INT
Default
-1
Reloadable
Yes
yaml:
records
net
additional_accepts
-1
This config addresses an issue that can sometimes happen if threads are caught in
a net accept while loop, become busy exclusviely accepting connections, and are prevented
from doing other work. This can cause an increase in latency and average event
loop time. When set to 0, a thread accepts only 1 connection per event loop.
When set to any other positive integer x, a thread will accept up to x+1 connections
per event loop. When set to -1 (default), a thread will accept connections as long
as there are connections waiting in its listening queue.is equivalent to “accept all”,
and setting to 0 is equivalent to “accept one”.
proxy.config.net.connections_throttle
Scope
CONFIG
Type
INT
Default
30000
yaml:
records
net
connections_throttle
30000
The total number of client and origin server connections that the server
can handle simultaneously. This is in fact the max number of file
descriptors that the
traffic_server
process can have open at any
given time. Roughly 10% of these connections are reserved for origin server
connections, i.e. from the default, only ~27,000 client connections can be
handled. This should be tuned according to your memory size, and expected
work load. If this is set to 0, the throttling logic is disabled.
proxy.config.net.max_connections_in
Scope
CONFIG
Type
INT
Default
30000
yaml:
records
net
max_connections_in
30000
The total number of client requests that Traffic Server can handle simultaneously.
This should be tuned according to your memory size, and expected work load
(network, cpu etc). This limit includes both idle (keep alive) connections
and active requests that Traffic Server can handle at any given instant. The delta
between
proxy.config.net.max_connections_in
and
proxy.config.net.max_requests_in
is the amount of maximum idle (keepalive) connections Traffic Server will maintain.
If this is set to 0, the throttling logic is disabled.
proxy.config.net.per_client.max_connections_in
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
yaml:
records
net
per_client
max_connections_in
The total number of concurrent client connections that Traffic Server will accept from
a given client IP address. Any received connections from a client beyond this
limit will be immediately closed. Once the number of concurrent client
connections drops below this configured value, Traffic Server will begin accepting new
connections from that IP while the number of concurrent connections remains
below this limit. A value of 0 disables the per client concurrent connection
limit.
See
proxy.config.http.per_client.connection.exempt_list
for a way to
allow (not count) certain client IP addresses when applying this limit.
proxy.config.http.per_client.connection.exempt_list
Scope
CONFIG
Type
STRING
Default
NULL
Reloadable
Yes
yaml:
records
http
per_client
connection
exempt_list
null
A comma-separated list of IP addresses or CIDR ranges to exempt when
counting incoming client connections for per client connection
throttling. Incoming addresses in this specified set will not count
against
proxy.config.net.per_client.max_connections_in
and
thus will not be blocked by that configuration. This may be useful,
for example, to allow any number of incoming connections from within
an organization’s network without blocking them due to the per client
connection max feature.
This configuration is reloadable via
traffic_ctl config reload
This configuration takes a comma-separated list of IP addresses, CIDR
networks, or ranges separated by a dash.
Example
Effect
10.0.2.123
Exempt a single IP Address.
10.0.3.1-10.0.3.254
Exempt a range of IP address.
10.0.4.0/24
Exempt a range of IP address specified by CIDR notation.
10.0.2.123,172.16.0.0/20
Exempt multiple addresses/ranges.
Here is an example configuration value:
10.0.2.123
172.16.0.0
20
192.168.1.0
24
proxy.config.http.per_client.connection.alert_delay
Scope
CONFIG
Type
INT
Default
60
Units
seconds
Reloadable
Yes
yaml:
records
http
per_client
connection
alert_delay
60
Throttle alerts per client IP address to be no more often than this many
seconds. Summary data is provided per alert to allow log scrubbing to
generate accurate data.
proxy.config.net.max_requests_in
Scope
CONFIG
Type
INT
Default
yaml:
records
net
max_requests_in
The total number of concurrent requests or active client connections
that the Traffic Server can handle simultaneously. This should be tuned according
to your memory size, and expected work load (network, cpu etc). When
set to 0, active request tracking is disabled and max requests has no
separate limit and the total connections follow
proxy.config.net.connections_throttle
proxy.config.net.default_inactivity_timeout
Scope
CONFIG
Type
INT
Default
86400
Reloadable
Yes
Overridable
Yes
yaml:
records
net
default_inactivity_timeout
86400
The connection inactivity timeout (in seconds) to apply when
Traffic Server detects that no inactivity timeout has been applied
by the HTTP state machine. When this timeout is applied, the
proxy.process.net.default_inactivity_timeout_applied
metric
is incremented.
Note that this configuration is overridable. While most overridable
configurations conceptually apply to specific transactions,
default_inactivity_timeout
is a connection level concept. This is not
necessarily a problem, but it does mean that care must be taken when
applying the override to consider that all transactions in the connection
which has this timeout overridden will be impacted by the override. For
instance, if the default inactivity timeout is being overridden via a
Configuration Remap Plugin
rule in
remap.config
, then all
transactions for that connection will be impacted by the override, not just
the ones matching that
remap.config
rule.
See
Timeout Settings
for more discussion on Traffic Server timeouts.
Note that for QUIC this will be ignored and
proxy.config.quic.no_activity_timeout_in
should be used instead.
proxy.config.net.inactivity_check_frequency
Scope
CONFIG
Type
INT
Default
yaml:
records
net
inactivity_check_frequency
How frequent (in seconds) to check for inactive connections. If you deal
with a lot of concurrent connections, increasing this setting can reduce
pressure on the system.
proxy.config.incoming_ip_to_bind
Scope
CONFIG
Type
STRING
Default
0.0.0.0 [::]
yaml:
records
incoming_ip_to_bind
0.0.0.0 [::]
Controls the global default IP addresses to which to bind proxy server
ports. The value is a space separated list of IP addresses, one per
supported IP address family (currently IPv4 and IPv6).
Unless explicitly specified in
proxy.config.http.server_ports
, the
server port will be bound to one of these addresses, selected by IP address
family. The built in default is any address. This is used if no address for
a family is specified. This setting is useful if most or all server ports
should be bound to the same address.
Note
This is ignored for inbound transparent server ports because they must be
able to accept connections on arbitrary IP addresses.
Example
Set the global default for IPv4 to
192.168.101.18
and leave the global
default for IPv6 as any address
records
incoming_ip_to_bind
192.168.101.18
Example
Set the global default for IPv4 to
191.68.101.18
and the global default
for IPv6 to
fc07:192:168:101::17
records
incoming_ip_to_bind
"192.168.101.18
[fc07:192:168:101::17]"
proxy.config.outgoing_ip_to_bind
Scope
CONFIG
Type
STRING
Default
0.0.0.0 [::]
yaml:
records
outgoing_ip_to_bind
0.0.0.0 [::]
This controls the global default for the local IP address for outbound
connections to origin servers. The value is a list of space separated IP
addresses, one per supported IP address family (currently IPv4 and IPv6).
Unless explicitly specified in
proxy.config.http.server_ports
, one
of these addresses, selected by IP address family, will be used as the local
address for outbound connections. This setting is useful if most or all of
the server ports should use the same outbound IP addresses.
Note
This is ignored for outbound transparent ports as the local outbound address will be the same as the client local address.
Example
Set the default local outbound IP address for IPv4 connections to
192.168.101.18
records
outgoing_ip_to_bind
192.168.101.18
Example
Set the default local outbound IP address to
192.168.101.17
for IPv4 and
fc07:192:168:101::17
for IPv6.
records
outgoing_ip_to_bind
"192.168.101.17
[fc07:192:168:101::17]"
proxy.config.net.event_period
Scope
CONFIG
Type
INT
Default
10
yaml:
records
net
event_period
10
How often, in milli-seconds, to schedule IO event processing. This is
unlikely to be necessary to tune, and we discourage setting it to a value
smaller than 10ms (on Linux).
proxy.config.net.accept_period
Scope
CONFIG
Type
INT
Default
10
yaml:
records
net
accept_period
10
How often, in milli-seconds, to schedule accept() processing. This is
unlikely to be necessary to tune, and we discourage setting it to a value
smaller than 10ms (on Linux).
proxy.config.net.retry_delay
Scope
CONFIG
Type
INT
Default
10
Reloadable
Yes
yaml:
records
net
retry_delay
10
How long to wait until we retry various events that would otherwise block
the network processing threads (e.g. locks). We discourage setting this to
a value smaller than 10ms (on Linux).
proxy.config.net.throttle_delay
Scope
CONFIG
Type
INT
Default
50
Reloadable
Yes
yaml:
records
net
throttle_delay
50
When we trigger a throttling scenario, this how long our accept() are delayed.
Management
proxy.config.admin.user_id
Scope
CONFIG
Type
STRING
Default
nobody
yaml:
records
admin
user_id
nobody
Designates the non-privileged account to run the
traffic_server
process as, which also has the effect of setting ownership of configuration
and log files.
If the user_id is prefixed with pound character (
),
the remainder of the string is considered to be a
numeric user identifier
If the value is set to
#-1
, Traffic Server will not change the user during startup.
Important
Attempting to set this option to
root
or
#0
is now forbidden, as
a measure to increase security. Doing so will cause a fatal failure upon
startup in
traffic_server
. However, there are two ways to
bypass this restriction:
Specify
-DBIG_SECURITY_HOLE
in
CXXFLAGS
during compilation.
Set the
user_id=#-1
and start trafficserver as root.
proxy.config.admin.api.restricted
Scope
CONFIG
Type
INT
Default
yaml:
records
admin
api
restricted
This is now deprecated, please refer to
Configuration
to find
out about the new admin API mechanism.
HTTP Engine
proxy.config.http.server_ports
Scope
CONFIG
Type
STRING
Default
8080 8080:ipv6
yaml:
records
http
server_ports
8080 8080:ipv6
Ports used for proxying HTTP traffic.
This is a list, separated by space or comma, of
port descriptors.
Each descriptor is a sequence of keywords and values separated by colons.
Not all keywords have values, those that do are specifically noted. Keywords
with values can have an optional
character separating the keyword and
value. The case of keywords is ignored. The order of keywords is irrelevant
but unspecified results may occur if incompatible options are used (noted
below). Options without values are idempotent. Options with values use the
last (right most) value specified, except for
ip-out
as detailed later.
Quick reference chart:
Name
Note
Definition
port/path
Required
The local IP port or Unix domain path.
blind
Blind (
CONNECT
) port.
compress
Not Implemented
Compressed.
ipv4
Default
Bind to IPv4 address family.
ipv6
Bind to IPv6 address family.
ip-in
Value
Local inbound IP address.
ip-out
Value
Local outbound IP address.
ip-resolve
Value
IP address resolution style.
proto
Value
List of supported session protocols.
pp
Enable Proxy Protocol.
pp-clnt
Use the Proxy Protocol SRC IP as the client IP.
ssl
SSL terminated.
quic
QUIC terminated.
tr-full
Fully transparent (inbound and outbound)
tr-in
Inbound transparent.
tr-out
Outbound transparent.
tr-pass
Pass through enabled.
mptcp
Multipath TCP.
allow-plain
Allow failback to non-TLS for TLS ports
port
Local IP port number to bind. This is the port to which ATS clients will connect.
path
Unix Domain Socket path to bind to. This socket will be available for local
clients to connect to. Some port descriptors below are not applicable to
domain sockets.
blind
Accept only the
CONNECT
method on this port.
Not compatible with:
tr-in
ssl
and
quic
compress
Compress the connection. Retained only by inertia, should be considered “not implemented”.
ipv4
Use IPv4. This is the default and is included primarily for completeness. This forced if the
ip-in
option is used with an IPv4 address.
ipv6
Use IPv6. This is forced if the
ip-in
option is used with an IPv6 address.
ssl
Require SSL termination for inbound connections. SSL
must be configured
for this option to provide a functional server port.
Not compatible with:
blind
and
quic
allow-plain
allows a failback to non SSL for such ports.
quic
Require QUIC termination for inbound connections. SSL
must be configured
for this option to provide a functional server port.
THIS IS EXPERIMENTAL SUPPORT AND NOT READY FOR PRODUCTION USE.
Not compatible with:
blind
and
ssl
proto
Specify the
session level protocols
supported. These should be
separated by semi-colons. For TLS proxy ports the default value is
all available protocols. For non-TLS proxy ports the default is HTTP
only. HTTP/3 is only available on QUIC ports.
pp
Enables Proxy Protocol on the port. If Proxy Protocol is enabled on the
port, Traffic Server tries to parse the header first, and it falls back to the regular connection handling based on other keywords. See
Proxy Protocol
for more details on how to configure
this option properly.
tr-full
Fully transparent. This is a convenience option and is identical to specifying both
tr-in
and
tr-out
Not compatible with: Any option not compatible with
tr-in
or
tr-out
tr-in
Inbound transparent. The proxy port will accept connections to any IP address on the port. To have IPv6 inbound transparent you must use this and the
ipv6
option. This overrides
proxy.config.incoming_ip_to_bind
for this port.
Not compatible with:
ip-in
blind
tr-out
Outbound transparent. If ATS connects to an origin server for a transaction on this port, it will use the client’s address as its local address. This overrides
proxy.config.outgoing_ip_to_bind
for this port.
Not compatible with:
ip-out
ip-resolve
tr-pass
Transparent pass through. This option is useful only for inbound transparent proxy ports. If the parsing of the expected HTTP header fails, then the transaction is switched to a blind tunnel instead of generating an error response to the client. It effectively enables
proxy.config.http.use_client_target_addr
for the transaction as there is no other place to obtain the origin server address.
ip-in
Set the local IP address for the port. This is the address to which clients will connect. This forces the IP address family for the port. The
ipv4
or
ipv6
can be used but it is optional and is an error for it to disagree with the IP address family of this value. An IPv6 address
must
be enclosed in square brackets. If this option is omitted
proxy.config.incoming_ip_to_bind
is used.
Not compatible with:
tr-in
ip-out
Set the local IP address for outbound connections. This is the address used by ATS locally when it connects to an origin server for transactions on this port. If this is omitted
proxy.config.outgoing_ip_to_bind
is used.
This option can used multiple times, once for each IP address family. The address used is selected by the IP address family of the origin server address.
Not compatible with:
tr-out
ip-resolve
Set the
host
resolution
style
for transactions on this proxy port.
Not compatible with:
tr-out
- this option requires a value of
client;none
which is forced and should not be explicitly specified.
mptcp
Enable Multipath TCP on this proxy port.
Requires custom Linux kernel available at
allow-plain
For TLS ports, will fall back to non-TLS processing if the TLS handshake fails. Incompatible with
quic ports.
Example
Listen on port 80 on any address for IPv4 and IPv6.:
80
80
ipv6
Example
Listen on unix domain socket at /var/run/trafficserver/proxy.sock and enable
Proxy Protocol
/var/run/trafficserver/proxy.sock:pp
Example
Listen transparently on any IPv4 address on port 8080, and
transparently on port 8080 on local address
fc01:10:10:1::1
(which implies
ipv6
).:
IPv4
tr
FULL
8080
TR
full
IP
in
fc02
10
10
::
]:
8080
Example
Listen on port 8080 for IPv6, fully transparent. Set up an SSL port on 443. These ports will use the IP address from
proxy.config.incoming_ip_to_bind
. Listen on IP address
192.168.17.1
, port 80, IPv4, and connect to origin servers using the local address
10.10.10.1
for IPv4 and
fc01:10:10:1::1
for IPv6.:
8080
ipv6
tr
full
443
ssl
ip
in
192.168.17.1
80
ip
out
fc01
10
10
::
]:
ip
out
10.10.10.1
Example
Listen on port 9090 for TLS enabled HTTP/2 or HTTP connections, accept no other session protocols.:
9090
proto
http2
http
ssl
Example
Listen on port 9090 for TLS disabled HTTP/2 and enabled HTTP connections, accept no other session protocols.:
9090
proto
http
ssl
Example
Listen on port 4433 for QUIC connections.:
4433
quic
proxy.config.http.connect_ports
Scope
CONFIG
Type
STRING
Default
443
yaml:
records
http
connect_ports
'443'
The range of origin server ports that can be used for tunneling via
CONNECT
Traffic Server allows tunnels only to the specified ports. Values are space separated. Wildcards
), ranges (
0-1023
), and mixes of each (e.g.
80
443
666-999
) are supported.
Note
These are the ports on the
origin server
, not Traffic Server
proxy
ports
proxy.config.http.forward_connect_method
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
Overridable
Yes
yaml:
records
http
forward_connect_method
The default, Traffic Server behavior for handling a CONNECT method request
is to establish a tunnel to the requested destination. This
configuration alters the behavior so that Traffic Server forwards the
CONNECT method to the next hop, and establishes the tunnel after
receiving a positive response. This behavior is useful in a proxy
hierarchy, and is equivalent to setting
proxy.config.http.parent_proxy.disable_connect_tunneling
to
when parent proxying is enabled.
proxy.config.http.insert_request_via_str
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
Overridable
Yes
yaml:
records
http
insert_request_via_str
Set how the
Via
field is handled on a request to the origin server.
Value
Effect
Do not modify or set this Via header.
Add the basic protocol and proxy identifier.
Add basic transaction codes.
Add detailed transaction codes.
Add full user agent connection
protocol tags
Note
The
Via
transaction codes can be decoded with the
Via Decoder Ring
proxy.config.http.request_via_str
Scope
CONFIG
Type
STRING
Default
ApacheTrafficServer/${PACKAGE_VERSION}
Reloadable
Yes
Overridable
Yes
yaml:
records
http
request_via_str
ApacheTrafficServer/${PACKAGE_VERSION}
Set the server and version string in the
Via
request header to the origin server which is inserted when the value of
proxy.config.http.insert_request_via_str
is not
. Note that the actual default value is defined with
"ApacheTrafficServer/"
PACKAGE_VERSION
in a C++ source code, and you must write such as
ApacheTrafficServer/6.0.0
if you really set a value with the version in
records.yaml
file. If you want to hide the version, you can set this value to
ApacheTrafficServer
proxy.config.http.insert_response_via_str
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
Overridable
Yes
yaml:
records
http
insert_response_via_str
Set how the
Via
field is handled on the response to the client.
Value
Effect
Do not modify or set this Via header.
Add the basic protocol and proxy identifier.
Add basic transaction codes.
Add detailed transaction codes.
Add full upstream connection
protocol tags
Note
The
Via
transaction code can be decoded with the
Via Decoder Ring
proxy.config.http.response_via_str
Scope
CONFIG
Type
STRING
Default
ApacheTrafficServer/${PACKAGE_VERSION}
Reloadable
Yes
Overridable
Yes
yaml:
records
http
response_via_str
ApacheTrafficServer/${PACKAGE_VERSION}
Set the server and version string in the
Via
response header to the client which is inserted when the value of
proxy.config.http.insert_response_via_str
is not
. Note that the actual default value is defined with
"ApacheTrafficServer/"
PACKAGE_VERSION
in a C++ source code, and you must write such as
ApacheTrafficServer/6.0.0
if you really set a value with the version in
records.yaml
file. If you want to hide the version, you can set this value to
ApacheTrafficServer
proxy.config.http.send_100_continue_response
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
yaml:
records
http
send_100_continue_response
You can specify one of the following:
Value
Description
Traffic Server will buffer the request until the post body has been received and
then send the request to the origin server.
Immediately return a
100
Continue
from Traffic Server without waiting for
the post body.
proxy.config.http.response_server_enabled
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
Overridable
Yes
yaml:
records
http
response_server_enabled
You can specify one of the following:
Value
Description
No
Server
header is added to the response.
The
Server
header is added according to
proxy.config.http.response_server_str
The
Server
header is added only if the response from origin does
not have one already.
proxy.config.http.response_server_str
Scope
CONFIG
Type
STRING
Default
ATS/${PACKAGE_VERSION}
Reloadable
Yes
Overridable
Yes
yaml:
records
http
response_server_str
ATS/${PACKAGE_VERSION}
The
Server
string that Traffic Server will insert in a response header (if
requested, see above). Note that the actual default value is defined with
"ATS/"
PACKAGE_VERSION
in the C++ source, and you must write such as
ATS/6.0.0
if you really set a value with the version in
records.yaml
. If you want to hide the version, you can set this
value to
ATS
proxy.config.http.insert_age_in_response
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
Overridable
Yes
yaml:
records
http
insert_age_in_response
This option specifies whether Traffic Server should insert an
Age
header in the
response. The value is the cache’s estimate of the amount of time since the
response was generated or revalidated by the origin server.
Value
Description
No
Age
header is added.
Age
header is added.
proxy.config.http.chunking_enabled
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
Overridable
Yes
yaml:
records
http
chunking_enabled
Specifies whether Traffic Server can generate a chunked response:
Value
Description
Never respond with chunked encoding.
Always respond with chunked encoding.
Generate a chunked response if the origin server has previously
returned HTTP/1.1.
Generate a chunked response if the client request is HTTP/1.1 and the
origin server has previously returned HTTP/1.1.
proxy.config.http.chunking.size
Scope
CONFIG
Type
INT
Default
4096
Overridable
Yes
yaml:
records
http
chunking
size
4096
If chunked transfer encoding is enabled with
proxy.config.http.chunking_enabled
and the conditions specified by that option’s setting are met by the current
request, this option determines the size of the chunks, in bytes, to use
when sending content to an HTTP/1.1 client.
proxy.config.http.drop_chunked_trailers
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
Overridable
Yes
yaml:
records
http
drop_chunked_trailers
Specifies whether Traffic Server should drop chunked trailers. If enabled (
), Traffic Server
will drop any chunked trailers in a
Transfer-Encoded:
chunked
request or
response body. If disabled (
), Traffic Server will pass the chunked trailers
unmodified to the receiving peer. See
RFC 9112, section 7.1.2
for details about chunked trailers. By default, this option is enabled
and therefore Traffic Server will drop chunked trailers.
proxy.config.http.strict_chunk_parsing
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
Overridable
Yes
yaml:
records
http
strict_chunk_parsing
Specifies whether Traffic Server strictly checks errors in chunked message body.
If enabled (
), Traffic Server returns 400 Bad Request if chunked message body is
not compliant with RFC 9112. If disabled (
), Traffic Server allows using LF as
a line terminator.
proxy.config.http.send_http11_requests
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
Overridable
Yes
yaml:
records
http
send_http11_requests
Specifies when and how Traffic Server uses HTTP/1.1 to communicate with the origin
server.
Value
Description
Never use HTTP/1.1.
Always use HTTP/1.1.
Use HTTP/1.1 with origin connections only if the server has previously
returned HTTP/1.1.
If the client request is HTTP/1.1 and the origin server has previously
returned HTTP/1.1, then use HTTP/1.1 for origin server connections.
Note
If
proxy.config.http.use_client_target_addr
is set to
, then
options
and
for this configuration variable cause the proxy
to use the client HTTP version for upstream requests.
proxy.config.http.auth_server_session_private
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
Overridable
Yes
yaml:
records
http
auth_server_session_private
Specifies whether Traffic Server should close the origin connection and not reuse it if the request contains an
Authorization
Proxy-Authorization
, or
Www-Authenticate
header. Private connections are
associated with a single client connection and are not shared with other client connections.
Value
Description
The origin connection will be available for reuse.
The origin connection will be closed after the client is done with it and if the request contains an
Authorization
Proxy-Authorization
, or
Www-Authenticate
header.
The origin connection will be closed after the client is done with it and if the request contains a
Proxy-Authorization
or
Www-Authenticate
header.
proxy.config.http.server_session_sharing.match
Scope
CONFIG
Type
STRING
Default
both
Overridable
Yes
yaml:
records
http
server_session_sharing
match
both
Enable and set the ability to re-use server connections across client
connections. Multiple values can be specified when separated by commas with no white spaces. Valid values are:
Value
Description
none
Do not match and do not re-use server sessions.
ip
Re-use server sessions, checking only that the IP address and port
of the origin server matches.
host
Re-use server sessions, checking that the fully qualified
domain name matches. In addition, if the session uses TLS, it also
checks that the current transaction’s host header value matches the session’s SNI.
both
Equivalent to
host,ip
hostonly
Check that the fully qualified domain name matches.
sni
Check that the SNI of the session matches the SNI that would be used to
create a new session. Only applicable for TLS sessions.
cert
Check that the certificate file name used for the server session matches the
certificate file name that would be used for the new server session. Only
applicable for TLS sessions.
The setting must contain at least one of
ip
host
hostonly
or
both
for session reuse to operate. The other values may be used for greater control
with TLS session reuse.
Note
Server sessions to different upstream ports never match even if the FQDN and IP
address match.
Note
Upstream
session
tracking
uses a similar
set of options for matching sessions, but is
set
independently
from session sharing.
proxy.config.http.server_session_sharing.pool
Scope
CONFIG
Type
STRING
Default
thread
yaml:
records
http
server_session_sharing
pool
thread
Control the scope of server session re-use if it is enabled by
proxy.config.http.server_session_sharing.match
. Valid values are:
Value
Description
global
Re-use sessions from a global pool of all server sessions.
thread
Re-use sessions from a per-thread pool.
hybrid
Try to work as a global pool, but release server sessions
to the per-thread pool if there is lock contention on the
global pool.
global_locked
Similar to global, except that the session pool is
managed by a blocking mutex.
Setting
proxy.config.http.server_session_sharing.pool
to global can reduce the number of connections to origin for some
traffic loads. However, if many execute threads are active, the thread
contention on the global pool can reduce the lifetime of connections
to origin and reduce effective origin connection reuse.
For a hybrid pool, the operation starts as the global pool, but sessons
are returned to the local thread pool if the global pool lock is not
acquired rather than just closing the origin connection as is the
case in standard global mode.
For a
global_locked
pool connections are managed by a blocking
mutex instead of the normal try mutex. Under extreme transaction
loads the connection pool starvation may result in most transactions
bypassing the connection pool resulting in runaway upstream
connections. This option will avoid this condition at the cost of
latency and ttfb (time to first byte) performance).
proxy.config.http.attach_server_session_to_client
Scope
CONFIG
Type
INT
Default
Overridable
Yes
yaml:
records
http
attach_server_session_to_client
Control the re-use of an server session by a user agent (client) session. Currently only applies to user
agents using HTTP/1.0 or HTTP/1.1. For other HTTP versions, the origin connection is always returned to the
session sharing pool or closed.
If a user agent performs more than one HTTP transaction on its connection to Traffic Server a server session must be
obtained for the second (and subsequent) transaction as for the first. This settings affects how that server session
is selected.
If this setting is
then after the first transaction the server session for that transaction is released to the
server pool (if any). When a server session is needed for subsequent transactions one is selected from the server
pool or created if there is no suitable server session in the pool.
If this setting is not
then the current server session for the user agent session is “sticky”. It will be
preferred to any other server session (either from the pool or newly created). The server session will be detached
from the user agent session only if it cannot be used for the transaction. This is determined by the
proxy.config.http.server_session_sharing.match
value. If the server session matches the next transaction
according to this setting then it will be used, otherwise it will be released to the pool and a different session
selected or created.
proxy.config.http.max_proxy_cycles
Scope
CONFIG
Type
INT
Default
Overridable
Yes
yaml:
records
http
max_proxy_cycles
Control the proxy cycle detection function in the following manner –
If this setting is
, then next hop is self IP address and port detection is active.
In addition, the proxy cycle detection using the Via string will declare a cycle if the current cache
appears one or more times in the Via string, i.e, > 0.
If this setting is
or more (N), then next hop is self IP address and port detection is inactive.
In addition, the proxy cycle detection using the Via string will declare a cycle if the current cache
appears more than N times in the Via string, i.e., > N.
Examples:
If the setting is
, then the second time a request enters a cache it will have its own machine
identifier in the Via string once, so a cycle will be detected. So no cycles are allowed.
If the setting is
, then the third time a request enters a cache it will have its own machine
identifier in the Via string twice, so a cycle will be detected. So one cycle is allowed.
The first cycle with two visits to the cache and one instance in the Via string is allowed.
The second cycle with three visits to the cache and two instances in the Via string is not allowed.
This setting allows an edge cache peering arrangement where an edge cache may forward a request to a
peer edge cache (possibly itself) a limited of times (usually once). Infinite loops are still detected
when the cycle allowance is exceeded.
proxy.config.http.use_client_target_addr
Scope
CONFIG
Type
INT
Default
yaml:
records
http
use_client_target_addr
For fully transparent ports use the same origin server address as the client.
This option causes Traffic Server to avoid where possible doing DNS lookups in forward
transparent proxy mode. The option is only effective if the following three
conditions are true:
Traffic Server is in forward proxy mode.
The proxy port is inbound transparent.
The target URL has not been modified by either remapping or a plugin.
If any of these conditions are not true, then normal DNS processing is done
for the connection.
There are three valid values.
Value
Description
Disables the feature.
Enables the feature with address verification. The proxy does the
regular DNS processing. If the client-specified origin address is not
in the set of addresses found by the proxy, the request continues to
the client specified address, but the result is not cached.
Enables the feature with no address verification. No DNS processing is
performed. The result is cached (if allowed otherwise).
This option is vulnerable to cache poisoning if an incorrect
Host
header is
specified, so this option should be used with extreme caution if HTTP caching is
enabled. See bug
TS-2954
for details.
If all of these conditions are met, then the origin server IP address is
retrieved from the original client connection, rather than through HostDB or
DNS lookup. In effect, client DNS resolution is used instead of Traffic Server DNS.
This can be used to be a little more efficient (looking up the target once
by the client rather than by both the client and Traffic Server) but the primary use
is when client DNS resolution can differ from that of Traffic Server. Two known uses
cases are:
Embedded IP addresses in a protocol with DNS load sharing. In this case,
even though Traffic Server and the client both make the same request to the same
DNS resolver chain, they may get different origin server addresses. If
the address is embedded in the protocol then the overall exchange will
fail. One current example is Microsoft Windows update, which presumably
embeds the address as a security measure.
The client has access to local DNS zone information which is not
available to Traffic Server. There are corporate nets with local DNS information
for internal servers which, by design, is not propagated outside the core
corporate network. Depending a network topology it can be the case that
Traffic Server can access the servers by IP address but cannot resolve such
addresses by name. In such as case the client supplied target address
must be used.
This solution must be considered interim. In the longer term, it should be
possible to arrange for much finer grained control of DNS lookup so that
wildcard domain can be set to use Traffic Server or client resolution. In both known
use cases, marking specific domains as client determined (rather than a
single global switch) would suffice. It is possible to do this crudely with
this flag by enabling it and then use identity URL mappings to re-disable it
for specific domains.
proxy.config.http.keep_alive_enabled_in
Scope
CONFIG
Type
INT
Default
Overridable
Yes
yaml:
records
http
keep_alive_enabled_in
Enables (
) or disables (
) incoming keep-alive connections.
proxy.config.http.keep_alive_enabled_out
Scope
CONFIG
Type
INT
Default
Overridable
Yes
yaml:
records
http
keep_alive_enabled_out
Enables (
) or disables (
) outgoing keep-alive connections.
Note
Enabling keep-alive does not automatically enable purging of keep-alive
requests when nearing the connection limit, that is controlled by
proxy.config.http.server_max_connections
proxy.config.http.keep_alive_post_out
Scope
CONFIG
Type
INT
Default
Overridable
Yes
yaml:
records
http
keep_alive_post_out
Controls whether new POST requests re-use keep-alive sessions (
) or
create new connections per request (
).
proxy.config.http.disallow_post_100_continue
Scope
CONFIG
Type
INT
Default
yaml:
records
http
disallow_post_100_continue
Allows you to return a 405 Method Not Supported with Posts also
containing an Expect: 100-continue.
When a Post w/ Expect: 100-continue is blocked the stat
proxy.process.http.disallowed_post_100_continue will be incremented.
proxy.config.http.default_buffer_size
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
Overridable
Yes
yaml:
records
http
default_buffer_size
Configures the default buffer size, in bytes, to allocate for incoming
request bodies which lack a
Content-length
header.
proxy.config.http.default_buffer_water_mark
Scope
CONFIG
Type
INT
Default
32768
Reloadable
Yes
Overridable
Yes
yaml:
records
http
default_buffer_water_mark
32768
Number of bytes Traffic Server is allowed to read ahead of the client from the origin. Note that when
Read While Write
settings are in place,
this setting will apply to the first client to request the object, regardless if subsequent,
simultaneous clients of that object can read faster. The buffered bytes will consume memory
while waiting for the client to consume them.
While this setting is reloadable, dramatic changes can cause bigger memory usage than expected
and is thus not recommended.
proxy.config.http.request_buffer_enabled
Scope
CONFIG
Type
INT
Default
Overridable
Yes
yaml:
records
http
request_buffer_enabled
This enables buffering the content for incoming
POST
requests. If enabled no outbound
connection is made until the entire
POST
request has been buffered.
If enabled,
proxy.config.http.post_copy_size
needs to be set to the maximum of the post body
size allowed, otherwise, the post would fail.
proxy.config.http.request_line_max_size
Scope
CONFIG
Type
INT
Default
65535
Reloadable
Yes
yaml:
records
http
request_line_max_size
65535
Controls the maximum size, in bytes, of an HTTP Request Line in requests. Requests
with a request line exceeding this size will be treated as invalid and
rejected by the proxy. Note that the HTTP request line typically includes HTTP method,
request target and HTTP version string except when the request is made using absolute
URI in which case the request line may also include the request scheme and domain name.
proxy.config.http.header_field_max_size
Scope
CONFIG
Type
INT
Default
32768
Reloadable
Yes
yaml:
records
http
header_field_max_size
32768
Controls the maximum size, in bytes, of an HTTP header field in requests. Headers
in a request with the sum of their name and value that exceed this size will cause the
entire request to be treated as invalid and rejected by the proxy.
proxy.config.http.request_header_max_size
Scope
CONFIG
Type
INT
Default
32768
Reloadable
Yes
Overridable
Yes
yaml:
records
http
request_header_max_size
32768
Controls the maximum size, in bytes, of an HTTP header in requests. Headers
in a request which exceed this size will cause the entire request to be
treated as invalid and rejected by the proxy.
proxy.config.http.response_header_max_size
Scope
CONFIG
Type
INT
Default
32768
Reloadable
Yes
Overridable
Yes
yaml:
records
http
response_header_max_size
32768
Controls the maximum size, in bytes, of headers in HTTP responses from the
proxy. Any responses with a header exceeding this limit will be treated as
invalid and a client error will be returned instead.
proxy.config.http.global_user_agent_header
Scope
CONFIG
Type
STRING
Default
null
Overridable
Yes
yaml:
records
http
global_user_agent_header
'null'
An arbitrary string value that, if set, will be used to replace any request
User-Agent
header.
proxy.config.http.strict_uri_parsing
Scope
CONFIG
Type
INT
Default
yaml:
records
http
strict_uri_parsing
Takes a value between 0 and 2.
disables strict_uri_parsing. Any character can appears
in the URI.
causes Traffic Server to return 400 Bad Request
if client’s request URI includes character which is not RFC 3986 compliant.
directs Traffic Server
to reject the clients request if it contains whitespace or non-printable characters.
proxy.config.http.errors.log_error_pages
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
yaml:
records
http
errors
log_error_pages
Enables (
) or disables (
) the logging of responses to bad requests
to the error logging destination. Disabling this option prevents error
responses (such as
403
s) from appearing in the error logs. Any HTTP
response status codes equal to, or higher, than the minimum code defined by
TS_HTTP_STATUS_BAD_REQUEST
are affected by this setting.
Parent Proxy Configuration
proxy.config.http.parent_proxy.retry_time
Scope
CONFIG
Type
INT
Default
300
Reloadable
Yes
Overridable
Yes
yaml:
records
http
parent_proxy
retry_time
300
The amount of time allowed between connection retries to a parent cache that is unavailable.
proxy.config.http.parent_proxy.max_trans_retries
Scope
CONFIG
Type
INT
Default
yaml:
records
http
parent_proxy
max_trans_retries
Limits the number of simultaneous transactions that may retry a parent once the parents
retry_time
has expired.
proxy.config.http.parent_proxy.fail_threshold
Scope
CONFIG
Type
INT
Default
10
Reloadable
Yes
Overridable
Yes
yaml:
records
http
parent_proxy
fail_threshold
10
The number of times the connection to the parent cache can fail before Traffic Server considers the parent unavailable.
proxy.config.http.parent_proxy.total_connect_attempts
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
Overridable
Yes
yaml:
records
http
parent_proxy
total_connect_attempts
The total number of connection attempts for a specific transaction allowed to
a parent cache before Traffic Server bypasses the parent or fails the request
(depending on the
go_direct
option in the
parent.config
file). The
number of parents tried is
proxy.config.http.parent_proxy.fail_threshold
proxy.config.http.parent_proxy.total_connect_attempts
proxy.config.http.parent_proxy.per_parent_connect_attempts
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
Overridable
Yes
yaml:
records
http
parent_proxy
per_parent_connect_attempts
The total number of connection attempts allowed per parent for a specific
transaction, if multiple parents are used.
proxy.config.http.parent_proxy.mark_down_hostdb
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
Overridable
Yes
yaml:
records
http
parent_proxy
mark_down_hostdb
Enables (
) or disables (
) marking parent proxies down in hostdb when a connection
error is detected. Normally parent selection manages parent proxies and will mark them as unavailable
as needed. But when parents are defined in dns with multiple ip addresses, it may be useful to mark the
failing ip down in hostdb. In this case you would enable these updates.
proxy.config.http.forward.proxy_auth_to_parent
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
Overridable
Yes
yaml:
records
http
forward
proxy_auth_to_parent
Configures Traffic Server to send proxy authentication headers on to the parent cache.
proxy.config.http.no_dns_just_forward_to_parent
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
Overridable
Yes
yaml:
records
http
no_dns_just_forward_to_parent
Don’t try to resolve DNS, forward all DNS requests to the parent. This is off (
) by default.
proxy.config.http.parent_proxy.disable_connect_tunneling
Scope
CONFIG
Type
INT
Default
yaml:
records
http
parent_proxy
disable_connect_tunneling
proxy.config.http.parent_proxy.self_detect
Scope
CONFIG
Type
INT
Default
yaml:
records
http
parent_proxy
self_detect
For each host that has been specified in a
parent
or
secondary_parent
list in the
parent.config
file, determine if the host is the same as the current host.
Obvious examples include
localhost
and
127.0.0.1
. If a match is found,
take an action depending upon the value below.
Value
Description
Disables the feature by not checking for matches.
Remove the matching host from the list.
Mark the host down. This is the default.
proxy.config.http.parent_proxy.consistent_hash_algorithm
Scope
CONFIG
Type
STRING
Default
siphash24
yaml:
records
http
parent_proxy
consistent_hash_algorithm
siphash24
Selects the hash algorithm used for consistent hash parent selection. This setting
only affects parent selection when
round_robin=consistent_hash
is configured in
parent.config
. The hash algorithm determines how requests are distributed
across parent proxies.
Value
Description
siphash24
SipHash-2-4 (default). Cryptographically strong, DoS-resistant hash function.
siphash13
SipHash-1-3. ~50% faster than SipHash-2-4, still DoS-resistant.
Warning
Changing this setting will cause requests to be redistributed differently across
parent proxies. This can lead to cache churn and increased origin load during the
transition period. Plan the migration carefully and consider doing it during
low-traffic periods.
proxy.config.http.parent_proxy.consistent_hash_seed0
Scope
CONFIG
Type
INT
Default
yaml:
records
http
parent_proxy
consistent_hash_seed0
The first 64 bits of the hash seed (key) for consistent hash parent selection.
This setting only affects parent selection when
round_robin=consistent_hash
is configured.
For SipHash algorithms, this forms the first half of the 128-bit cryptographic key (k0)
For future 64-bit hash algorithms (like XXH3), this is the full seed value
The value must be specified as a decimal integer (e.g.
12345678901234567
). Default is
Per-rule configuration is available in
parent.config
using
hash_seed0=
Per-strategy configuration is available in
strategies.yaml
using
hash_seed0:

proxy.config.http.parent_proxy.consistent_hash_seed1
Scope
CONFIG
Type
INT
Default
yaml:
records
http
parent_proxy
consistent_hash_seed1
The second 64 bits of the hash seed (key) for consistent hash parent selection.
This setting only affects parent selection when
round_robin=consistent_hash
is configured.
For SipHash algorithms, this forms the second half of the 128-bit cryptographic key (k1)
For future 64-bit hash algorithms, this value is ignored
The value must be specified as a decimal integer (e.g.
9876543210987654321
). Default is
Per-rule configuration is available in
parent.config
using
hash_seed1=
Per-strategy configuration is available in
strategies.yaml
using
hash_seed1:

proxy.config.http.parent_proxy.consistent_hash_replicas
Scope
CONFIG
Type
INT
Default
1024
yaml:
records
http
parent_proxy
consistent_hash_replicas
1024
The number of virtual nodes (replicas) per parent host on the consistent hash ring.
This setting only affects parent selection when
round_robin=consistent_hash
is configured.
Increasing the replica count improves the distribution of requests across parent proxies
but uses more memory. The default value of 1024 provides good distribution in most scenarios.
Must be greater than 0. Default is
1024
Per-rule configuration is available in
parent.config
using
hash_replicas=
Per-strategy configuration is available in
strategies.yaml
using
hash_replicas:

proxy.config.http.parent_proxy.enable_parent_timeout_markdowns
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
Overridable
Yes
yaml:
records
http
parent_proxy
enable_parent_timeout_markdowns
Enables (
) or disables (
) parent proxy mark downs due to inactivity
timeouts. By default parent proxies are not marked down due to inactivity
timeouts, the transaction will retry using another parent instead. The
default for this configuration keeps this behavior and is disabled (
).
This setting is overridable using one of the two plugins
header_rewrite
or
conf_remap
to enable inactivity timeout markdowns and should be done
so rather than enabling this globally. This setting should not be used in
conjunction with
proxy.config.http.parent_proxy.disable_parent_markdowns
proxy.config.http.parent_proxy.disable_parent_markdowns
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
Overridable
Yes
yaml:
records
http
parent_proxy
disable_parent_markdowns
Enables (
) or disables (
) parent proxy markdowns. This is useful
if parent entries in a parent.config line are VIP’s and one doesn’t wish
to mark down a VIP which may have several origin or parent proxies behind
the load balancer. This setting is overridable using one of the
header_rewrite
or the
conf_remap
plugins to override the default
setting and this method should be used rather than disabling markdowns
globally. This setting should not be used in conjunction with
proxy.config.http.parent_proxy.enable_parent_timeout_markdowns
HTTP Connection Timeouts
proxy.config.http.keep_alive_no_activity_timeout_in
Scope
CONFIG
Type
INT
Default
120
Reloadable
Yes
Overridable
Yes
yaml:
records
http
keep_alive_no_activity_timeout_in
120
Specifies how long Traffic Server keeps connections to clients open for a
subsequent request after a transaction ends. A value of
will set
proxy.config.net.default_inactivity_timeout
as the timeout.
See
Timeout Settings
for more discussion on Traffic Server timeouts.
proxy.config.http.keep_alive_no_activity_timeout_out
Scope
CONFIG
Type
INT
Default
120
Reloadable
Yes
Overridable
Yes
yaml:
records
http
keep_alive_no_activity_timeout_out
120
Specifies how long Traffic Server keeps connections to origin servers open
for a subsequent transfer of data after a transaction ends. A value of
will
set
proxy.config.net.default_inactivity_timeout
as the timeout.
See
Timeout Settings
for more discussion on Traffic Server timeouts.
proxy.config.http.transaction_no_activity_timeout_in
Scope
CONFIG
Type
INT
Default
30
Reloadable
Yes
Overridable
Yes
yaml:
records
http
transaction_no_activity_timeout_in
30
Specifies how long Traffic Server keeps connections to clients open if a
transaction stalls.
See
Timeout Settings
for more discussion on Traffic Server timeouts.
proxy.config.http.transaction_no_activity_timeout_out
Scope
CONFIG
Type
INT
Default
30
Reloadable
Yes
Overridable
Yes
yaml:
records
http
transaction_no_activity_timeout_out
30
Specifies how long Traffic Server keeps connections to origin servers open if the transaction stalls.
See
Timeout Settings
for more discussion on Traffic Server timeouts.
proxy.config.websocket.no_activity_timeout
Scope
CONFIG
Type
INT
Default
600
Reloadable
Yes
Overridable
Yes
yaml:
records
websocket
no_activity_timeout
600
Specifies how long Traffic Server keeps connections open if a websocket stalls.
See
Timeout Settings
for more discussion on Traffic Server timeouts.
proxy.config.websocket.active_timeout
Scope
CONFIG
Type
INT
Default
3600
Reloadable
Yes
Overridable
Yes
yaml:
records
websocket
active_timeout
3600
The maximum amount of time Traffic Server keeps websocket connections open.
See
Timeout Settings
for more discussion on Traffic Server timeouts.
proxy.config.http.transaction_active_timeout_in
Scope
CONFIG
Type
INT
Default
900
Reloadable
Yes
Overridable
Yes
yaml:
records
http
transaction_active_timeout_in
900
The maximum amount of time Traffic Server can remain connected to a client. If the transfer to the client is not complete before this
timeout expires, then Traffic Server closes the connection.
The value of
specifies that there is no timeout.
See
Timeout Settings
for more discussion on Traffic Server timeouts.
proxy.config.http.transaction_active_timeout_out
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
Overridable
Yes
yaml:
records
http
transaction_active_timeout_out
The maximum amount of time Traffic Server waits for fulfillment of a connection request to an origin server. If Traffic Server does not
complete the transfer to the origin server before this timeout expires, then Traffic Server terminates the connection request.
The default value of
specifies that there is no timeout.
See
Timeout Settings
for more discussion on Traffic Server timeouts.
proxy.config.http.accept_no_activity_timeout
Scope
CONFIG
Type
INT
Default
120
Reloadable
Yes
yaml:
records
http
accept_no_activity_timeout
120
The timeout interval in seconds before Traffic Server closes a connection that has no activity.
See
Timeout Settings
for more discussion on Traffic Server timeouts.
proxy.config.http.background_fill_active_timeout
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
Overridable
Yes
yaml:
records
http
background_fill_active_timeout
Specifies how long Traffic Server continues a background fill before giving up and dropping the origin server connection.
See
Timeout Settings
for more discussion on Traffic Server timeouts.
proxy.config.http.background_fill_completed_threshold
Scope
CONFIG
Type
FLOAT
Default
0.0
Reloadable
Yes
Overridable
Yes
yaml:
records
http
background_fill_completed_threshold
0.0
The proportion of total document size already transferred when a client aborts at which the proxy continues fetching the document
from the origin server to get it into the cache (a
background fill
).
HTTP Redirection
proxy.config.http.number_of_redirections
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
Overridable
Yes
yaml:
records
http
number_of_redirections
This setting determines the maximum number of times Trafficserver does a redirect follow location on receiving a 3XX Redirect response
for a given client request.
Note
When
proxy.config.http.number_of_redirections
is set to a positive value and Traffic Server has previously cached a 3XX Redirect response, the cached response will continue to be refreshed and returned until the response is no longer in the cache.
Note
In previous versions proxy.config.http.redirection_enabled had to be set to 1 before this setting was evaluated. Now setting
proxy.config.http.number_of_redirections
to a value greater than zero is sufficient to cause Traffic Server to follow redirects.
proxy.config.http.redirect_host_no_port
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
yaml:
records
http
redirect_host_no_port
This setting enables Trafficserver to not include the port in the Host header in the redirect follow request for default/standard ports
(e.g. 80 for HTTP and 443 for HTTPS). Note that the port is still included in the Host header if it’s non-default.
proxy.config.http.redirect_use_orig_cache_key
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
Overridable
Yes
yaml:
records
http
redirect_use_orig_cache_key
This setting enables Trafficserver to allow using original request cache key (for example, set using a TS API) during a 3xx redirect follow.
The default behavior (0) is to use the URL specified by Location header in the 3xx response as the cache key.
proxy.config.http.post_copy_size
Scope
CONFIG
Type
INT
Default
2048
Reloadable
Yes
yaml:
records
http
post_copy_size
2048
This setting determines the maximum size in bytes of uploaded content to be
buffered for HTTP methods such as POST and PUT.
proxy.config.http.redirect.actions
Scope
CONFIG
Type
STRING
Default
routable:follow
Reloadable
Yes
yaml:
records
http
redirect
actions
routable:follow
This setting determines how redirects should be handled. The setting consists
of a comma-separated list of key-value pairs, where the keys are named IP
address ranges and the values are actions.
The following are valid keys:
Key
Description
self
Addresses of the host’s interfaces
loopback
IPv4
127.0.0.0/8
and IPv6
::1
private
IPv4
10.0.0.0/8
100.64.0.0/10
172.16.0.0/12
192.168.0.0/16
and IPv6
fc00::/7
multicast
IPv4
224.0.0.0/4
and IPv6
ff00::/8
linklocal
IPv4
169.254.0.0/16
and IPv6
fe80::/10
routable
All publicly routable addresses
default
All address ranges not configured specifically
The following are valid values:
Value
Description
return
Do not process the redirect, send it as the proxy response.
reject
Do not process the redirect, send a 403 as the proxy response.
follow
Internally follow the redirect up to
proxy.config.http.number_of_redirections
Use this setting with caution!
Warning
Following a redirect to other than
routable
addresses can be
dangerous, as it allows the controller of an origin to arrange a probe the
Traffic Server host. Enabling these redirects makes Traffic Server open to third party attacks
and probing and therefore should be considered only in known safe
environments.
For example, a setting of
loopback:reject,private:reject,routable:follow,default:return
would send
403
as the proxy response to loopback and private addresses, routable
addresses would be followed up to
proxy.config.http.number_of_redirections
, and redirects to all other
ranges will be sent as the proxy response.
The action for
self
has the highest priority when an address would match
multiple keys, and the action for
default
has the lowest priority. Other
keys represent disjoint sets of addresses that will not conflict. If
duplicate keys are present in the setting, the right-most key-value pair is
used.
The default value is
routable:follow
, which means “follow routable
redirects, return all other redirects”. Note that
proxy.config.http.number_of_redirections
must be positive also,
otherwise redirects will be returned rather than followed.
Origin Server Connect Attempts
proxy.config.http.connect_attempts_max_retries
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
Overridable
Yes
yaml:
records
http
connect_attempts_max_retries
The maximum number of connection retries Traffic Server can make when the origin server is not responding.
Each retry attempt lasts for
proxy.config.http.connect_attempts_timeout
seconds. Once the maximum number of retries is
reached, the origin is marked down (as controlled by
proxy.config.http.connect.down.policy
. After this, the setting
proxy.config.http.connect_attempts_max_retries_down_server
is used to limit the number of retry attempts to the known down origin.
proxy.config.http.connect_attempts_max_retries_down_server
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
Overridable
Yes
yaml:
records
http
connect_attempts_max_retries_down_server
Maximum number of connection attempts Traffic Server can make while an origin is marked down per request. Typically this value is smaller than
proxy.config.http.connect_attempts_max_retries
so an error is returned to the client faster and also to reduce the load on the down origin.
The timeout interval
proxy.config.http.connect_attempts_timeout
in seconds is used with this setting.
proxy.config.http.connect_attempts_retry_backoff_base
Scope
CONFIG
Type
INT
Default
Units
milliseconds
Reloadable
Yes
Overridable
Yes
yaml:
records
http
connect_attempts_retry_backoff_base
The base delay, in milliseconds, used for exponential backoff between retry attempts to connect to the origin server. After each
failure the delay doubles - e.g. 64m, 128m, 256m. When this is set to
(the default value), Traffic Server retries immediately without exponential backoff.
proxy.config.http.connect.down.policy
Scope
CONFIG
Type
INT
Default
Overridable
Yes
yaml:
records
http
connect
down
policy
Controls what origin server connection failures contribute to marking a server down.
When set to
, any connection failure during the TCP and TLS handshakes will
contribute to marking the server down. When set to
, only TCP handshake failures
will contribute to marking a server down. When set to
, no connection failures
will be used towards marking a server down. When set to
, all failures covered
by
plus transaction inactive timeouts (server goes silent after connection is
established) will contribute to marking a server down.
proxy.config.http.server_max_connections
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
yaml:
records
http
server_max_connections
Limits the number of socket connections across all origin servers to the
value specified. To disable, set to zero (
).
This value is used in determining when and if to prune active origin
sessions. Without this value set, connections to origins can consume all the
way up to
proxy.config.net.connections_throttle
connections, which
in turn can starve incoming requests from available connections.
proxy.config.http.per_server.connection.max
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
Overridable
Yes
yaml:
records
http
per_server
connection
max
Set a limit for the number of concurrent connections to an upstream server group. A value of
disables checking. If a transaction attempts to connect to a group which already has the
maximum number of concurrent connections a 503
HTTPStatus::SERVICE_UNAVAILABLE
) error response is sent to the user agent. To configure
Upstream server group definition
See
proxy.config.http.per_server.connection.match
Frequency of alerts
See
proxy.config.http.per_server.connection.alert_delay
proxy.config.http.per_server.connection.match
Scope
CONFIG
Type
STRING
Default
both
Reloadable
Yes
Overridable
Yes
yaml:
records
http
per_server
connection
match
both
Control the definition of an upstream server group for
proxy.config.http.per_server.connection.max
. This must be one of the following keywords.
ip
Group by IP address. Each IP address is a group.
port
Group by IP address and port. Each distinct IP address and port pair is a group.
host
Group by host name. The host name is the post remap FQDN used to resolve the upstream
address.
both
Group by IP address, port, and host name. Each distinct combination is a group.
To disable upstream server grouping, set
proxy.config.http.per_server.connection.max
to
Note
This setting is independent of the
setting
for
upstream
session
sharing
matching
proxy.config.http.per_server.connection.alert_delay
Scope
CONFIG
Type
INT
Default
60
Units
seconds
Reloadable
Yes
yaml:
records
http
per_server
connection
alert_delay
60
Throttle alerts per upstream server group to be no more often than this many seconds. Summary
data is provided per alert to allow log scrubbing to generate accurate data.
proxy.config.http.per_server.connection.min
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
Overridable
Yes
yaml:
records
http
per_server
connection
min
Set a target for the minimum number of active connections to an upstream server group. When an
outbound connection is in keep alive state and the inactivity timer expires, if there are fewer
than this many connections in the group a new connection the timer is reset instead of closing
the connection. Useful when the origin supports keep-alive, removing the time needed to set up a
new connection from the next request at the expense of added (inactive) connections.
proxy.config.http.connect_attempts_rr_retries
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
Overridable
Yes
yaml:
records
http
connect_attempts_rr_retries
The maximum number of failed connection attempts allowed before a round-robin entry is marked as ‘down’ if a server
has round-robin DNS entries.
proxy.config.http.connect_attempts_timeout
Scope
CONFIG
Type
INT
Default
30
Reloadable
Yes
Overridable
Yes
yaml:
records
http
connect_attempts_timeout
30
The timeout value (in seconds) for time to set up a connection to the origin. After the connection is established the value of
proxy.config.http.transaction_no_activity_timeout_out
is used to established timeouts on the data over the connection.
See
Timeout Settings
for more discussion on Traffic Server timeouts.
proxy.config.http.post.check.content_length.enabled
Scope
CONFIG
Type
INT
Default
yaml:
records
http
post
check
content_length
enabled
Enables (
) or disables (
) checking the Content-Length: Header for a POST request.
proxy.config.http.down_server.cache_time
Scope
CONFIG
Type
INT
Default
60
Reloadable
Yes
Overridable
Yes
yaml:
records
http
down_server
cache_time
60
Specifies how long (in seconds) Traffic Server remembers that an origin server was unreachable.
proxy.config.http.uncacheable_requests_bypass_parent
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
Overridable
Yes
yaml:
records
http
uncacheable_requests_bypass_parent
When enabled (1), Traffic Server bypasses the parent proxy for a request that is not cacheable.
Congestion Control
proxy.config.http.flow_control.enabled
Scope
CONFIG
Type
INT
Default
Overridable
Yes
yaml:
records
http
flow_control
enabled
Transaction buffering / flow control is enabled if this is set to a non-zero value. Otherwise no flow control is done.
proxy.config.http.flow_control.high_water
Scope
CONFIG
Type
INT
Default
Units
bytes
Overridable
Yes
yaml:
records
http
flow_control
high_water
The high water mark for transaction buffer control. External source I/O is halted when the total buffer space in use
by the transaction exceeds this value.
proxy.config.http.flow_control.low_water
Scope
CONFIG
Type
INT
Default
Units
bytes
Overridable
Yes
yaml:
records
http
flow_control
low_water
The low water mark for transaction buffer control. External source I/O is resumed when the total buffer space in use
by the transaction is no more than this value.
proxy.config.http.websocket.max_number_of_connections
Scope
CONFIG
Type
INT
Default
-1
Reloadable
Yes
yaml:
records
http
websocket
max_number_of_connections
-1
When enabled >= (
), Traffic Server will enforce a maximum number of simultaneous websocket connections.
Negative Response Caching
proxy.config.http.negative_caching_enabled
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
Overridable
Yes
yaml:
records
http
negative_caching_enabled
When enabled (
), Traffic Server caches negative responses (such as
404
Not
Found
when a requested page does not exist. The next time a client requests the
same page, Traffic Server serves the negative response directly from cache.
When disabled (
), Traffic Server will only cache the response if the response has
Cache-Control
headers.
The following negative responses are cached by Traffic Server by default:
HTTP Response Code
Description
204
No Content
305
Use Proxy
403
Forbidden
404
Not Found
414
URI Too Long
500
Internal Server Error
501
Not Implemented
502
Bad Gateway
503
Service Unavailable
504
Gateway Timeout
The cache lifetime for objects cached from this setting is controlled via
proxy.config.http.negative_caching_lifetime
proxy.config.http.negative_caching_lifetime
Scope
CONFIG
Type
INT
Default
1800
Reloadable
Yes
Overridable
Yes
yaml:
records
http
negative_caching_lifetime
1800
How long (in seconds) Traffic Server keeps the negative responses valid in cache. This value only affects negative
responses that do NOT have explicit
Expires:
or
Cache-Control:
lifetimes set by the server.
proxy.config.http.negative_caching_list
Scope
CONFIG
Type
STRING
Default
204 305 403 404 414 500 501 502 503 504
Reloadable
Yes
Overridable
Yes
yaml:
records
http
negative_caching_list
204 305 403 404 414 500 501 502 503 504
The HTTP status code for negative caching. Default values are mentioned above. The unwanted status codes can be
taken out from the list. Other status codes can be added. The variable is a list but parsed as STRING.
proxy.config.http.negative_revalidating_enabled
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
Overridable
Yes
yaml:
records
http
negative_revalidating_enabled
Negative revalidating allows Traffic Server to return stale content if revalidation to the origin fails due
to network or HTTP errors. If it is enabled, rather than caching the negative response, the
current stale content is preserved and served. Note this is considered only on a revalidation of
already cached content. A revalidation failure means a connection failure or a 50x response code.
When considering replying with a stale response in these negative revalidating circumstances,
Traffic Server will respect the
proxy.config.http.cache.max_stale_age
configuration and will not
use a cached response older than
max_stale_age
seconds plus
max-age
of cached content.
A value of
disables serving stale content and a value of
enables keeping and serving stale content if revalidation fails.
proxy.config.http.negative_revalidating_lifetime
Scope
CONFIG
Type
INT
Default
1800
Reloadable
Yes
Overridable
Yes
yaml:
records
http
negative_revalidating_lifetime
1800
When replying with a stale cached response in negative revalidating circumstances (see
proxy.config.http.negative_revalidating_enabled
), Traffic Server includes an
Expires:
HTTP
header field in the cached response with a future time so that upstream caches will not try to
revalidate their respective stale objects. This configuration specifies how many seconds in the
future Traffic Server will calculate the value of this inserted
Expires:
header field.
There is a limitation to this method to be aware of: per specification (see IETF RFC 7234,
section 4.2.1),
Cache-Control:
response directives take precedence over the
Expires:
header field when determining object freshness. Thus if the cached response contains either a
max-age
or an
s-maxage
Cache-Control:
response directive, then these directives would
take precedence for the upstream caches over the inserted
Expires:
field, rendering the
Expires:
header ineffective in specifying the configured freshness lifetime.
Finally, be aware that the only way this configuration is used is as input into calculating the
value of these inserted
Expires:
header fields. This configuration does not direct Traffic Server
behavior with regard to whether it considers a stale object to be fresh enough to serve out of
cache when revalidation fails. As mentioned above in
proxy.config.http.negative_revalidating_enabled
proxy.config.http.cache.max_stale_age
is used for that determination.
This configuration defaults to 1,800 seconds (30 minutes).
proxy.config.http.negative_revalidating_list
Scope
CONFIG
Type
STRING
Default
500 502 503 504
Reloadable
Yes
Overridable
Yes
yaml:
records
http
negative_revalidating_list
500 502 503 504
The HTTP status codes for which the negative revalidating feature applies. Note that this is a
STRING
configuration containing a space separated list of the desired HTTP status codes.
Proxy User Variables
proxy.config.http.anonymize_remove_from
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
Overridable
Yes
yaml:
records
http
anonymize_remove_from
When enabled (
), Traffic Server removes the
From
header to protect the privacy of your users.
proxy.config.http.anonymize_remove_referer
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
yaml:
records
http
anonymize_remove_referer
When enabled (
), Traffic Server removes the
Referrer
header to protect the privacy of your site and users.
proxy.config.http.anonymize_remove_user_agent
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
Overridable
Yes
yaml:
records
http
anonymize_remove_user_agent
When enabled (
), Traffic Server removes the
User-agent
header to protect the privacy of your site and users.
proxy.config.http.anonymize_remove_cookie
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
Overridable
Yes
yaml:
records
http
anonymize_remove_cookie
When enabled (
), Traffic Server removes the
header to protect the privacy of your site and users.
proxy.config.http.anonymize_remove_client_ip
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
Overridable
Yes
yaml:
records
http
anonymize_remove_client_ip
When enabled (
), Traffic Server removes
Client-IP
headers for more privacy.
proxy.config.http.insert_client_ip
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
Overridable
Yes
yaml:
records
http
insert_client_ip
Specifies whether Traffic Server inserts
Client-IP
headers to retain the client IP address:
Value
Description
Don’t insert the
Client-ip
header
Insert the
Client-ip
header, but only if the UA did not send one
Always insert the
Client-ip
header
proxy.config.http.anonymize_other_header_list
Scope
CONFIG
Type
STRING
Default
NULL
Reloadable
Yes
yaml:
records
http
anonymize_other_header_list
null
Comma separated list of headers Traffic Server should remove from outgoing requests.
proxy.config.http.insert_squid_x_forwarded_for
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
Overridable
Yes
yaml:
records
http
insert_squid_x_forwarded_for
When enabled (
), Traffic Server adds the client IP address to the
X-Forwarded-For
header.
proxy.config.http.insert_forwarded
Scope
CONFIG
Type
STRING
Default
none
Reloadable
Yes
Overridable
Yes
yaml:
records
http
insert_forwarded
none
The default value (
none
) means that Traffic Server does not insert or append information to any
Forwarded
header (described in IETF RFC 7239) in the request message. To put information into a
Forwarded
header in the request, the value of this variable must be a list of the
Forwarded
parameters to be inserted.
Parameter
Value of parameter place in outgoing Forwarded header
for
Client IP address
by=ip
Proxy IP address
by=unknown
The literal string
unknown
by=servername
Proxy server name
by=uuid
Server UUID prefixed with
proto
Protocol of incoming request
host
The host specified in the incoming request
connection=compact
Connection with basic transaction codes.
connection=std
Connection with detailed transaction codes.
connection=full
Full user agent connection
protocol tags
Each parameter in the list must be separated by
or
. For example,
for|by=uuid|proto
is
a valid value for this variable. Note that the
connection
parameter is a non-standard extension to
RFC 7239. Also note that, while Traffic Server allows multiple
by
parameters for the same proxy, this
is prohibited by RFC 7239. Currently, for the
host
parameter to provide the original host from the
incoming client request,
proxy.config.url_remap.pristine_host_hdr
must be enabled.
proxy.config.http.proxy_protocol_allowlist
Scope
CONFIG
Type
STRING
Default
``````
yaml:
records
http
proxy_protocol_allowlist
'```list>```'
This defines a allowlist of server IPs that are trusted to provide
connections with Proxy Protocol information. This is a comma delimited list
of IP addresses. Addressed may be listed individually, in a range separated
by a dash or by using CIDR notation.
Example
Effect
10.0.2.123
A single IP Address.
10.0.3.1-10.0.3.254
A range of IP address.
10.0.4.0/24
A range of IP address specified by CIDR notation.
Important
If Proxy Protocol is enabled on the port, but this directive is not
defined any server may initiate a connection with Proxy Protocol
information.
See
proxy.config.http.server_ports
for information on how to enable Proxy Protocol on a port.
See
Proxy Protocol
for more discussion on how Traffic Server transforms the
Forwarded: header
proxy.config.http.proxy_protocol_out
Scope
CONFIG
Type
INT
Default
-1
Reloadable
Yes
Overridable
Yes
yaml:
records
http
proxy_protocol_out
-1
Set the behavior of outbound PROXY Protocol.
Value
Description
-1
Disable (default)
Forward received PROXY protocol to the next hop
Send client information in PROXY protocol version 1
Send client information in PROXY protocol version 2
proxy.config.http.normalize_ae
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
Overridable
Yes
yaml:
records
http
normalize_ae
Specifies normalization, if any, of
Accept-Encoding:
headers.
Value
Description
No normalization.
Accept-Encoding:
gzip
(if the header has
gzip
or
x-gzip
with any
OR
blank
(for any header that does not include
gzip
Accept-Encoding:
br
if the header has
br
(with any
ELSE
normalize as for value
Accept-Encoding:
br,
gzip
(if the header has
br
and
gzip
(with any
for either) then
br,
gzip
ELSE
normalize as for value
Accept-Encoding:
zstd
if the header has
zstd
(with any
ELSE
normalize as for value
Accept-Encoding:
zstd,
br,
gzip
(supports all combinations of
zstd
br
, and
gzip
ELSE
normalize as for value
This is useful for minimizing cached alternates of documents (e.g.
gzip,
deflate
vs.
deflate,
gzip
).
Enabling this option is recommended if your origin servers use no encodings other than
gzip
br
(Brotli), or
zstd
(Zstandard).
Security
proxy.config.http.push_method_enabled
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
yaml:
records
http
push_method_enabled
Enables (
) or disables (
) the HTTP
PUSH
option, which allows you to deliver content directly to the cache without a user
request.
Important
If you enable this option, then you must also specify
a filtering rule in the ip_allow.yaml file to allow only certain
machines to push content into the cache.
proxy.config.http.max_post_size
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
yaml:
records
http
max_post_size
This feature is disabled by default with a value of (
), any positive
value will limit the size of post bodies. If a request is received with a
post body larger than this limit the response will be terminated with
413 - Request Entity Too Large and logged accordingly.
proxy.config.http.allow_multi_range
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
Overridable
Yes
yaml:
records
http
allow_multi_range
This option allows the administrator to configure different behavior and
handling of requests with multiple ranges in the
Range
header.
Value
Description
Do not allow multiple ranges, effectively ignoring the
Range
header
Allows multiple ranges. This can be potentially dangerous since well
formed requests can cause excessive resource consumption on the server.
Similar to 0, except return a 416 error code and no response body.
proxy.config.http.host_sni_policy
Scope
CONFIG
Type
INT
Default
yaml:
records
http
host_sni_policy
This option controls how host header and SNI name mismatches are handled. Mismatches
may result in SNI-based policies defined in
sni.yaml
being avoided. For example,
foo.com
may be the fqdn value in
sni.yaml
which defines that client certificates are required.
The user could specify
bar.com
as the SNI to avoid the policy requiring the client certificate
but specify
foo.com
as the HTTP host header to still access the same object.
Therefore, if a host header would have triggered a SNI policy, it is possible that the user is
trying to bypass a SNI policy if the host header and SNI values do not match.
If this setting is 0, no checking is performed. If this setting is 1 or 2, the host header and SNI values
are compared if the host header value would have triggered a SNI policy. If there is a mismatch and the value
is 1, a warning is generated but the transaction is allowed to proceed. If the value is 2 and there is a
mismatch, a warning is generated and a status 403 is returned.
Note that SNI and hostname consistency checking is not performed on all connections indiscriminately, even if this
global
proxy.config.http.host_sni_policy
is set to a value of 1 or 2. It is only performed for connections to
hosts specifying
verify_client
and/or
ip_allow
policies in
sni.yaml
. That is, the SNI and hostname
mismatch check is only performed if a relevant security policy for the SNI is set in
sni.yaml
. The
proxy.config.http.host_sni_policy
records.yaml
value is used as the default value if either of these
policies is set in the corresponding
sni.yaml
file entry and the
sni.yaml
entry does not override
this value via a
host_sni_policy
attribute.
IP Allow
proxy.config.cache.ip_allow.filename
Scope
CONFIG
Type
STRING
Default
ip_allow.yaml
Reloadable
Yes
yaml:
records
cache
ip_allow
filename
ip_allow.yaml
Set the file path for the IP allow configuration file. For details of the use
of this file, see
ip_allow.yaml
. If this is a relative path, Traffic Server
loads it relative to the
SYSCONFDIR
directory.
proxy.config.cache.ip_categories.filename
Scope
CONFIG
Type
STRING
Default
NULL
Reloadable
Yes
yaml:
records
cache
ip_categories
filename
null
Set the file path for the IP allow categories definition file. For details of
the use of this file, see
ip_allow.yaml
. If this is a relative path,
Traffic Server loads it relative to the
SYSCONFDIR
directory.
proxy.config.acl.subjects
Scope
CONFIG
Type
STRING
Default
PEER
yaml:
records
acl
subjects
PEER
Specifies the list of data sources for getting client’s IP address for ACL.
The value is a comma separated string, and the first available data source
will be used. If you configure a port to enable PROXY protocol, you probably
need to adjust this setting to have
PROXY
in the list.
Value
Description
PEER
Use the IP address of the peer
PROXY
Use the IP address from PROXY protocol
PLUGIN
Use the IP address verified by a plugin
Cache Control
proxy.config.cache.enable_read_while_writer
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
yaml:
records
cache
enable_read_while_writer
Specifies when to enable the ability to read a cached object while another
connection is completing the write to cache for that same object. The goal
here is to avoid multiple origin connections for the same cacheable object
upon a cache miss. The possible values of this config are:
Value
Description
Never read while writing.
Always read while writing.
Always read while writing, but allow non-cached
Range
requests
through to the origin server.
The
option is useful to avoid delaying requests which can not easily
be satisfied by the partially written response.
Several other configuration values need to be set for this to be
usable. See
Reducing Origin Server Requests (Avoiding the Thundering Herd)
proxy.config.cache.read_while_writer.max_retries
Scope
CONFIG
Type
INT
Default
10
Reloadable
Yes
yaml:
records
cache
read_while_writer
max_retries
10
Specifies how many retries trafficserver attempts to trigger read_while_writer on failing
to obtain the write VC mutex or until the first fragment is downloaded for the
object being downloaded. The retry duration is specified using the setting
proxy.config.cache.read_while_writer_retry.delay
proxy.config.cache.read_while_writer_retry.delay
Scope
CONFIG
Type
INT
Default
50
Reloadable
Yes
yaml:
records
cache
read_while_writer_retry
delay
50
Specifies the delay in msec, trafficserver waits to reattempt read_while_writer
on failing to obtain the write VC mutex or until the first fragment is downloaded
for the object being downloaded. Note that trafficserver implements a progressive
delay in reattempting, by doubling the configured duration from the third reattempt
onwards.
proxy.config.cache.force_sector_size
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
yaml:
records
cache
force_sector_size
Forces the use of a specific hardware sector size, e.g. 4096, for all disks.
SSDs and “advanced format” drives claim a sector size of 512; however, it is safe to force a higher
size than the hardware supports natively as we count atomicity in 512 byte increments.
4096-sized drives formatted for Windows will have partitions aligned on 63 512-byte sector boundaries,
so they will be unaligned. There are workarounds, but you need to do some research on your particular
drive. Some drives have a one-time option to switch the partition boundary, while others might require
reformatting or repartitioning.
To be safe in Linux, you could just use the entire drive:
/dev/sdb
instead of
/dev/sdb1
and
Traffic Server will do the right thing. Misaligned partitions on Linux are auto-detected.
For example: If
/sys/block/sda/sda1/alignment_offset
is non-zero, ATS will offset reads/writes to
that disk by that alignment. If Linux knows about any existing partition misalignments, ATS will compensate.
Partitions formatted to support hardware sector size of more than 512 (e.g. 4096) will result in all
objects stored in the cache to be integral multiples of 4096 bytes, which will result in some waste for
small files.
proxy.config.http.cache.http
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
Overridable
Yes
yaml:
records
http
cache
http
Enables (
) or disables (
) caching of HTTP requests.
proxy.config.http.cache.post_method
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
Overridable
Yes
yaml:
records
http
cache
post_method
Enables (
) or disables (
) caching of HTTP POST requests.
proxy.config.http.cache.generation
Scope
CONFIG
Type
INT
Default
-1
Reloadable
Yes
Overridable
Yes
yaml:
records
http
cache
generation
-1
If set to a value other than
-1
, the value if this configuration
option is combined with the cache key at cache lookup time.
Changing this value has the effect of an instantaneous, zero-cost
cache purge since it will cause all subsequent cache keys to
change. Since this is an overridable configuration, it can be
used to purge the entire cache, or just a specific
remap.config
rule.
proxy.config.http.cache.ignore_query
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
Overridable
Yes
yaml:
records
http
cache
ignore_query
If this value is set to
, then the query string is ignored when
calculating the cach key for the request. This can be noticeably faster
than using e.g. the
cachekey
plugin to just remove the query parameters.
proxy.config.http.doc_in_cache_skip_dns
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
Overridable
Yes
yaml:
records
http
doc_in_cache_skip_dns
When enabled (
), do not perform origin server DNS resolution if a fresh
copy of the requested document is available in the cache. This setting has
no effect if HTTP caching is disabled or if there are IP based ACLs
configured.
Note that plugins, particularly authorization plugins, which use the
TS_HTTP_OS_DNS_HOOK
hook may require this configuration variable
to be disabled (
) in order to function properly. This will ensure that
the hook will be evaluated and plugin execution will occur even when there
is a fresh copy of the requested object in the cache (which would normally
allow the DNS lookup to be skipped, thus eliminating the hook evaluation).
The downside is that the performance gain by skipping otherwise unnecessary
DNS lookups is lost. Because the variable is overridable, you may retain
this performance benefit for portions of your cache which do not require the
use of
TS_HTTP_OS_DNS_HOOK
plugins, by ensuring that the setting
is first disabled within only the relevant transactions. Refer to the
documentation on
Configuration Remap Plugin
for more information.
proxy.config.http.cache.ignore_client_no_cache
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
Overridable
Yes
yaml:
records
http
cache
ignore_client_no_cache
When enabled (
), Traffic Server ignores client requests to bypass the cache. Specifically,
Pragma:
no-cache
Cache-Control:
no-cache
and
Cache-Control:
no-store
in requests are ignored.
proxy.config.http.cache.ims_on_client_no_cache
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
Overridable
Yes
yaml:
records
http
cache
ims_on_client_no_cache
When enabled (
), Traffic Server issues a conditional request to the origin server if an incoming request has a
No-Cache
header.
proxy.config.http.cache.ignore_server_no_cache
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
Overridable
Yes
yaml:
records
http
cache
ignore_server_no_cache
When enabled (
), Traffic Server ignores origin server requests to bypass the cache. Specifically,
Pragma:
no-cache
Cache-Control:
no-cache
and
Cache-Control:
no-store
in responses are ignored.
proxy.config.http.cache.cache_responses_to_cookies
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
Overridable
Yes
yaml:
records
http
cache
cache_responses_to_cookies
Specifies how cookies are cached:
Value
Description
Do not cache any responses to cookies.
Cache for any content-type.
Cache only for image types.
Cache for all but text content-types.
Cache for all but text content-types; except origin server response
without
Set-Cookie
or with
Cache-Control:
public
proxy.config.http.cache.ignore_authentication
Scope
CONFIG
Type
INT
Default
Overridable
Yes
yaml:
records
http
cache
ignore_authentication
When enabled (
), Traffic Server ignores
WWW-Authentication
headers in
responses and the responses are cached.
proxy.config.http.cache.cache_urls_that_look_dynamic
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
Overridable
Yes
yaml:
records
http
cache
cache_urls_that_look_dynamic
Enables (
) or disables (
) caching of URLs that look dynamic, i.e.: URLs that end in
.asp
or contain a question
mark (
), a semicolon (
), or
cgi
. For a full list, please refer to
HttpTransact::url_looks_dynamic
proxy.config.http.cache.when_to_revalidate
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
Overridable
Yes
yaml:
records
http
cache
when_to_revalidate
Specifies when to revalidate content:
Value
Description
Use cache directives or heuristic (the default value).
Stale if heuristic.
Always stale (always revalidate).
Never stale.
Use cache directives or heuristic (0) unless the request has an
If-Modified-Since
header.
If the request contains the
If-Modified-Since
header, then Traffic Server always
revalidates the cached content and uses the client’s
If-Modified-Since
header for the proxy request.
proxy.config.http.cache.required_headers
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
Overridable
Yes
yaml:
records
http
cache
required_headers
The type of headers required in a request for the request to be cacheable.
Value
Description
No headers required to make document cacheable.
Either the
Last-Modified
header, or an explicit lifetime header
Expires
or
Cache-Control:
max-age
) is required.
Explicit lifetime is required, from either
Expires
or
Cache-Control:
max-age
proxy.config.http.cache.targeted_cache_control_headers
Scope
CONFIG
Type
STRING
Default
“CDN-Cache-Control”
Reloadable
Yes
Overridable
Yes
yaml:
records
http
cache
targeted_cache_control_headers
'"CDN-Cache-Control"'
Comma-separated list of targeted cache control header names to check in
priority order before falling back to the standard
Cache-Control
header. This implements
RFC 9213
Targeted HTTP Cache Control. The default value is
CDN-Cache-Control
Set this to an empty string to disable targeted cache control and use only
the standard
Cache-Control
header.
Example values:
CDN-Cache-Control
- Use only CDN-Cache-Control if present
ATS-Cache-Control,CDN-Cache-Control
- Check ATS-Cache-Control first, then
CDN-Cache-Control, then fall back to Cache-Control
When a targeted header is found, its directives are used rather than those in the
standard
Cache-Control
header for caching decisions. The targeted headers are
passed through to downstream caches.
Note
This implementation uses the existing Cache-Control parser rather than the
strict RFC 8941 Structured Fields parser specified in RFC 9213.
proxy.config.http.cache.max_stale_age
Scope
CONFIG
Type
INT
Default
604800
Reloadable
Yes
Overridable
Yes
yaml:
records
http
cache
max_stale_age
604800
The maximum age in seconds allowed for a stale response before it cannot be cached.
proxy.config.http.cache.guaranteed_min_lifetime
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
Overridable
Yes
yaml:
records
http
cache
guaranteed_min_lifetime
Establishes a guaranteed minimum lifetime boundary for object freshness.
Setting this to
(default) disables the feature.
proxy.config.http.cache.guaranteed_max_lifetime
Scope
CONFIG
Type
INT
Default
31536000
Reloadable
Yes
Overridable
Yes
yaml:
records
http
cache
guaranteed_max_lifetime
31536000
Establishes a guaranteed maximum lifetime boundary for object freshness.
Setting this to
disables the feature.
proxy.config.http.cache.try_compat_key_read
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
yaml:
records
http
cache
try_compat_key_read
When enabled (
), Traffic Server will try to lookup the cached object using the
previous cache key generation algorithm, but will always write new objects
using the newest key generation. This might be temporarily necessary
if a large cache was created by the previous version of ATS but the new
version changed the way cache keys are generated. If this is turned on,
a metric called
proxy.process.http.cache.compat_key_reads
will be
incremented any time the compat cache lookup successfully finds the object.
You can monitor this metric and know when its safe to turn this feature off
as the cache wraps around.
proxy.config.http.cache.range.lookup
Scope
CONFIG
Type
INT
Default
Overridable
Yes
yaml:
records
http
cache
range
lookup
When enabled (
), Traffic Server looks up range requests in the cache.
proxy.config.http.cache.range.write
Scope
CONFIG
Type
INT
Default
Overridable
Yes
yaml:
records
http
cache
range
write
When enabled (
), Traffic Server will attempt to write (lock) the URL
to cache for a request specifying a range. This is useful when the origin server
might ignore a range request and respond with a full (
200
) response.
Additionally, this setting will attempt to transform a 200 response from the origin
server to a partial (
206
) response, honoring the requested range, while
caching the full response.
proxy.config.http.cache.ignore_accept_mismatch
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
Overridable
Yes
yaml:
records
http
cache
ignore_accept_mismatch
When enabled with a value of
, Traffic Server serves documents from cache with a
Content-Type:
header even if it does not match the
Accept:
header of the
request. If set to
(default), this logic only happens in the absence of a
Vary
header in the cached response (which is the recommended and safe use).
Note
This option should only be enabled with
if you’re having
problems with caching
and
you origin server doesn’t set the
Vary
header. Alternatively, if the origin is incorrectly setting
Vary:
Accept
or doesn’t respond with
406
(Not
Acceptable)
you can also enable this configuration with a
proxy.config.http.cache.ignore_accept_language_mismatch
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
Overridable
Yes
yaml:
records
http
cache
ignore_accept_language_mismatch
When enabled with a value of
, Traffic Server serves documents from cache with a
Content-Language:
header even if it does not match the
Accept-Language:
header of the request. If set to
(default), this logic only happens in the absence of a
Vary
header in the cached response (which is the recommended and safe use).
Note
This option should only be enabled with
if you’re having
problems with caching
and
you origin server doesn’t set the
Vary
header. Alternatively, if the origin is incorrectly setting
Vary:
Accept-Language
or doesn’t respond with
406
(Not
Acceptable)
you can also enable this configuration with a
proxy.config.http.cache.ignore_accept_encoding_mismatch
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
Overridable
Yes
yaml:
records
http
cache
ignore_accept_encoding_mismatch
When enabled with a value of
, Traffic Server serves documents from cache with a
Content-Encoding:
header even if it does not match the
Accept-Encoding:
header of the request. If set to
(default), this logic only happens in the absence of a
Vary
header in the cached response (which is the recommended and safe use).
Note
This option should only be enabled with
if you’re having
problems with caching
and
you origin server doesn’t set the
Vary
header. Alternatively, if the origin is incorrectly setting
Vary:
Accept-Encoding
or doesn’t respond with
406
(Not
Acceptable)
you can also enable this configuration with a
proxy.config.http.cache.ignore_accept_charset_mismatch
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
Overridable
Yes
yaml:
records
http
cache
ignore_accept_charset_mismatch
When enabled with a value of
, Traffic Server serves documents from cache with a
Content-Type:
header even if it does not match the
Accept-Charset:
header
of the request. If set to
(default), this logic only happens in the absence of a
Vary
header in the cached response (which is the recommended and safe use).
Note
This option should only be enabled with
if you’re having
problems with caching
and
you origin server doesn’t set the
Vary
header. Alternatively, if the origin is incorrectly setting
Vary:
Accept-Charset
or doesn’t respond with
406
(Not
Acceptable)
you can also enable this configuration with a
proxy.config.http.cache.ignore_client_cc_max_age
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
Overridable
Yes
yaml:
records
http
cache
ignore_client_cc_max_age
When enabled (
), Traffic Server ignores any
Cache-Control:
max-age
headers from the client. This technically violates the HTTP RFC,
but avoids a problem where a client can forcefully invalidate a cached object.
proxy.config.cache.max_doc_size
Scope
CONFIG
Type
INT
Default
yaml:
records
cache
max_doc_size
Specifies the maximum object size that will be cached.
is unlimited.
proxy.config.cache.min_average_object_size
Scope
CONFIG
Type
INT
Default
8000
yaml:
records
cache
min_average_object_size
8000
Specifies the lower boundary of average object sizes in the cache and is
used in determining the number of
directory buckets
to allocate for the in-memory cache directory.
proxy.config.cache.default_volumes
Scope
CONFIG
Type
STRING
Default
“”
yaml:
records
cache
default_volumes
'""'
Specifies a comma-separated list of cache volume numbers to use as the default
for cache stripe selection when no more specific volume configuration applies.
For example,
"1,2"
would use volumes 1 and 2 as the default.
The volume selection priority order is:
@volume=
directive in
remap.config
(highest priority)
Hostname matching in
hosting.config
proxy.config.cache.default_volumes
(if non-empty)
All available cache volumes (lowest priority)
An empty string (the default) disables this feature, causing Traffic Server to fall
back directly to using all available volumes when no other configuration
matches.
This is useful for scenarios where you want to restrict default caching to
specific volumes without configuring hostname patterns in
hosting.config
For example, you might want to reserve certain volumes for specific remap rules
while having a different set of default volumes for all other traffic.
Example
Assign volumes 1 and 2 as defaults for general traffic
CONFIG
proxy
config
cache
default_volumes
STRING
"1,2"
proxy.config.cache.permit.pinning
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
yaml:
records
cache
permit
pinning
When enabled (
), Traffic Server will keep certain HTTP objects in the cache for a certain time as specified in cache.config.
proxy.config.cache.hit_evacuate_percent
Scope
CONFIG
Type
INT
Default
yaml:
records
cache
hit_evacuate_percent
The size of the region (as a percentage of the total content storage in a
cache stripe
) in front of the
write cursor
that constitutes a recent access hit for evacuating the accessed object.
When an object is accessed it can be marked for evacuation, that is to be copied over the write cursor and
thereby preserved from being overwritten. This is done if it is no more than a specific number of bytes in front of
the write cursor. The number of bytes is a percentage of the total number of bytes of content storage in the cache
stripe where the object is stored and that percentage is set by this variable.
By default, the feature is off (set to 0).
proxy.config.cache.hit_evacuate_size_limit
Scope
CONFIG
Type
INT
Default
Units
bytes
yaml:
records
cache
hit_evacuate_size_limit
Limit the size of objects that are hit evacuated.
Objects larger than the limit are not hit evacuated. A value of 0 disables the limit.
proxy.config.cache.dir.sync_frequency
Scope
CONFIG
Type
INT
Default
60
Units
seconds
yaml:
records
cache
dir
sync_frequency
60
How often we will sync the cache directory entries to disk. Note that this is
a minimum time, and the actual sync may be delayed if the disks are larger than
how fast we allow it to write to disk (see next options).
proxy.config.cache.dir.sync_max_writes
Scope
CONFIG
Type
INT
Default
2097152
Units
bytes
yaml:
records
cache
dir
sync_max_writes
2097152
How much of a stripes cache directory we will write to disk in each write cycle.
Together with the sync_delay, this controls how fast we can sync the entire directory
structure to disk. The default is 2MB.
proxy.config.cache.dir.sync_delay
Scope
CONFIG
Type
INT
Default
500
Units
millisecond
yaml:
records
cache
dir
sync_delay
500
How long to wait between each write cycle when syncing the cache directory to disk.
proxy.config.cache.dir.sync_parallel_tasks
Scope
CONFIG
Type
INT
Default
yaml:
records
cache
dir
sync_parallel_tasks
Number of parallel tasks to use for directory syncing. Each task syncs
directories for a different physical drive on ET_TASK threads.
Value
Description
-1
Unlimited - one task per drive (maximum parallelism)
Sequential - one task for all drives (default, safe)
Parallel - up to N tasks (drives) sync concurrently
Default is
(sequential). Set to
-1
for maximum parallelism on
high-end NVMe arrays, or to
4-8
for balanced performance on multi-drive
systems.
proxy.config.cache.limits.http.max_alts
Scope
CONFIG
Type
INT
Default
yaml:
records
cache
limits
http
max_alts
The maximum number of alternates that are allowed for any given URL.
Disable by setting to 0.
proxy.config.cache.log.alternate.eviction
Scope
CONFIG
Type
INT
Default
yaml:
records
cache
log
alternate
eviction
When enabled (
), Traffic Server will emit a Status level log entry every time an
alternate for an object is evicted due to the number of its alternates
exceeding the value of
proxy.config.cache.limits.http.max_alts
. The
URI for the evicted alternate is included in the log. This logging may be
useful to determine whether
proxy.config.cache.limits.http.max_alts
is tuned correctly for a given environment. It also provides visibility into
alternate eviction for individual objects, which can be helpful for
diagnosing unexpected
Vary:
header behavior from particular origins.
For further details concerning the caching of alternates, see
Caching
HTTP Alternates
By default, alternate eviction logging is disabled (set to
).
proxy.config.cache.target_fragment_size
Scope
CONFIG
Type
INT
Default
1048576
yaml:
records
cache
target_fragment_size
1048576
Sets the target size of a contiguous fragment of a file in the disk cache.
When setting this, consider that larger numbers could waste memory on slow
connections, but smaller numbers could increase (waste) seeks.
proxy.config.cache.alt_rewrite_max_size
Scope
CONFIG
Type
INT
Default
4096
Reloadable
Yes
yaml:
records
cache
alt_rewrite_max_size
4096
Configures the size, in bytes, of an alternate that will be considered
small enough to trigger a rewrite of the resident alt fragment within a
write vector. For further details on cache write vectors, refer to the
developer documentation for
CacheVC
proxy.config.cache.mutex_retry_delay
Scope
CONFIG
Type
INT
Default
Units
milliseconds
Reloadable
Yes
yaml:
records
cache
mutex_retry_delay
The retry delay for missing a lock on a mutex in the cache component. This is used generically
for most locks, except those that have an explicit configuration for the retry delay. For
instance, if the cache component is notifying another continuation of a cache event and fails to
get the lock for that continuation, it will use this as the delay for the retry. This is also
used from the asynchronous IO threads when IO finishes and the
CacheVC
lock or stripe lock is
required.
proxy.config.cache.max_disk_errors
Scope
CONFIG
Type
INT
Default
yaml:
records
cache
max_disk_errors
Cache disks sometimes fail due to hardware problems. Traffic Server keeps count of
the number of times it encounters I/O errors when accessing each cache disk.
If the number of errors on a disk reaches this setting, Traffic Server removes that
disk from the cache.
Note that the count of errors is kept in memory, and is reset to zero when
Traffic Server is restarted. By default, Traffic Server will not remember which cache disk has
been removed in this way when it restarts. If you wish to change this behavior
and prevent known bad disks from re-joining the cache upon restart, change
the setting
proxy.config.cache.persist_bad_disks
proxy.config.cache.persist_bad_disks
Scope
CONFIG
Type
INT
Default
yaml:
records
cache
persist_bad_disks
When enabled (
), Traffic Server will remember which cache disks have been
marked as failed through
proxy.config.cache.max_disk_errors
even after a restart. A list of known bad cache disks is written to
localstatedir/known_bad_disks.txt
. If you replace the known bad disks,
delete this file so that Traffic Server will use them in the cache again.
When disabled (
), Traffic Server will ignore
known_bad_disks.txt
This feature is disabled by default.
RAM Cache
proxy.config.cache.ram_cache.size
Scope
CONFIG
Type
INT
Default
-1
yaml:
records
cache
ram_cache
size
-1
By default the RAM cache size is automatically determined, based on
disk cache size; approximately 10 MB of RAM cache per GB of disk cache.
Alternatively, it can be set to a fixed value such as
20GB
(21474836480)
This global setting can be overridden on a per-volume basis using the
ram_cache_size
parameter in
volume.config
. Per-volume
allocations are subtracted from the total RAM cache size before
distributing the remainder among volumes without explicit settings.
proxy.config.cache.ram_cache_cutoff
Scope
CONFIG
Type
INT
Default
4194304
yaml:
records
cache
ram_cache_cutoff
4194304
Objects greater than this size will not be kept in the RAM cache.
This should be set high enough to keep objects accessed frequently
in memory in order to improve performance.
4MB
(4194304)
This global setting can be overridden on a per-volume basis using the
ram_cache_cutoff
parameter in
volume.config
. When set,
the per-volume cutoff takes precedence over this global setting for
that specific volume.
proxy.config.cache.ram_cache.algorithm
Scope
CONFIG
Type
INT
Default
yaml:
records
cache
ram_cache
algorithm
Two distinct RAM caches are supported, the default (1) being the simpler
LRU
Least Recently Used
) cache. As an alternative, the
CLFUS
Clocked Least Frequently Used by Size
) is also available, by changing this
configuration to 0.
proxy.config.cache.ram_cache.use_seen_filter
Scope
CONFIG
Type
INT
Default
yaml:
records
cache
ram_cache
use_seen_filter
Enabling this option will filter inserts into the RAM cache to ensure that
they have been seen at least once. For the
LRU
, this provides scan
resistance.
As of ATS v10.0.0 and later, this setting can take values in the range
to
. Values above
will only enable the seen filter after a certain
threshold of RAM cache usage has been reached. The threshold is determined by
the value of this setting, with
being 50% filled,
being 67% filled,
and so on.
Note that
CLFUS
already requires that a document have history
before it is inserted, so for
CLFUS
, setting this option means that a
document must be seen three times before it is added to the RAM cache.
proxy.config.cache.ram_cache.compress
Scope
CONFIG
Type
INT
Default
yaml:
records
cache
ram_cache
compress
The
CLFUS
RAM cache also supports an optional in-memory compression.
This is not to be confused with
Content-Encoding:
gzip
compression.
The RAM cache compression is intended to try to save space in the RAM,
and is not visible to the User-Agent (client).
Possible values are:
Value
Description
No compression
Fastlz (extremely fast, relatively low compression)
Libz (moderate speed, reasonable compression)
Liblzma (very slow, high compression)
Compression runs on task threads. To use more cores for RAM cache
compression, increase
proxy.config.task_threads
Heuristic Expiration
proxy.config.http.cache.heuristic_min_lifetime
Scope
CONFIG
Type
INT
Default
3600
Reloadable
Yes
Overridable
Yes
yaml:
records
http
cache
heuristic_min_lifetime
3600
The minimum amount of time, in seconds, an HTTP object without an expiration
date can remain fresh in the cache before is considered to be stale.
proxy.config.http.cache.heuristic_max_lifetime
Scope
CONFIG
Type
INT
Default
86400
Reloadable
Yes
Overridable
Yes
yaml:
records
http
cache
heuristic_max_lifetime
86400
The maximum amount of time, in seconds, an HTTP object without an expiration
date can remain fresh in the cache before is considered to be stale.
proxy.config.http.cache.heuristic_lm_factor
Scope
CONFIG
Type
FLOAT
Default
0.10
Reloadable
Yes
Overridable
Yes
yaml:
records
http
cache
heuristic_lm_factor
0.1
The aging factor for freshness computations. Traffic Server stores an object for this
percentage of the time that elapsed since it last changed.
Dynamic Content & Content Negotiation
proxy.config.http.cache.open_read_retry_time
Scope
CONFIG
Type
INT
Default
10
Reloadable
Yes
Overridable
Yes
yaml:
records
http
cache
open_read_retry_time
10
The number of milliseconds a cacheable request will wait before requesting the object from cache if an equivalent request is in flight.
proxy.config.http.cache.max_open_read_retries
Scope
CONFIG
Type
INT
Default
-1
Reloadable
Yes
Overridable
Yes
yaml:
records
http
cache
max_open_read_retries
-1
The number of times to attempt fetching an object from cache if there was an equivalent request in flight.
proxy.config.http.cache.max_open_write_retries
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
Overridable
Yes
yaml:
records
http
cache
max_open_write_retries
The number of times to attempt a cache open write upon failure to get a write lock.
This config is ignored when
proxy.config.http.cache.open_write_fail_action
is
set to
or
, or when
proxy.config.http.cache.max_open_write_retry_timeout
is set to gt
proxy.config.http.cache.max_open_write_retry_timeout
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
Overridable
Yes
yaml:
records
http
cache
max_open_write_retry_timeout
A timeout for attempting a cache open write upon failure to get a write lock.
This config is ignored when
proxy.config.http.cache.open_write_fail_action
is
set to
or
proxy.config.http.cache.open_write_fail_action
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
Overridable
Yes
yaml:
records
http
cache
open_write_fail_action
This setting indicates the action taken on failing to obtain the cache open write lock on either a cache miss or a cache
hit stale. This typically happens when there is more than one request to the same cache object simultaneously. During such
a scenario, all but one (which goes to the origin) request is served either a stale copy or an error depending on this
setting.
Value
Description
Default. Disable cache and go to origin server.
Return a
502
error on a cache miss.
Serve stale if object’s age is under
max-age
proxy.config.http.cache.max_stale_age
. Otherwise, go to
origin server.
Return a
502
error on a cache miss or serve stale on a cache
revalidate if object’s age is under
max-age
proxy.config.http.cache.max_stale_age
. Otherwise, go to
origin server.
Return a
502
error on either a cache miss or on a revalidation.
Retry Cache Read on a Cache Write Lock failure. This option together
with
proxy.config.cache.enable_read_while_writer
configuration
allows to collapse concurrent requests without a need for any plugin.
Make sure to configure the
Read While Writer
feature
correctly. With this option, CACHE_LOOKUP_COMPLETE HOOK is deferred for
read retries so that plugins see only the final cache lookup result.
Retry Cache Read on a Cache Write Lock failure (same as
), but if
read retries are exhausted and a stale cached object exists, serve the
stale content if allowed. This combines the request collapsing behavior
of
with the stale-serving fallback of
. If stale is not
returnable (e.g., due to
Cache-Control:
must-revalidate
), go to
origin server.
Customizable User Response Pages
proxy.config.body_factory.enable_customizations
Scope
CONFIG
Type
INT
Default
yaml:
records
body_factory
enable_customizations
Specifies whether customizable response pages are language specific
or not:
Value
Description
Enable customizable user response pages in the default directory only.
Enable language-targeted user response pages.
Enable host-targeted user response pages.
proxy.config.body_factory.enable_logging
Scope
CONFIG
Type
INT
Default
yaml:
records
body_factory
enable_logging
Enables (
) or disables (
) logging for customizable response pages. When enabled, Traffic Server records a message in
the error log each time a customized response page is used or modified.
proxy.config.body_factory.template_sets_dir
Scope
CONFIG
Type
STRING
Default
etc/trafficserver/body_factory
yaml:
records
body_factory
template_sets_dir
etc/trafficserver/body_factory
The customizable response page default directory. If this is a
relative path, Traffic Server resolves it relative to the
PREFIX
directory.
proxy.config.body_factory.template_base
Scope
CONFIG
Type
STRING
Default
“”
Reloadable
Yes
Overridable
Yes
yaml:
records
body_factory
template_base
'""'
A prefix for the file name to use to find an error template file. If set (not the empty string)
this value and an underscore are prepended to the file name to find in the template sets
directory. See
HTML Messages Sent to Clients
proxy.config.body_factory.response_max_size
Scope
CONFIG
Type
INT
Default
8192
Reloadable
Yes
yaml:
records
body_factory
response_max_size
8192
Maximum size of the error template response page.
proxy.config.body_factory.response_suppression_mode
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
Overridable
Yes
yaml:
records
body_factory
response_suppression_mode
Specifies when Traffic Server suppresses generated response pages:
Value
Description
Never suppress generated response pages.
Always suppress generated response pages.
Suppress response pages only for internal traffic.
DNS
proxy.config.dns.search_default_domains
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
yaml:
records
dns
search_default_domains
Traffic Server can attempt to resolve unqualified hostnames by expanding to the local
domain. For example if a client makes a request to an unqualified host (e.g.
host_x
) and the Traffic Server local domain is
y.com
, then Traffic Server will expand
the hostname to
host_x.y.com
Value
Description
Disable local domain expansion.
Enable local domain expansion.
Enable local domain expansion, but do not split local domain name.
proxy.config.dns.splitDNS.enabled
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
yaml:
records
dns
splitDNS
enabled
Enables (
) or disables (
) DNS server selection. When enabled, Traffic Server refers to the
splitdns.config
file for
the selection specification. Refer to
Configuring DNS Server Selection
proxy.config.dns.resolv_conf
Scope
CONFIG
Type
STRING
Default
/etc/resolv.conf
yaml:
records
dns
resolv_conf
/etc/resolv.conf
Allows one to specify which
resolv.conf
file to use for finding resolvers. While the format of this file must be the same as the
standard
resolv.conf
file, this option allows an administrator to manage the set of resolvers in an external configuration file,
without affecting how the rest of the operating system uses DNS. Note that this setting works in conjunction with
proxy.config.dns.nameservers
, with its settings appended to the
resolv.conf
contents.
proxy.config.dns.round_robin_nameservers
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
yaml:
records
dns
round_robin_nameservers
Enables (
) or disables (
) DNS server round-robin.
proxy.config.dns.nameservers
Scope
CONFIG
Type
STRING
Default
NULL
Reloadable
Yes
yaml:
records
dns
nameservers
null
The DNS servers. Note that this does not override
proxy.config.dns.resolv_conf
That is, the contents of the file listed in
proxy.config.dns.resolv_conf
will
be appended to the list of nameservers specified here. To prevent this, a bogus file
can be listed there.
Example
IPv4 DNS server, loopback and port 9999
CONFIG
proxy
config
dns
nameservers
STRING
127.0.0.1
9999
Example
IPv6 DNS server, loopback and port 9999
CONFIG
proxy
config
dns
nameservers
STRING
[::
]:
9999
proxy.config.srv_enabled
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
Overridable
Yes
yaml:
records
srv_enabled
Enables (
) or disables (
) the use of SRV records for origin server
lookup. Traffic Server will use weights found in the SRV record as a weighted round
robin in origin selection. Note that Traffic Server will lookup
_$scheme._$internet_protocol.$origin_name
. For instance, if the origin is
set to
, Traffic Server 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).
proxy.config.dns.dedicated_thread
Scope
CONFIG
Type
INT
Default
yaml:
records
dns
dedicated_thread
Create and dedicate a thread entirely for DNS processing. This is probably
most useful on system which do a significant number of DNS lookups,
typically forward proxies. But even on other systems, it can avoid some
contention on the first worker thread (which otherwise takes on the burden of
all DNS lookups).
proxy.config.dns.validate_query_name
Scope
CONFIG
Type
INT
Default
yaml:
records
dns
validate_query_name
When enabled (1) provides additional resilience against DNS forgery (for instance
in DNS Injection attacks), particularly in forward or transparent proxies, but
requires that the resolver populates the queries section of the response properly.
proxy.config.dns.connection_mode
Scope
CONFIG
Type
INT
Default
yaml:
records
dns
connection_mode
Three connection modes between Traffic Server and nameservers can be set – UDP_ONLY,
TCP_RETRY, TCP_ONLY.
Value
Description
UDP_ONLY: Traffic Server always talks to nameservers over UDP.
TCP_RETRY: Traffic Server first UDP, retries with TCP if UDP response is truncated.
TCP_ONLY: Traffic Server always talks to nameservers over TCP.
proxy.config.dns.max_tcp_continuous_failures
Scope
CONFIG
Type
INT
Default
10
yaml:
records
dns
max_tcp_continuous_failures
10
If DNS connection mode is TCP_RETRY, set the threshold of the continuous TCP
query failures count for the TCP connection, reset the TCP connection immediately
if the continuous TCP query failures conut over the threshold. If the threshold
is 0 (or less than 0) we close this feature.
proxy.config.dns.max_dns_in_flight
Scope
CONFIG
Type
INT
Default
2048
yaml:
records
dns
max_dns_in_flight
2048
Maximum inflight DNS queries made by Traffic Server at any given instant
proxy.config.dns.lookup_timeout
Scope
CONFIG
Type
INT
Default
20
yaml:
records
dns
lookup_timeout
20
Time to wait for a DNS response in seconds.
proxy.config.dns.retries
Scope
CONFIG
Type
INT
Default
yaml:
records
dns
retries
Maximum number of retries made by Traffic Server on a given DNS query
proxy.config.dns.local_ipv4
Scope
CONFIG
Type
STRING
Default
NULL
yaml:
records
dns
local_ipv4
null
Local IPV4 address to bind to in order to make DNS requests
proxy.config.dns.local_ipv6
Scope
CONFIG
Type
STRING
Default
NULL
yaml:
records
dns
local_ipv6
null
Local IPV6 address to bind to in order to make DNS requests
HostDB
proxy.config.hostdb.lookup_timeout
Scope
CONFIG
Type
INT
Default
30
Units
seconds
Reloadable
Yes
yaml:
records
hostdb
lookup_timeout
30
Time to wait for a DNS response in seconds.
See
Timeout Settings
for more discussion on Traffic Server timeouts.
proxy.config.hostdb.serve_stale_for
Scope
CONFIG
Type
INT
Default
*NONE*
Units
seconds
Reloadable
Yes
yaml:
records
hostdb
serve_stale_for
null
The number of seconds for which to use a stale NS record while initiating a
background fetch for the new data.
If not set then stale records are not served.
proxy.config.hostdb.max_size
Scope
CONFIG
Type
INT
Default
10737418240
Units
bytes
yaml:
records
hostdb
max_size
10737418240
The maximum amount of space (in bytes) allocated to
hostdb
Setting this value to
-1
will disable size limit enforcement.
proxy.config.hostdb.max_count
Scope
CONFIG
Type
INT
Default
-1
yaml:
records
hostdb
max_count
-1
The maximum number of entries that can be stored in hostdb. A value of
-1
disables item count limit enforcement.
Note
For values above
200000
, you must increase
proxy.config.hostdb.max_size
by at least 44 bytes per entry.
proxy.config.hostdb.round_robin_max_count
Scope
CONFIG
Type
INT
Default
16
yaml:
records
hostdb
round_robin_max_count
16
The maximum count of DNS answers per round robin hostdb record. The default variable is 16.
proxy.config.hostdb.ttl_mode
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
yaml:
records
hostdb
ttl_mode
A host entry will eventually time out and be discarded. This variable
controls how that time is calculated. A DNS request will return a TTL value
and an internal value can be set with
proxy.config.hostdb.timeout
This variable determines which value will be used.
Value
TTL
The TTL from the DNS response.
The internal timeout value.
The smaller of the DNS and internal TTL values. The internal timeout
value becomes a maximum TTL.
The larger of the DNS and internal TTL values. The internal timeout
value become a minimum TTL.
proxy.config.hostdb.timeout
Scope
CONFIG
Type
INT
Default
86400
Units
seconds
Reloadable
Yes
yaml:
records
hostdb
timeout
86400
Internal time to live value for host DB entries in seconds.
See
proxy.config.hostdb.ttl_mode
for when this value
is used. See
Timeout Settings
for more discussion
on Traffic Server timeouts.
proxy.config.hostdb.fail.timeout
Scope
CONFIG
Type
INT
Default
yaml:
records
hostdb
fail
timeout
Time to live value for “failed” hostdb lookups.
Note
HostDB considers any response that does not contain a response to
the query a failure. This means “failure” responses (such as SOA) are
subject to this timeout
proxy.config.hostdb.strict_round_robin
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
yaml:
records
hostdb
strict_round_robin
Set host resolution to use strict round robin.
When this and
proxy.config.hostdb.timed_round_robin
are both
disabled (set to
), Traffic Server always uses the same origin server for the
same client, for as long as the origin server is available. Otherwise if
this is set then IP address is rotated on every request. This setting takes
precedence over
proxy.config.hostdb.timed_round_robin
proxy.config.hostdb.timed_round_robin
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
yaml:
records
hostdb
timed_round_robin
Set host resolution to use timed round robin.
When this and
proxy.config.hostdb.strict_round_robin
are both
disabled (set to
), Traffic Server always uses the same origin server for the
same client, for as long as the origin server is available. Otherwise if
this is set to
the IP address is rotated if more than
seconds have
passed since the first time the current address was used.
proxy.config.hostdb.host_file.path
Scope
CONFIG
Type
STRING
Default
NULL
yaml:
records
hostdb
host_file
path
null
Set the file path for an external host file.
If this is set (non-empty) then the file is presumed to be a hosts file in
the standard .
It is read and the entries there added to the HostDB. The file is
periodically checked for a more recent modification date in which case it is
reloaded. The interval is set with
proxy.config.hostdb.host_file.interval
While not technically reloadable, the value is read every time the file is
to be checked so that if changed the new value will be used on the next
check and the file will be treated as modified.
proxy.config.hostdb.host_file.interval
Scope
CONFIG
Type
INT
Default
86400
Units
seconds
Reloadable
Yes
yaml:
records
hostdb
host_file
interval
86400
Set the file changed check timer for
proxy.config.hostdb.host_file.path
The file is checked every this many seconds to see if it has changed. If so
the HostDB is updated with the new values in the file.
proxy.config.hostdb.partitions
Scope
CONFIG
Type
INT
Default
64
yaml:
records
hostdb
partitions
64
The number of partitions for hostdb. If you are seeing lock contention within
hostdb’s cache (due to a large number of records) you can increase the number
of partitions
proxy.config.hostdb.ip_resolve
Scope
CONFIG
Type
STRING
Default
NULL
Overridable
Yes
yaml:
records
hostdb
ip_resolve
null
Set the host resolution style.
This is an ordered list of keywords separated by semicolons that specify how
a host name is to be resolved to an IP address. The keywords are case
insensitive.
Keyword
Description
ipv4
Resolve to an IPv4 address.
ipv6
Resolve to an IPv6 address.
client
Resolve to the same family as the client IP address.
only
Stop resolving.
The order of the keywords is critical. When a host name needs to be resolved
it is resolved in same order as the keywords. If a resolution fails, the
next option in the list is tried. The keyword
only
means to give up
resolution entirely. The keyword list has a maximum length of three
keywords, more are never needed. By default there is an implicit
ipv4;ipv6
attached to the end of the string unless the keyword
only
appears.
Example
Use the incoming client family, then try IPv4 and IPv6.
client
ipv4
ipv6
Because of the implicit resolution this can also be expressed as just
client
Example
Resolve only to IPv4.
ipv4
only
Example
Resolve only to the same family as the client (do not permit cross family transactions).
client
only
This value is a global default that can be overridden by
proxy.config.http.server_ports
Note
This style is used as a convenience for the administrator. During a resolution the
resolution order
will be
one family, then possibly the other. This is determined by changing
client
to
ipv4
or
ipv6
based on the
client IP address and then removing duplicates.
Important
This option has no effect on outbound transparent connections The local IP address used in the connection to the
origin server is determined by the client, which forces the IP address family of the address used for the origin
server. In effect, outbound transparent connections always use a resolution style of “
client
”.
proxy.config.hostdb.verify_after
Scope
CONFIG
Type
INT
Default
720
yaml:
records
hostdb
verify_after
720
Set the interval (in seconds) in which to re-query DNS regardless of TTL status.
Logging Configuration
proxy.config.log.logging_enabled
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
yaml:
records
log
logging_enabled
Enables and disables event logging:
Value
Effect
Logging disabled.
Log errors only.
Log transactions only.
Dual logging (errors and transactions).
Refer to
Logging
for more information on event logging.
proxy.config.log.log_fast_buffer
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
yaml:
records
log
log_fast_buffer
Enables
fast
logging mode as the default for all log objects. This mode
can log larger transaction rates, but log entries will appear out of order
in the log output. You can enable
fast
mode for individual log objects in
logging.yaml
file by adding
fast:
true
to that object’s config.
proxy.config.log.max_secs_per_buffer
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
yaml:
records
log
max_secs_per_buffer
The maximum amount of time before data in the buffer is flushed to disk.
Note
The effective lower bound to this config is whatever
proxy.config.log.periodic_tasks_interval
is set to.
proxy.config.log.max_space_mb_for_logs
Scope
CONFIG
Type
INT
Default
25000
Units
megabytes
Reloadable
Yes
yaml:
records
log
max_space_mb_for_logs
25000
The amount of space allocated to the logging directory (in MB).
The headroom amount specified by
proxy.config.log.max_space_mb_headroom
is taken from
this space allocation.
Note
All files in the logging directory contribute to the space used,
even if they are not log files.
proxy.config.log.max_space_mb_headroom
Scope
CONFIG
Type
INT
Default
1000
Units
megabytes
Reloadable
Yes
yaml:
records
log
max_space_mb_headroom
1000
The tolerance for the log space limit (in megabytes). If the variable
proxy.config.log.auto_delete_rolled_files
is set to
(enabled), then auto-deletion of log files is triggered when the amount of free space available in the logging directory is less than
the value specified here.
proxy.config.log.hostname
Scope
CONFIG
Type
STRING
Default
localhost
Reloadable
Yes
yaml:
records
log
hostname
localhost
The hostname of the machine running Traffic Server.
proxy.config.log.logfile_dir
Scope
CONFIG
Type
STRING
Default
var/log/trafficserver
Reloadable
Yes
yaml:
records
log
logfile_dir
var/log/trafficserver
The path to the logging directory. This can be an absolute path
or a path relative to the
PREFIX
directory in which Traffic
Server is installed.
Note
The directory you specify must already exist.
proxy.config.log.logfile_perm
Scope
CONFIG
Type
STRING
Default
rw-r–r–
Reloadable
Yes
yaml:
records
log
logfile_perm
rw-r--r--
The log file permissions. The standard UNIX file permissions are used (owner, group, other). Permissible values are:
Value
Description
No permissions.
Read permission.
Write permission.
Execute permission.
Permissions are subject to the umask settings for the Traffic Server process. This
means that a umask setting of
002
will not allow write permission for
others, even if specified in the configuration file. Permissions for
existing log files are not changed when the configuration is modified.
proxy.config.log.rolling_enabled
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
yaml:
records
log
rolling_enabled
Specifies how log files are rolled. You can specify the following values:
Value
Description
Disables log file rolling.
Enables log file rolling at specific intervals during the day
(specified with the
proxy.config.log.rolling_interval_sec
and
proxy.config.log.rolling_offset_hr
variables).
Enables log file rolling when log files reach a specific size
(specified with
proxy.config.log.rolling_size_mb
).
Enables log file rolling at specific intervals during the day or when
log files reach a specific size (whichever occurs first).
Enables log file rolling at specific intervals during the day when log
files reach a specific size (i.e. at a specified time if the file is
of the specified size).
proxy.config.log.rolling_interval_sec
Scope
CONFIG
Type
INT
Default
86400
Reloadable
Yes
yaml:
records
log
rolling_interval_sec
86400
The log file rolling interval, in seconds. The minimum value is
60
(1 minute). The maximum, and default, value is 86400 seconds (one day).
Note
If you start Traffic Server within a few minutes of the next rolling time, then rolling might not occur until the next rolling time.
proxy.config.log.rolling_offset_hr
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
yaml:
records
log
rolling_offset_hr
The file rolling offset hour. The hour of the day that starts the log rolling period.
proxy.config.log.rolling_size_mb
Scope
CONFIG
Type
INT
Default
10
Reloadable
Yes
yaml:
records
log
rolling_size_mb
10
The size, in megabytes, that log files must reach before rolling takes place.
The minimum value for this setting is
10
proxy.config.log.rolling_min_count
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
yaml:
records
log
rolling_min_count
Specifies the minimum count of rolled (event) logs to keep. This value will be used to decide the
order of auto-deletion (if enabled). A default value of 0 means auto-deletion will try to keep
logs as much as possible. This value can be and should be overridden in logging.yaml. See
Log Rotation and Retention
for guidance.
proxy.config.log.rolling_max_count
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
yaml:
records
log
rolling_max_count
Specifies the maximum count of rolled output logs to keep. This value will be used by the
auto-deletion (if enabled) to trim the number of rolled log files every time the log is rolled.
A default value of 0 means auto-deletion will not try to limit the number of output logs.
See
Log Rotation and Retention
for an use-case for this option.
proxy.config.log.rolling_allow_empty
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
yaml:
records
log
rolling_allow_empty
While rolling default behavior is to rename, close and re-open the log file
only
when/if there is
something to log to the log file. This option opens a new log file right after rolling even if there
is nothing to log (i.e. nothing to be logged due to lack of requests to the server)
which may lead to 0-sized log files while rolling. See
Log Rotation and Retention
for an use-case
for this option.
Value
Description
No empty log files created and rolled if there was nothing to log
Allow empty log files to be created and rolled even if there was nothing to log
proxy.config.log.auto_delete_rolled_files
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
yaml:
records
log
auto_delete_rolled_files
Enables (
) or disables (
) automatic deletion of rolled files.
proxy.config.log.sampling_frequency
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
yaml:
records
log
sampling_frequency
Configures Traffic Server to log only a sample of transactions rather than every
transaction. You can specify the following values:
Value
Description
Log every transaction.
Log every second transaction.
Log every third transaction.
… and so on…
proxy.config.log.periodic_tasks_interval
Scope
CONFIG
Type
INT
Default
Units
seconds
Reloadable
Yes
yaml:
records
log
periodic_tasks_interval
How often Traffic Server executes log related periodic tasks, in seconds
proxy.config.log.proxy.config.log.throttling_interval_msec
Scope
CONFIG
Type
INT
Default
60000
Units
milliseconds
Reloadable
Yes
yaml:
records
log
proxy
config
log
throttling_interval_msec
60000
The minimum amount of milliseconds between repeated throttled Traffic Server log
events. A value of 0 implies no throttling. Note that for performance
reasons only certain logs are compiled with throttling applied to them.
Throttling is applied to all log events for a particular message which is
emitted within its throttling interval. That is, once a throttled log is
emitted, none will be emitted until the next log event for that message
which occurs outside of this configured interval. As mentioned above, this
message is applied not broadly but rather to potentially noisy log messages,
such as ones that might occur thousands of times a second under certain
error conditions. Once the next log event occurs outside of its interval, a
summary message is printed conveying how many messages of that type were
throttled since the last time it was emitted.
It is possible that a log is emitted, followed by more of its type in an
interval, then none are emitted after that. Be aware this would result in no
summary log message for that interval until the message is emitted again
outside of the throttled interval.
proxy.config.http.slow.log.threshold
Scope
CONFIG
Type
INT
Default
Units
milliseconds
Reloadable
Yes
yaml:
records
http
slow
log
threshold
If set to a non-zero value
then any connection that takes longer than
milliseconds from accept to
completion will cause its timing stats to be written to the
debugging
log
file
. This is identifying data about the transaction and all of the
transaction
milestones
proxy.config.http2.connection.slow.log.threshold
Scope
CONFIG
Type
INT
Default
Units
milliseconds
Reloadable
Yes
yaml:
records
http2
connection
slow
log
threshold
If set to a non-zero value
then any HTTP/2 connection
that takes longer than
milliseconds from open to close will cause
its timing stats to be written to the
debugging
log
file
. This is identifying data about the
transaction and all of the
transaction
milestones
proxy.config.http2.stream.slow.log.threshold
Scope
CONFIG
Type
INT
Default
Units
milliseconds
Reloadable
Yes
yaml:
records
http2
stream
slow
log
threshold
If set to a non-zero value
then any HTTP/2 stream
that takes longer than
milliseconds from open to close will cause
its timing stats to be written to the
debugging
log
file
. This is identifying data about the
transaction and all of the
transaction
milestones
proxy.config.log.config.filename
Scope
CONFIG
Type
STRING
Default
logging.yaml
Reloadable
Yes
Deprecated
Yes
yaml:
records
log
config
filename
logging.yaml
This configuration value specifies the path to the
logging.yaml
configuration file. If this is a relative
path, Traffic Server loads it relative to the
SYSCONFDIR
directory.
proxy.config.log.max_line_size
Scope
CONFIG
Type
INT
Default
9216
Units
bytes
yaml:
records
log
max_line_size
9216
This controls the maximum line length for
ASCII
formatted log entries.
This applies to
ASCII_PIPE
and
ASCII
file logs,
unless
proxy.config.log.ascii_buffer_size
is also specified and the value
of
ascii_buffer_size
is larger than
max_line_size
: in that case,
max_line_size
only applies to
ASCII_PIPE
logs while
ascii_buffer_size
will apply to
ASCII
(non-pipe) log files.
proxy.config.log.ascii_buffer_size
Scope
CONFIG
Type
INT
Default
36864
Units
bytes
yaml:
records
log
ascii_buffer_size
36864
This controls the maximum line length for
ASCII
formatted log entries
that are non-pipe log files. If this value is smaller than
proxy.config.log.max_line_size
, then the latter will be used for
both
ASCII
and
ASCII_PIPE
log files. If both
max_line_size
and
ascii_buffer_size
are set, then
max_line_size
will be used for
ASCII_PIPE
logs while
ascii_buffer_size
will be used for
ASCII
(non-pipe) log files. This all might seem complicated, but just keep in
mind that the intention of
ascii_buffer_size
is to simply provide a way
for the user to configure different
ASCII
and
ASCII_PIPE
maximum
line lengths.
proxy.config.log.log_buffer_size
Scope
CONFIG
Type
INT
Default
9216
Units
bytes
Reloadable
Yes
yaml:
records
log
log_buffer_size
9216
This is an orthogonal mechanism from
proxy.config.log.max_line_size
and
proxy.config.log.ascii_buffer_size
for limiting line length
size by constraining the log entry buffer to a particular amount of memory.
Unlike the above two configurations,
log_buffer_size
applies to both
binary and
ASCII
log file entries. For
ASCII
log files, if a maximum
log size is set via both the above mechanisms and by
log_buffer_size
then the smaller of the two configurations will be applied to the line
length.
Diagnostic Logging Configuration
proxy.config.diags.output.diag
Scope
CONFIG
Type
STRING
Default
yaml:
records
diags
output
diag
proxy.config.diags.output.debug
Scope
CONFIG
Type
STRING
Default
yaml:
records
diags
output
debug
proxy.config.diags.output.status
Scope
CONFIG
Type
STRING
Default
yaml:
records
diags
output
status
proxy.config.diags.output.note
Scope
CONFIG
Type
STRING
Default
yaml:
records
diags
output
note
proxy.config.diags.output.warning
Scope
CONFIG
Type
STRING
Default
yaml:
records
diags
output
warning
proxy.config.diags.output.error
Scope
CONFIG
Type
STRING
Default
SL
yaml:
records
diags
output
error
SL
proxy.config.diags.output.fatal
Scope
CONFIG
Type
STRING
Default
SL
yaml:
records
diags
output
fatal
SL
proxy.config.diags.output.alert
Scope
CONFIG
Type
STRING
Default
yaml:
records
diags
output
alert
proxy.config.diags.output.emergency
Scope
CONFIG
Type
STRING
Default
SL
yaml:
records
diags
output
emergency
SL
The diagnostic output configuration variables control where Traffic
Server should log diagnostic output. Messages at each diagnostic level
can be directed to any combination of diagnostic destinations.
Valid diagnostic message destinations are:
Value
Description
Log to standard output.
Log to standard error.
Log to syslog.
Log to
diags.log
(with the filename configurable via
proxy.config.diags.logfile.filename
).
Example
To log debug diagnostics to both syslog and
diags.log
CONFIG
proxy
config
diags
output
debug
STRING
SL
proxy.config.diags.show_location
Scope
CONFIG
Type
INT
Default
yaml:
records
diags
show_location
Annotates diagnostic messages with the source code location. Set to 1 to enable
for Dbg() messages only. Set to 2 to enable for all messages.
proxy.config.diags.debug.enabled
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
yaml:
records
diags
debug
enabled
When set to 1, enables logging for diagnostic messages whose log level is
diag
or
debug
When set to 2, interprets the
proxy.config.diags.debug.client_ip
setting determine whether diagnostic messages are logged.
See the
Enable debug using traffic_ctl
for a convenient way to handle this.
proxy.config.diags.debug.client_ip
Scope
CONFIG
Type
STRING
Default
NULL
yaml:
records
diags
debug
client_ip
null
if
proxy.config.diags.debug.enabled
is set to 2, this value is tested against the source IP of the incoming connection. If there is a match, all the diagnostic messages for that connection and the related outgoing connection will be logged.
proxy.config.diags.debug.tags
Scope
CONFIG
Type
STRING
Default
http|dns
yaml:
records
diags
debug
tags
http|dns
Each Traffic Server
diag
and
debug
level message is annotated with a subsystem tag. This configuration
contains an anchored regular expression that filters the messages based on the tag. The
expressions are prefix matched which creates an implicit
.*
at the end. Therefore the default
value
http|dns
will match tags such as
http
http_hdrs
dns
, and
dns_recv
Some commonly used debug tags are:
Tag
Subsystem usage
dns
DNS query resolution
http_hdrs
Logs the headers for HTTP requests and responses
privileges
Privilege elevation
ssl
TLS termination and certificate processing
proxy.config.diags.debug.throttling_interval_msec
Scope
CONFIG
Type
INT
Default
Units
milliseconds
Reloadable
Yes
yaml:
records
diags
debug
throttling_interval_msec
The minimum amount of milliseconds between repeated Traffic Server
diag
and
debug
log events. A value of 0 implies no throttling. All diags and debug logs
are compiled with throttling applied to them.
For details about how log throttling works, see
log.throttling_interval_msec
proxy.config.diags.logfile.filename
Scope
CONFIG
Type
STRING
Default
diags.log
yaml:
records
diags
logfile
filename
diags.log
The name of the file to which Traffic Server diagnostic logs will be emitted. For
information on the diagnostic log file, see
diags.log
. For the
configurable parameters concerning what log content is emitted to
diags.log
, see the
Diagnostic Output Configuration Variables
above.
If this is set to
stdout
or
stderr
, then all diagnostic logging will
go to the stdout or stderr stream, respectively.
proxy.config.error.logfile.filename
Scope
CONFIG
Type
STRING
Default
error.log
yaml:
records
error
logfile
filename
error.log
The name of the file to which Traffic Server transaction error logs will be emitted.
For more information on these log messages, see
error.log
If this is set to
stdout
or
stderr
, then all transaction error
logging will go to the stdout or stderr stream, respectively.
proxy.config.diags.logfile_perm
Scope
CONFIG
Type
STRING
Default
rw-r–r–
yaml:
records
diags
logfile_perm
rw-r--r--
The log file permissions. The standard UNIX file permissions are used (owner, group, other). Permissible values are:
Value
Description
No permissions.
Read permission.
Write permission.
Execute permission.
Permissions are subject to the umask settings for the Traffic Server process. This
means that a umask setting of
002
will not allow write permission for
others, even if specified in the configuration file. Permissions for
existing log files are not changed when the configuration is modified.
proxy.config.diags.logfile.rolling_enabled
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
yaml:
records
diags
logfile
rolling_enabled
Specifies how the diagnostics log is rolled. You can specify the following values:
Value
Description
Disables diagnostics log rolling.
Enables diagnostics log rolling at specific intervals (specified with
proxy.config.diags.logfile.rolling_interval_sec
). The “clock”
starts ticking on Traffic Server startup.
Enables diagnostics log rolling when the diagnostics log reaches a
specific size (specified with
proxy.config.diags.logfile.rolling_size_mb
).
Enables diagnostics log rolling at specific intervals or when the
diagnostics log reaches a specific size (whichever occurs first).
proxy.config.diags.logfile.rolling_interval_sec
Scope
CONFIG
Type
INT
Default
3600
Units
seconds
Reloadable
Yes
yaml:
records
diags
logfile
rolling_interval_sec
3600
Specifies how often the diagnostics log is rolled, in seconds. The timer starts on Traffic Server startup.
proxy.config.diags.logfile.rolling_size_mb
Scope
CONFIG
Type
INT
Default
100
Units
megabytes
Reloadable
Yes
yaml:
records
diags
logfile
rolling_size_mb
100
Specifies at what size to roll the diagnostics log at.
proxy.config.diags.logfile.rolling_min_count
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
yaml:
records
diags
logfile
rolling_min_count
Specifies the minimum count of rolled diagnostic logs to keep. This value will be used to decide the
order of auto-deletion (if enabled). A default value of 0 means auto-deletion will try to keep
diagnostic logs as much as possible. See
Log Rotation and Retention
for guidance.
Reverse Proxy
proxy.config.reverse_proxy.enabled
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
yaml:
records
reverse_proxy
enabled
Enables (
) or disables (
) HTTP reverse proxy.
proxy.config.header.parse.no_host_url_redirect
Scope
CONFIG
Type
STRING
Default
NULL
Reloadable
Yes
yaml:
records
header
parse
no_host_url_redirect
null
The URL to which to redirect requests with no host headers (reverse
proxy).
URL Remap Rules
proxy.config.url_remap.filename
Scope
CONFIG
Type
STRING
Default
remap.config
Deprecated
Yes
yaml:
records
url_remap
filename
remap.config
Sets the name of the
remap.config
file.
proxy.config.url_remap.remap_required
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
yaml:
records
url_remap
remap_required
Set this variable to
if you want Traffic Server to serve
requests only from origin servers listed in the mapping rules of the
remap.config
file. If a request does not match, then the browser
will receive an error.
proxy.config.url_remap.pristine_host_hdr
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
Overridable
Yes
yaml:
records
url_remap
pristine_host_hdr
Set this variable to
if you want to retain the client host
header in a request during remapping.
proxy.config.url_remap.min_rules_required
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
yaml:
records
url_remap
min_rules_required
The minimum number of rules
remap.config
must have to be considered valid. An otherwise
valid configuration with fewer than this many rules is considered to be invalid as if it had a syntax
error. A value of zero allows
remap.config
to be empty or absent.
This is dynamic to enable different requirements for startup and reloading.
proxy.config.url_remap.acl_behavior_policy
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
yaml:
records
url_remap
acl_behavior_policy
This controls how the ACL filter
allow
and
deny
actions behave in
remap.config
. See
ACL Filters
for more details.
Value
Description
Legacy (9.x and below) behavior.
Modern (10.x and above) behavior.
The value
provides ACL filter
allow
and
deny
action behavior that is backwards compatible with previous
versions of Traffic Server. The value
results in a fatal log message if
allow
or
deny
is used with a message
encouraging the user to transition to either
set_allow
or
set_deny
or
add_allow
or
add_deny
actions.
is the default value.
Note
This configuration is deprecated in 10.x. Starting with 11.x, Traffic Server will always function like this configuration is
set to
(modern) and the configuration will be removed entirely.
SSL Termination
proxy.config.ssl.server.cipher_suite
Scope
CONFIG
Type
STRING
Default

yaml:
records
ssl
server
cipher_suite

Configures the set of encryption, digest, authentication, and key exchange
algorithms provided by OpenSSL which Traffic Server will use for SSL connections. For
the list of algorithms and instructions on constructing an appropriately
formatting cipher_suite string, see
OpenSSL Ciphers
The current default is:
ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-CCM:ECDHE-ECDSA-AES128-CCM:ECDHE-ECDSA-AES256-CCM8:ECDHE-ECDSA-AES128-CCM8:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES256-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES128-SHA256:DHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-CCM8:DHE-RSA-AES128-CCM8:DHE-RSA-AES256-CCM:DHE-RSA-AES128-CCM:DHE-RSA-AES256-SHA256:DHE-RSA-AES128-SHA256:AES256-GCM-SHA384:AES128-GCM-SHA256:AES256-CCM8:AES128-CCM8:AES256-CCM:AES128-CCM:AES256-SHA256:AES128-SHA2
proxy.config.ssl.client.cipher_suite
Scope
CONFIG
Type
STRING
Default

yaml:
records
ssl
client
cipher_suite

Configures the cipher_suite which Traffic Server will use for SSL connections to origin or next hop. This currently defaults to:
ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:DHE-DSS-AES256-GCM-SHA384:DHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-CCM8:ECDHE-ECDSA-AES256-CCM:DHE-RSA-AES256-CCM8:DHE-RSA-AES256-CCM:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-ARIA256-GCM-SHA384:ECDHE-ARIA256-GCM-SHA384:DHE-DSS-ARIA256-GCM-SHA384:DHE-RSA-ARIA256-GCM-SHA384:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:DHE-RSA-AES256-SHA256:DHE-DSS-AES256-SHA256:ECDHE-ECDSA-CAMELLIA256-SHA384:ECDHE-RSA-CAMELLIA256-SHA384:DHE-RSA-CAMELLIA256-SHA256:DHE-DSS-CAMELLIA256-SHA256:RSA-PSK-AES256-GCM-SHA384:RSA-PSK-CHACHA20-POLY1305:RSA-PSK-ARIA256-GCM-SHA384:AES256-GCM-SHA384:AES256-CCM8:AES256-CCM:ARIA256-GCM-SHA384:AES256-SHA256:CAMELLIA256-SHA256:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:DHE-DSS-AES128-GCM-SHA256:DHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-CCM8:ECDHE-ECDSA-AES128-CCM:DHE-RSA-AES128-CCM8:DHE-RSA-AES128-CCM:ECDHE-ECDSA-ARIA128-GCM-SHA256:ECDHE-ARIA128-GCM-SHA256:DHE-DSS-ARIA128-GCM-SHA256:DHE-RSA-ARIA128-GCM-SHA256:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA256:DHE-DSS-AES128-SHA256:ECDHE-ECDSA-CAMELLIA128-SHA256:ECDHE-RSA-CAMELLIA128-SHA256:DHE-RSA-CAMELLIA128-SHA256:DHE-DSS-CAMELLIA128-SHA256:RSA-PSK-AES128-GCM-SHA256:RSA-PSK-ARIA128-GCM-SHA256:AES128-GCM-SHA256:AES128-CCM8:AES128-CCM:ARIA128-GCM-SHA256:AES128-SHA256:CAMELLIA128-SHA256
proxy.config.ssl.server.TLSv1_3.cipher_suites
Scope
CONFIG
Type
STRING
Default

yaml:
records
ssl
server
TLSv1_3
cipher_suites

Configures the pair of the AEAD algorithm and hash algorithm to be
used with HKDF provided by OpenSSL which Traffic Server will use for TLSv1.3
connections. For the list of algorithms and instructions, see
The
-ciphersuites
section of
OpenSSL Ciphers
The current default value is:
TLS_AES_256_GCM_SHA384:TLS_AES_128_GCM_SHA256:TLS_CHACHA20_POLY1305_SHA256
This configuration works with OpenSSL v1.1.1 and above. BoringSSL does not support customizing the list.
proxy.config.ssl.server.honor_cipher_order
Scope
CONFIG
Type
INT
Default
yaml:
records
ssl
server
honor_cipher_order
By default (
) Traffic Server will use the server’s preferences for cipher suites, supported groups, and
signature algorithms instead of the client preferences. By disabling it (
) Traffic Server will use the
client’s preferences. Note that despite the configuration name mentioning “cipher_order”, this
setting controls server preference for multiple aspects of TLS negotiation, not just cipher suites.
proxy.config.ssl.server.prioritize_chacha
Scope
CONFIG
Type
INT
Default
yaml:
records
ssl
server
prioritize_chacha
By enabling it (
) Traffic Server will temporarily reprioritize ChaCha20-Poly1305 ciphers to the top of the
server cipher list if a ChaCha20-Poly1305 cipher is at the top of the client cipher list.
This configuration works with OpenSSL v1.1.1 and above. BoringSSL does not support this.
proxy.config.ssl.client.TLSv1_3.cipher_suites
Scope
CONFIG
Type
STRING
Default

yaml:
records
ssl
client
TLSv1_3
cipher_suites

Configures the cipher_suites which Traffic Server will use for TLSv1.3
connections to origin or next hop. This configuration works
with OpenSSL v1.1.1 and above. BoringSSL does not support customizing the list.
The current default is:
TLS_AES_256_GCM_SHA384:TLS_AES_128_GCM_SHA256:TLS_CHACHA20_POLY1305_SHA256
proxy.config.ssl.server.groups_list
Scope
CONFIG
Type
STRING
Default

yaml:
records
ssl
server
groups_list

Configures the list of supported groups provided by OpenSSL which
Traffic Server will be used to determine the set of shared groups. The value
is a colon separated list of group NIDs or names, for example
“P-521:P-384:P-256”. For instructions, see “Groups” section of
TLS1.3 - OpenSSLWiki
The current default value with OpenSSL is:
X25519:P-256:X448:P-521:P-384
This configuration works with OpenSSL v1.0.2 and above.
proxy.config.ssl.client.groups_list
Scope
CONFIG
Type
STRING
Default

yaml:
records
ssl
client
groups_list

Configures the list of supported groups provided by OpenSSL which
Traffic Server will use for the “key_share” and “supported groups” extension
of TLSv1.3 connections. The value is a colon separated list of
group NIDs or names, for example “P-521:P-384:P-256”. For
instructions, see “Groups” section of
TLS1.3 - OpenSSLWiki
This configuration works with OpenSSL v1.0.2 and above.
proxy.config.ssl.server.version.min
Scope
CONFIG
Type
INT
Default
-1
yaml:
records
ssl
server
version
min
-1
Specifies the minimum TLS version that will be offered to clients during the TLS negotiation.
Value
Version
TLS 1.0
TLS 1.1
TLS 1.2
TLS 1.3
proxy.config.ssl.server.version.max
Scope
CONFIG
Type
INT
Default
-1
yaml:
records
ssl
server
version
max
-1
Specifies the maximum TLS version that will be offered to clients during the TLS negotiation.
Value
Version
TLS 1.0
TLS 1.1
TLS 1.2
TLS 1.3
proxy.config.ssl.TLSv1
Scope
CONFIG
Type
INT
Default
Deprecated
Yes
yaml:
records
ssl
TLSv1
This setting is deprecated in favor of
proxy.config.ssl.server.version.min
and
proxy.config.ssl.server.version.min
, and will be ignored if those new settings are used.
Enables (
) or disables (
) TLSv1.0. If not specified, disabled by default.
proxy.config.ssl.TLSv1_1
Scope
CONFIG
Type
INT
Default
Deprecated
Yes
yaml:
records
ssl
TLSv1_1
This setting is deprecated in favor of
proxy.config.ssl.server.version.min
and
proxy.config.ssl.server.version.min
, and will be ignored if those new settings are used.
Enables (
) or disables (
) TLS v1.1. If not specified, disabled by default. [Requires OpenSSL v1.0.1 and higher]
Note
In order to enable TLS v1 or v1.1, additional ciphers must be added to proxy.config.ssl.client.cipher_suite. For
example this list would restore the SHA1 (insecure!) cipher suites suitable for these deprecated TLS versions:
ECDHE-ECDSA-AES256-SHA:ECDHE-RSA-AES256-SHA:DHE-RSA-AES256-SHA:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES128-SHA:DHE-RSA-AES128-SHA:AES256-SHA:AES128-SHA
proxy.config.ssl.TLSv1_2
Scope
CONFIG
Type
INT
Default
Deprecated
Yes
yaml:
records
ssl
TLSv1_2
This setting is deprecated in favor of
proxy.config.ssl.server.version.min
and
proxy.config.ssl.server.version.min
, and will be ignored if those new settings are used.
Enables (
) or disables (
) TLS v1.2. If not specified, enabled by default. [Requires OpenSSL v1.0.1 and higher]
proxy.config.ssl.TLSv1_3.enabled
Scope
CONFIG
Type
INT
Default
Deprecated
Yes
yaml:
records
ssl
TLSv1_3
enabled
This setting is deprecated in favor of
proxy.config.ssl.server.version.min
and
proxy.config.ssl.server.version.min
, and will be ignored if those new settings are used.
Enables (
) or disables (
) TLS v1.3. If not specified, enabled by default. [Requires OpenSSL v1.1.1 and higher]
proxy.config.ssl.client.certification_level
Scope
CONFIG
Type
INT
Default
yaml:
records
ssl
client
certification_level
Sets the client certification level:
Value
Description
Client certificates are
ignored
. Traffic Server does not verify client
certificates during the SSL handshake. Access to Traffic Server depends on Traffic Server
configuration options (such as access control lists).
Client certificates are
optional
. If a client has a certificate,
then the certificate is validated. If the client does not have a
certificate, then the client is still allowed access to Traffic Server unless
access is denied through other Traffic Server configuration options.
Client certificates are
required
. The client must be authenticated
during the SSL handshake. Clients without a certificate are not
allowed to access Traffic Server.
proxy.config.ssl.server.multicert.filename
Scope
CONFIG
Type
STRING
Default
ssl_multicert.yaml
Deprecated
Yes
yaml:
records
ssl
server
multicert
filename
ssl_multicert.yaml
The location of the
ssl_multicert.yaml
file, relative
to the Traffic Server configuration directory. In the following
example, if the Traffic Server configuration directory is
/etc/trafficserver
, the Traffic Server SSL configuration file
and the corresponding certificates are located in
/etc/trafficserver/ssl
CONFIG
proxy
config
ssl
server
multicert
filename
STRING
ssl
ssl_multicert
yaml
CONFIG
proxy
config
ssl
server
cert
path
STRING
etc
trafficserver
ssl
CONFIG
proxy
config
ssl
server
private_key
path
STRING
etc
trafficserver
ssl
proxy.config.ssl.server.multicert.exit_on_load_fail
Scope
CONFIG
Type
INT
Default
yaml:
records
ssl
server
multicert
exit_on_load_fail
By default (
), Traffic Server will not start unless all the SSL certificates listed in the
ssl_multicert.yaml
file successfully load. If false (
), SSL certificate
load failures will not prevent Traffic Server from starting.
proxy.config.ssl.server.cert.path
Scope
CONFIG
Type
STRING
Default
/config
yaml:
records
ssl
server
cert
path
/config
The location of the SSL certificates and chains used for accepting
and validation new SSL sessions. If this is a relative path,
it is appended to the Traffic Server installation PREFIX. All
certificates and certificate chains listed in
ssl_multicert.yaml
will be loaded relative to this path.
proxy.config.ssl.server.private_key.path
Scope
CONFIG
Type
STRING
Default
NULL
yaml:
records
ssl
server
private_key
path
null
The location of the SSL certificate private keys. Change this
variable only if the private key is not located in the SSL
certificate file. All private keys listed in
ssl_multicert.yaml
will be loaded relative to this
path.
proxy.config.ssl.server.cert_chain.filename
Scope
CONFIG
Type
STRING
Default
NULL
yaml:
records
ssl
server
cert_chain
filename
null
The name of a file containing a global certificate chain that
should be used with every server certificate. This file is only
used if there are certificates defined in
ssl_multicert.yaml
Unless this is an absolute path, it is loaded relative to the
path specified by
proxy.config.ssl.server.cert.path
proxy.config.ssl.server.dhparams_file
Scope
CONFIG
Type
STRING
Default
NULL
yaml:
records
ssl
server
dhparams_file
null
The name of a file containing a set of Diffie-Hellman key exchange
parameters. If not specified, 2048-bit DH parameters from RFC 5114 are
used. These parameters are only used if a DHE (or EDH) cipher suite has
been selected.
proxy.config.ssl.CA.cert.path
Scope
CONFIG
Type
STRING
Default
NULL
yaml:
records
ssl
CA
cert
path
null
The location of the certificate authority file that client
certificates will be verified against.
proxy.config.ssl.CA.cert.filename
Scope
CONFIG
Type
STRING
Default
NULL
yaml:
records
ssl
CA
cert
filename
null
The filename of the certificate authority that client certificates
will be verified against.
proxy.config.ssl.server.ticket_key.filename
Scope
CONFIG
Type
STRING
Default
NULL
yaml:
records
ssl
server
ticket_key
filename
null
The filename of the default and global ticket key for SSL sessions. The location is relative to the
proxy.config.ssl.server.cert.path
directory. One way to generate this would be to run
head
-c48
/dev/urandom
openssl
enc
-base64
head
-c48
file.ticket
. Also
note that OpenSSL session tickets are sensitive to the version of the ca-certificates. Once the
file is changed with new tickets, use
traffic_ctl
config
reload
to begin using them.
proxy.config.ssl.servername.filename
Scope
CONFIG
Type
STRING
Default
sni.yaml
Deprecated
Yes
yaml:
records
ssl
servername
filename
sni.yaml
The filename of the
sni.yaml
configuration file.
If relative, it is relative to the configuration directory.
proxy.config.ssl.max_record_size
Scope
CONFIG
Type
INT
Default
yaml:
records
ssl
max_record_size
This configuration specifies the maximum number of bytes to write
into a SSL record when replying over a SSL session. In some
circumstances this setting can improve response latency by reducing
buffering at the SSL layer. This setting can have a value between 0
and 16383 (max TLS record size).
The default of
means to always write all available data into
a single SSL record.
A value of
-1
means TLS record size is dynamically determined. The
strategy employed is to use small TLS records that fit into a single
TCP segment for the first ~1 MB of data, but, increase the record size to
16 KB after that to optimize throughput. The record size is reset back to
a single segment after ~1 second of inactivity and the record size ramping
mechanism is repeated again.
proxy.config.ssl.origin_session_cache.enabled
Scope
CONFIG
Type
INT
Default
yaml:
records
ssl
origin_session_cache
enabled
This configuration enables the SSL session cache for the origin server
when set to
Setting to
disables SSL session cache for the origin server.
proxy.config.ssl.origin_session_cache.size
Scope
CONFIG
Type
INT
Default
10240
yaml:
records
ssl
origin_session_cache
size
10240
This configuration specifies the maximum number of entries
the SSL session cache for the origin server may contain.
Setting a value less than or equal to
effectively disables
SSL session cache for the origin server.
proxy.config.ssl.server.session_ticket.enable
Scope
CONFIG
Type
INT
Default
yaml:
records
ssl
server
session_ticket
enable
Set to 1 to enable Traffic Server to process TLS tickets for TLS session resumption.
proxy.config.ssl.server.session_ticket.number
Scope
CONFIG
Type
INT
Default
yaml:
records
ssl
server
session_ticket
number
This configuration controls the number of TLSv1.3 session tickets that are issued.
Setting the value to 0 will disable session ticket-based session resumption for TLSv1.3
connections.
Increasing the number of tickets could be potentially beneficial for clients performing
multiple requests over concurrent TLS connections as per RFC 8446 clients SHOULDN’T reuse TLS Tickets.
For more information see
proxy.config.ssl.hsts_max_age
Scope
CONFIG
Type
INT
Default
-1
Overridable
Yes
yaml:
records
ssl
hsts_max_age
-1
This configuration specifies the max-age value that will be used
when adding the Strict-Transport-Security header. The value is in seconds.
A value of
will set the max-age value to
and should remove the
HSTS entry from the client. A value of
-1
will disable this feature and
not set the header. This option is only used for HTTPS requests and the
header will not be set on HTTP requests.
proxy.config.ssl.hsts_include_subdomains
Scope
CONFIG
Type
INT
Default
Overridable
Yes
yaml:
records
ssl
hsts_include_subdomains
Enables (
) or disables (
) adding the includeSubdomain value
to the Strict-Transport-Security header. proxy.config.ssl.hsts_max_age
needs to be set to a non
-1
value for this configuration to take effect.
proxy.config.ssl.allow_client_renegotiation
Scope
CONFIG
Type
INT
Default
yaml:
records
ssl
allow_client_renegotiation
This configuration specifies whether the client is able to initiate
renegotiation of the SSL connection. The default of
, means
the client can’t initiate renegotiation.
proxy.config.ssl.cert.load_elevated
Scope
CONFIG
Type
INT
Default
yaml:
records
ssl
cert
load_elevated
Enables (
) or disables (
) elevation of traffic_server
privileges during loading of SSL certificates. By enabling this, SSL
certificate files’ access rights can be restricted to help reduce the
vulnerability of certificates.
This feature requires Traffic Server to be built with POSIX
capabilities enabled.
proxy.config.ssl.handshake_timeout_in
Scope
CONFIG
Type
INT
Default
30
yaml:
records
ssl
handshake_timeout_in
30
When enabled this limits the total duration for the incoming side SSL
handshake.
See
Timeout Settings
for more discussion on Traffic Server timeouts.
proxy.config.ssl.keylog_file
Scope
CONFIG
Type
STRING
Default
NULL
Reloadable
Yes
yaml:
records
ssl
keylog_file
null
If configured, TLS session keys for TLS connections will be logged to the
specified file. This file is formatted in such a way that it can be
conveniently imported into tools such as Wireshark to decrypt packet
captures. This should only be used for debugging purposes since the data in
the keylog file can be used to decrypt the otherwise encrypted traffic. A
NULL value for this disables the feature.
This feature is disabled by default.
proxy.config.ssl.ktls.enabled
Scope
CONFIG
Type
INT
Default
yaml:
records
ssl
ktls
enabled
Enables the use of Kernel TLS. This configuration requires OpenSSL v3.0 and
above, and it must have been compiled with support for Kernel TLS.
Value
Description
Disables the use of Kernel TLS.
Enables the use of Kernel TLS..
Client-Related Configuration
proxy.config.ssl.client.verify.server.policy
Scope
CONFIG
Type
STRING
Default
ENFORCED
Reloadable
Yes
Overridable
Yes
yaml:
records
ssl
client
verify
server
policy
ENFORCED
Configures Traffic Server to verify the origin server certificate
with the Certificate Authority (CA). This configuration takes a value of
DISABLED
PERMISSIVE
, or
ENFORCED
You can override this global setting on a per domain basis in the
sni.yaml
file using the
verify_server_policy
attribute.
You can also override via the conf_remap plugin. Those changes will take precedence over the changes in
sni.yaml
DISABLED
Server Certificate will not be verified
PERMISSIVE
The provided certificate will be verified and the connection will be established irrespective of the verification result. If verification fails the name of the server will be logged.
ENFORCED
Certificate will be verified and the connection will not be established if verification fails.
proxy.config.ssl.client.verify.server.properties
Scope
CONFIG
Type
STRING
Default
ALL
Reloadable
Yes
Overridable
Yes
yaml:
records
ssl
client
verify
server
properties
ALL
Configures Traffic Server for what the default verify callback should check during origin server verification.
You can override this global setting on a per domain basis in the
sni.yaml
file using the
verify_server_properties
attribute.
You can also override via the conf_remap plugin. Those changes will take precedence over the changes in
sni.yaml
NONE
Check nothing in the standard callback. Rely entirely on plugins to check the certificate.
SIGNATURE
Check only for a valid signature.
NAME
Check only that the SNI name is in the certificate.
ALL
Check both the signature and the name.
proxy.config.ssl.client.cert.filename
Scope
CONFIG
Type
STRING
Default
NULL
Reloadable
Yes
Overridable
Yes
yaml:
records
ssl
client
cert
filename
null
The filename of SSL client certificate installed on Traffic Server.
proxy.config.ssl.client.cert.exit_on_load_fail
Scope
CONFIG
Type
INT
Default
yaml:
records
ssl
client
cert
exit_on_load_fail
By default (
), Traffic Server will start even if problems occur when loading the
SSL client certificates. If true (
), SSL client certificate load
failures will prevent Traffic Server from starting.
proxy.config.ssl.client.cert.path
Scope
CONFIG
Type
STRING
Default
/config
Reloadable
Yes
yaml:
records
ssl
client
cert
path
/config
The location of the SSL client certificate installed on Traffic
Server.
proxy.config.ssl.client.private_key.filename
Scope
CONFIG
Type
STRING
Default
NULL
Reloadable
Yes
Overridable
Yes
yaml:
records
ssl
client
private_key
filename
null
The filename of the Traffic Server private key. Change this variable
only if the private key is not located in the Traffic Server SSL
client certificate file.
proxy.config.ssl.client.private_key.path
Scope
CONFIG
Type
STRING
Default
NULL
Reloadable
Yes
yaml:
records
ssl
client
private_key
path
null
The location of the Traffic Server private key. Change this variable
only if the private key is not located in the SSL client certificate
file.
proxy.config.ssl.client.CA.cert.filename
Scope
CONFIG
Type
STRING
Default
NULL
Reloadable
Yes
Overridable
Yes
yaml:
records
ssl
client
CA
cert
filename
null
The filename of the certificate authority against which the origin
server will be verified.
proxy.config.ssl.client.CA.cert.path
Scope
CONFIG
Type
STRING
Default
NULL
Reloadable
Yes
yaml:
records
ssl
client
CA
cert
path
null
Specifies the location of the certificate authority file against
which the origin server will be verified.
proxy.config.ssl.client.sni_policy
Scope
CONFIG
Type
STRING
Default
NULL
Overridable
Yes
yaml:
records
ssl
client
sni_policy
null
Indicate how the SNI value for the TLS connection to the origin is selected.
host
This is the default. The value of the
Host
field in the proxy request is used.
server_name
The SNI value of the inbound TLS connection is used.
remap
The remapped upstream name is used.
verify_with_name_source
The value of the
Host
field in the proxy request is used. In addition, if the names in the
server certificate of the upstream are checked, they are checked against the remapped upstream
name, not the SNI.
@...
If the policy starts with the
character, it is treated as a literal, less the leading
. E.g. if the policy is “@apache.org” the SNI will be “apache.org”.
We have two names that could be used in the transaction host header and the SNI value to the
origin. These could be the host header from the client or the remap host name. Unless you have
pristine host header enabled, these are likely the same values.
If sni_policy =
host
, both the sni and the value of the
Host
field to origin will be the
same. If sni_policy =
remap
, the sni value will be the remap host name and the host header
will be the host header from the client.
In addition, We may want to set the SNI and host headers the same (makes some common web servers
happy), but the server certificate for the upstream may have a name that corresponds to the remap
name. So instead of using the SNI name for the name check, we may want to use the remap name. So
if sni_policy =
verify_with_name_source
, the sni will be the host header value and the name
to check in the server certificate will be the remap header value.
proxy.config.ssl.client.scheme_proto_mismatch_policy
Scope
CONFIG
Type
INT
Default
Overridable
Yes
yaml:
records
ssl
client
scheme_proto_mismatch_policy
This option controls how Traffic Server behaves when the client side connection
protocol and the client request’s scheme do not match. For example, if
enforcement is enabled by setting this value to
and the client
connection is a cleartext HTTP connection but the scheme of the URL is
, then Traffic Server will emit a warning and return an immediate 400 HTTP
response without proxying the request to the origin.
The default value is
, meaning that Traffic Server will enforce that the protocol
matches the scheme.
Value
Description
Disable verification that the protocol and scheme match.
Check that the protocol and scheme match, but only emit a warning if
they do not.
Check that the protocol and scheme match and, if they do not, emit a
warning and return an immediate HTTP 400 response.
proxy.config.ssl.client.version.min
Scope
CONFIG
Type
INT
Default
-1
yaml:
records
ssl
client
version
min
-1
Specifies the minimum TLS version that will be offered to servers during the TLS negotiation.
Value
Version
TLS 1.0
TLS 1.1
TLS 1.2
TLS 1.3
proxy.config.ssl.client.version.max
Scope
CONFIG
Type
INT
Default
-1
yaml:
records
ssl
client
version
max
-1
Specifies the maximum TLS version that will be offered to servers during the TLS negotiation.
Value
Version
TLS 1.0
TLS 1.1
TLS 1.2
TLS 1.3
proxy.config.ssl.client.TLSv1
Scope
CONFIG
Type
INT
Default
Deprecated
Yes
yaml:
records
ssl
client
TLSv1
This setting is deprecated in favor of
proxy.config.ssl.client.version.min
and
proxy.config.ssl.client.version.max
, and will be ignored if those new settings are used.
Enables (
) or disables (
) TLSv1.0 in the ATS client context. If not specified, disabled by default
proxy.config.ssl.client.TLSv1_1
Scope
CONFIG
Type
INT
Default
Deprecated
Yes
yaml:
records
ssl
client
TLSv1_1
This setting is deprecated in favor of
proxy.config.ssl.client.version.min
and
proxy.config.ssl.client.version.max
, and will be ignored if those new settings are used.
Enables (
) or disables (
) TLSv1_1 in the ATS client context. If not specified, disabled by default
proxy.config.ssl.client.TLSv1_2
Scope
CONFIG
Type
INT
Default
Deprecated
Yes
yaml:
records
ssl
client
TLSv1_2
This setting is deprecated in favor of
proxy.config.ssl.client.version.min
and
proxy.config.ssl.client.version.max
, and will be ignored if those new settings are used.
Enables (
) or disables (
) TLSv1_2 in the ATS client context. If not specified, enabled by default
proxy.config.ssl.client.TLSv1_3.enabled
Scope
CONFIG
Type
INT
Default
Deprecated
Yes
yaml:
records
ssl
client
TLSv1_3
enabled
This setting is deprecated in favor of
proxy.config.ssl.client.version.min
and
proxy.config.ssl.client.version.max
, and will be ignored if those new settings are used.
Enables (
) or disables (
) TLSv1_3 in the ATS client context. If not specified, enabled by default
proxy.config.ssl.client.alpn_protocols
Scope
CONFIG
Type
STRING
Default
“”
Overridable
Yes
yaml:
records
ssl
client
alpn_protocols
'""'
Sets the ALPN string that Traffic Server will send to the origin in the ClientHello of TLS handshakes.
Configuring this to an empty string (the default configuration) means that the ALPN extension
will not be sent as a part of the TLS ClientHello, resulting in HTTP/1.x being negotiated for all
origin-side connections.
Configuring the ALPN string provides a mechanism to control origin-side HTTP protocol
negotiation. Including
h2
in the ALPN list is required for negotiatnge origin-side HTTP/2
connections.
Configuring this requires an understanding of the ALPN TLS protocol extension. See
RFC 7301
for details about the ALPN protocol.
See the official
IANA ALPN protocol registration
for the official list of ALPN protocol names. As a summary, the ALPN string is a comma-separated
(no spaces) list of protocol names that the TLS client (Traffic Server in this case) supports. On the TLS
server side (origin side in this case), the names are compared in order to the list of protocols
supported by the origin. The first match is used, thus the ALPN list should be listed in
decreasing order of preference. If no match is found, the TLS server is expected (per the RFC) to
fail the TLS handshake with a fatal “no_application_protocol” alert.
Currently, Traffic Server supports the following ALPN protocol names:
http/1.0
http/1.1
h2
Here are some example configurations and the consequences of each:
Value
Description
""
No ALPN extension is sent by Traffic Server in origin-side TLS handshakes.
Traffic Server will assume an HTTP/1.1 connection in this case.
"http/1.1"
Only HTTP/1.1 is advertised by Traffic Server. Thus, the origin will
either negotiate HTTP/1.1, or it will fail the handshake if that
is not supported by the origin.
"http/1.1,http/1.0"
Both HTTP/1.1 and HTTP/1.0 are supported by Traffic Server, but HTTP/1.1
is preferred.
"h2,http/1.1,http/1.0"
HTTP/2 is preferred by Traffic Server over HTTP/1.1 and HTTP/1.0. Thus, if the
origin supports HTTP/2, it will be used for the connection. If
not, it will fall back to HTTP/1.1 or, if that is not supported,
HTTP/1.0.
"h2"
Traffic Server only advertises HTTP/2 support. Thus, the origin will
either negotiate HTTP/2 or fail the handshake.
Note that this is an overridable configuration, so the ALPN can be configured on a per-origin
basis via the
Configuration Remap Plugin
plugin.
proxy.config.ssl.async.handshake.enabled
Scope
CONFIG
Type
INT
Default
yaml:
records
ssl
async
handshake
enabled
Enables the use of OpenSSL async job during the TLS handshake. Traffic
Server must be build against OpenSSL 1.1 or greater or this to take affect.
Can be useful if using a crypto engine that communicates off chip. The
thread will be rescheduled for other work until the crypto engine operation
completes. A test crypto engine that inserts a 5 second delay on private key
operations can be found at
contrib/openssl/async_engine.cc
proxy.config.ssl.engine.conf_file
Scope
CONFIG
Type
STRING
Default
NULL
yaml:
records
ssl
engine
conf_file
null
Specify the location of the OpenSSL config file used to load dynamic crypto
engines. This setting assumes an absolute path. An example config file is at
contrib/openssl/load_engine.cnf
TLS v1.3 0-RTT Configuration
Note
TLS v1.3 must be enabled in order to utilize 0-RTT early data.
proxy.config.ssl.server.max_early_data
Scope
CONFIG
Type
INT
Default
yaml:
records
ssl
server
max_early_data
Specifies the maximum amount of early data in bytes that is permitted to be sent on a single connection.
The minimum value that enables early data, and the suggested value for this option are both 16384 (16KB).
Setting to
effectively disables 0-RTT.
If you use BoringSSL, setting a value grater than 0 enables early data but the value won’t be used to limit the
maximum amount of early data.
proxy.config.ssl.server.allow_early_data_params
Scope
CONFIG
Type
INT
Default
yaml:
records
ssl
server
allow_early_data_params
Set to
to allow HTTP parameters on early data requests.
SNI Routing
proxy.config.tunnel.activity_check_period
Scope
CONFIG
Type
INT
Default
Units
seconds
yaml:
records
tunnel
activity_check_period
Frequency of checking the activity of SNI Routing Tunnel. Set to
to disable monitoring of the activity of the SNI tunnels.
The feature is disabled by default.
proxy.config.tunnel.prewarm.enabled
Scope
CONFIG
Type
INT
Default
yaml:
records
tunnel
prewarm
enabled
Enable
Pre-warming TLS Tunnel
. The feature is disabled by default.
proxy.config.tunnel.prewarm.algorithm
Scope
CONFIG
Type
INT
Default
yaml:
records
tunnel
prewarm
algorithm
Version of pre-warming algorithm.
Value
Description
Periodical pre-warming only
Event based pre-warming + Periodical pre-warming
proxy.config.tunnel.prewarm.event_period
Scope
CONFIG
Type
INT
Default
1000
Units
milliseconds
yaml:
records
tunnel
prewarm
event_period
1000
Frequency of periodical pre-warming in milli-seconds.
OCSP Stapling Configuration
proxy.config.ssl.ocsp.enabled
Scope
CONFIG
Type
INT
Default
yaml:
records
ssl
ocsp
enabled
Enable OCSP stapling.
Value
Description
Disables OCSP Stapling.
Allows Traffic Server to request SSL certificate revocation status from an OCSP
responder.
proxy.config.ssl.ocsp.cache_timeout
Scope
CONFIG
Type
INT
Default
3600
yaml:
records
ssl
ocsp
cache_timeout
3600
Number of seconds before an OCSP response expires in the stapling cache.
proxy.config.ssl.ocsp.request_mode
Scope
CONFIG
Type
INT
Default
yaml:
records
ssl
ocsp
request_mode
Set the request method to prefer when querying OCSP responders. The default
is zero, or POST, and a value of 1 will cause ATS to attempt a GET request.
Because the length of the encoded request must be less than 255 bytes per RFC
6960, Appendix A, ATS will fall back to the POST request method when the
encoded size exceeds this limit.
proxy.config.ssl.ocsp.request_timeout
Scope
CONFIG
Type
INT
Default
10
Units
seconds
yaml:
records
ssl
ocsp
request_timeout
10
Timeout (in seconds) for queries to OCSP responders.
proxy.config.ssl.ocsp.update_period
Scope
CONFIG
Type
INT
Default
60
Units
seconds
yaml:
records
ssl
ocsp
update_period
60
Update period (in seconds) for stapling caches.
proxy.config.ssl.ocsp.response.path
Scope
CONFIG
Type
STRING
Default
NULL
yaml:
records
ssl
ocsp
response
path
null
The directory path of the prefetched OCSP stapling responses. Change this
variable only if you intend to use and administratively maintain
prefetched OCSP stapling responses. All stapling responses listed in
ssl_multicert.yaml
will be loaded relative to this
path.
HTTP/2 Configuration
proxy.config.http2.max_concurrent_streams_in
Scope
CONFIG
Type
INT
Default
100
Reloadable
Yes
yaml:
records
http2
max_concurrent_streams_in
100
The maximum number of concurrent streams per inbound connection.
Note
Reloading this value affects only new HTTP/2 connections, not the
ones already established.
proxy.config.http2.max_concurrent_streams_out
Scope
CONFIG
Type
INT
Default
100
Reloadable
Yes
yaml:
records
http2
max_concurrent_streams_out
100
The maximum number of concurrent streams per outbound connection.
Note
Reloading this value affects only new HTTP/2 connections, not the
ones already established.
proxy.config.http2.min_concurrent_streams_in
Scope
CONFIG
Type
INT
Default
10
Reloadable
Yes
yaml:
records
http2
min_concurrent_streams_in
10
The minimum number of concurrent streams per inbound connection.
This is used when
proxy.config.http2.max_active_streams_in
is set
larger than
proxy.config.http2.min_concurrent_streams_out
Scope
CONFIG
Type
INT
Default
10
Reloadable
Yes
yaml:
records
http2
min_concurrent_streams_out
10
The minimum number of concurrent streams per outbound connection.
This is used when
proxy.config.http2.max_active_streams_out
is set
larger than
proxy.config.http2.max_active_streams_in
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
yaml:
records
http2
max_active_streams_in
Limits the maximum number of connection wide active streams.
When connection wide active streams are larger than this value,
SETTINGS_MAX_CONCURRENT_STREAMS will be reduced to
proxy.config.http2.min_concurrent_streams_in
To disable, set to zero (
).
proxy.config.http2.max_active_streams_out
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
yaml:
records
http2
max_active_streams_out
Limits the maximum number of connection wide active streams.
When connection wide active streams are larger than this value,
SETTINGS_MAX_CONCURRENT_STREAMS will be reduced to
proxy.config.http2.min_concurrent_streams_out
To disable, set to zero (
).
proxy.config.http2.initial_window_size_in
Scope
CONFIG
Type
INT
Default
65535
Units
bytes
Reloadable
Yes
yaml:
records
http2
initial_window_size_in
65535
The initial HTTP/2 stream window size for inbound connections that Traffic Server as a
receiver advertises to the peer. See IETF RFC 9113 section 5.2 for details
concerning HTTP/2 flow control. See
proxy.config.http2.flow_control.policy_in
for how HTTP/2 stream and
session windows are maintained over the lifetime of HTTP/2 sessions.
proxy.config.http2.initial_window_size_out
Scope
CONFIG
Type
INT
Default
65535
Units
bytes
Reloadable
Yes
yaml:
records
http2
initial_window_size_out
65535
The initial HTTP/2 stream window size for outbound connections that Traffic Server as a
client advertises to the peer. See IETF RFC 9113 section 5.2 for details
concerning HTTP/2 flow control. See
proxy.config.http2.flow_control.policy_out
for how HTTP/2 stream and
session windows are maintained over the lifetime of HTTP/2 sessions.
proxy.config.http2.flow_control.policy_in
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
yaml:
records
http2
flow_control
policy_in
Specifies the mechanism Traffic Server uses to maintian flow control via the HTTP/2
stream and session windows for inbound connections. See IETF RFC 9113
section 5.2 for details concerning HTTP/2 flow control.
Value
Description
Session and stream receive windows are initialized and maintained at the value as specified
in
proxy.config.http2.initial_window_size_in
over the lifetime of HTTP/2
sessions.
Session receive windows are initialized to the value of the product of
proxy.config.http2.initial_window_size_in
and
proxy.config.http2.max_concurrent_streams_in
and are maintained as such over the
lifetime of HTTP/2 sessions. Stream windows are initialized to the value of
proxy.config.http2.initial_window_size_in
and are maintained as such over the
lifetime of each HTTP/2 stream.
Session receive windows are initialized to the value of the product of
proxy.config.http2.initial_window_size_in
and
proxy.config.http2.max_concurrent_streams_in
and are maintained as such over the
lifetime of HTTP/2 sessions. Stream windows are initialized to the value of
proxy.config.http2.initial_window_size_in
but are dynamically adjusted to the
session window size divided by the number of concurrent streams over the lifetime of HTTP/2
sessions. That is, stream window sizes dynamically adjust to fill the session window in
a way that shares the window equally among all concurrent streams.
proxy.config.http2.flow_control.policy_out
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
yaml:
records
http2
flow_control
policy_out
Specifies the mechanism Traffic Server uses to maintian flow control via the HTTP/2
stream and session windows for outbound connections. See the corresponding
proxy.config.http2.flow_control.policy_in
configuration for details concerning how this configuration variable is used.
proxy.config.http2.max_frame_size
Scope
CONFIG
Type
INT
Default
16384
Units
bytes
Reloadable
Yes
yaml:
records
http2
max_frame_size
16384
Indicates the size of the largest frame payload that the sender is willing
to receive.
proxy.config.http2.header_table_size
Scope
CONFIG
Type
INT
Default
4096
Reloadable
Yes
yaml:
records
http2
header_table_size
4096
The maximum size of the header compression table used to decode header
blocks. This value will be advertised as SETTINGS_HEADER_TABLE_SIZE.
proxy.config.http2.header_table_size_limit
Scope
CONFIG
Type
INT
Default
65536
Reloadable
Yes
yaml:
records
http2
header_table_size_limit
65536
The maximum size of the header compression table ATS actually use when ATS
encodes headers. Setting 0 means ATS doesn’t insert headers into HPACK
Dynamic Table, however, headers still can be encoded as indexable
representations. The upper limit is 65536.
proxy.config.http2.max_header_list_size
Scope
CONFIG
Type
INT
Default
32768
Reloadable
Yes
yaml:
records
http2
max_header_list_size
32768
This advisory setting informs a peer of the maximum size of header list
that the sender is prepared to accept.
proxy.config.http2.stream_priority_enabled
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
yaml:
records
http2
stream_priority_enabled
Enable the experimental HTTP/2 Stream Priority feature.
proxy.config.http2.active_timeout_in
Scope
CONFIG
Type
INT
Default
Units
seconds
Reloadable
Yes
yaml:
records
http2
active_timeout_in
This is the active timeout of the http2 connection. It is set when the connection is opened
and keeps ticking regardless of activity level.
The value of
specifies that there is no timeout.
proxy.config.http2.accept_no_activity_timeout
Scope
CONFIG
Type
INT
Default
120
Units
seconds
Reloadable
Yes
yaml:
records
http2
accept_no_activity_timeout
120
Specifies how long Traffic Server keeps connections to clients open if no
activity is received on the connection. Lowering this timeout can ease
pressure on the proxy if misconfigured or misbehaving clients are opening
a large number of connections without submitting requests.
proxy.config.http2.no_activity_timeout_in
Scope
CONFIG
Type
INT
Default
120
Units
seconds
Reloadable
Yes
yaml:
records
http2
no_activity_timeout_in
120
Specifies how long Traffic Server keeps connections to clients open if a
transaction stalls. Lowering this timeout can ease pressure on the proxy if
misconfigured or misbehaving clients are opening a large number of
connections without submitting requests.
proxy.config.http2.no_activity_timeout_out
Scope
CONFIG
Type
INT
Default
120
Units
seconds
Reloadable
Yes
yaml:
records
http2
no_activity_timeout_out
120
Specifies how long Traffic Server keeps connections to origins open if a
transaction stalls.
proxy.config.http2.incomplete_header_timeout_in
Scope
CONFIG
Type
INT
Default
10
Units
seconds
Reloadable
Yes
yaml:
records
http2
incomplete_header_timeout_in
10
Specifies how long Traffic Server keeps streams to clients open after they start sending HTTP headers. If a client doesn’t send all
headers within this time, the stream and connection will be closed.
proxy.config.http2.zombie_debug_timeout_in
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
yaml:
records
http2
zombie_debug_timeout_in
This timeout enables the zombie debugging feature. If it is non-zero, it sets a zombie event to go off that
many seconds in the future when the HTTP2 session reaches one but not both of the terminating events, i.e received
a close event (via client goaway or timeout) and the number of active streams has gone to zero. If the event is executed,
the Traffic Server process will assert. This mechanism is useful to debug potential leaks in the HTTP2 Stream and Session
processing.
proxy.config.http2.push_diary_size
Scope
CONFIG
Type
INT
Default
256
Reloadable
Yes
yaml:
records
http2
push_diary_size
256
Indicates the maximum number of HTTP/2 server pushes that are remembered per
HTTP/2 connection to avoid duplicate pushes on the same connection. If the
maximum number is reached, new entries are not remembered.
proxy.config.http2.stream_error_rate_threshold
Scope
CONFIG
Type
FLOAT
Default
0.1
Reloadable
Yes
yaml:
records
http2
stream_error_rate_threshold
0.1
This is the maximum stream error rate Traffic Server allows on an HTTP/2 connection.
Traffic Server gracefully closes connections that have stream error rates above this
setting by sending GOAWAY frames.
proxy.config.http2.stream_error_sampling_threshold
Scope
CONFIG
Type
INT
Default
10
Reloadable
Yes
yaml:
records
http2
stream_error_sampling_threshold
10
This is the threshold of sampling stream number to start checking the stream error rate.
proxy.config.http2.max_settings_per_frame
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
yaml:
records
http2
max_settings_per_frame
Specifies how many settings in an HTTP/2 SETTINGS frame Traffic Server accepts.
Clients exceeded this limit will be immediately disconnected with an error
code of ENHANCE_YOUR_CALM.
Any negative value configures no limit to the number of settings received.
proxy.config.http2.max_settings_per_minute
Scope
CONFIG
Type
INT
Default
14
Reloadable
Yes
yaml:
records
http2
max_settings_per_minute
14
Specifies how many settings in HTTP/2 SETTINGS frames Traffic Server accept for a minute.
Clients exceeded this limit will be immediately disconnected with an error
code of ENHANCE_YOUR_CALM.
Any negative value configures no limit to the number of settings received.
proxy.config.http2.max_settings_frames_per_minute
Scope
CONFIG
Type
INT
Default
14
Reloadable
Yes
yaml:
records
http2
max_settings_frames_per_minute
14
Specifies how many SETTINGS frames Traffic Server receives for a minute at maximum.
Clients exceeded this limit will be immediately disconnected with an error
code of ENHANCE_YOUR_CALM.
Any negative value configures no limit to the number of SETTINGS frames received.
proxy.config.http2.max_ping_frames_per_minute
Scope
CONFIG
Type
INT
Default
60
Reloadable
Yes
yaml:
records
http2
max_ping_frames_per_minute
60
Specifies how many number of PING frames Traffic Server receives for a minute at maximum.
Clients exceeded this limit will be immediately disconnected with an error
code of ENHANCE_YOUR_CALM.
Any negative value configures no limit to the number of PING frames received.
proxy.config.http2.max_priority_frames_per_minute
Scope
CONFIG
Type
INT
Default
120
Reloadable
Yes
yaml:
records
http2
max_priority_frames_per_minute
120
Specifies how many number of PRIORITY frames Traffic Server receives for a minute at maximum.
Clients exceeded this limit will be immediately disconnected with an error
code of ENHANCE_YOUR_CALM. If this is set to 0, the limit logic is disabled.
This limit only will be enforced if
proxy.config.http2.stream_priority_enabled
is set to 1.
Any negative value configures no limit to the number of PRIORITY frames received.
proxy.config.http2.max_rst_stream_frames_per_minute
Scope
CONFIG
Type
INT
Default
200
Reloadable
Yes
yaml:
records
http2
max_rst_stream_frames_per_minute
200
Specifies how many RST_STREAM frames Traffic Server receives per minute at maximum.
Clients exceeding this limit will be immediately disconnected with an error
code of ENHANCE_YOUR_CALM.
Any negative value configures no limit to the number of RST_STREAM frames received.
proxy.config.http2.max_continuation_frames_per_minute
Scope
CONFIG
Type
INT
Default
120
Reloadable
Yes
yaml:
records
http2
max_continuation_frames_per_minute
120
Specifies how many CONTINUATION frames Traffic Server receives per minute at maximum.
Clients exceeding this limit will be immediately disconnected with an error
code of ENHANCE_YOUR_CALM.
Any negative value configures no limit to the number of CONTINUATION frames received.
proxy.config.http2.max_empty_frames_per_minute
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
yaml:
records
http2
max_empty_frames_per_minute
Specifies the maximum number of empty frames Traffic Server will receive per minute before it will start closing connections.
In this context, an “empty frame” means either a DATA frame that does not carry a payload
nor an END_STREAM flag, or a CONTINUATION frame that does not carry payload
nor an END_HEADERS flag.
Clients exceeding this limit will be immediately disconnected with an error
code of ENHANCE_YOUR_CALM.
Any negative value configures no limit to the number of empty frames received.
is the default configuration, meaning that no empty frames are allowed.
proxy.config.http2.min_avg_window_update
Scope
CONFIG
Type
FLOAT
Default
2560.0
Reloadable
Yes
yaml:
records
http2
min_avg_window_update
2560.0
Specifies the minimum average window increment Traffic Server allows. The average will be calculated based on the last 5 WINDOW_UPDATE frames.
Clients that send smaller window increments lower than this limit will be immediately disconnected with an error
code of ENHANCE_YOUR_CALM.
proxy.config.http2.write_buffer_block_size
Scope
CONFIG
Type
INT
Default
262144
Units
bytes
Reloadable
Yes
yaml:
records
http2
write_buffer_block_size
262144
Specifies the size of a buffer block that is used for buffering outgoing
HTTP/2 frames. The size will be rounded up based on power of 2.
proxy.config.http2.write_size_threshold
Scope
CONFIG
Type
FLOAT
Default
0.5
Reloadable
Yes
yaml:
records
http2
write_size_threshold
0.5
Specifies the size threshold for triggering write operation for sending HTTP/2
frames. The default value is 0.5 and it measn write operation is going to be
triggered when half or more of the buffer is occupied.
proxy.config.http2.write_time_threshold
Scope
CONFIG
Type
INT
Default
100
Units
milliseconds
Reloadable
Yes
yaml:
records
http2
write_time_threshold
100
Specifies the time threshold for triggering write operation for sending HTTP/2
frames. Write operation will be triggered at least once every this configured
number of millisecond regardless of pending data size.
proxy.config.http2.default_buffer_water_mark
Scope
CONFIG
Type
INT
Default
-1
Units
bytes
Reloadable
Yes
yaml:
records
http2
default_buffer_water_mark
-1
Specifies the high water mark for all HTTP/2 frames on an outgoing connection.
Default is -1 to preserve existing water marking behavior.
You can override this global setting on a per domain basis in the
sni.yaml
file using the
http2_buffer_water_mark
attribute.
HTTP/3 Configuration
There is no configuration available yet on this release.
QUIC Configuration
All configurations for QUIC are still experimental and may be changed or
removed in the future without prior notice.
proxy.config.quic.qlog.file_base
Scope
CONFIG
Type
STRING
Default
NULL
Reloadable
Yes
yaml:
records
quic
qlog
file_base
null
Sets qlog output to a specific base file name. For a given file base name the file becomes
{file_base}-{trace
id}.sqlog
Absolute path or relative to the configured prefix can be used.
Qlog is emitted for each connection.
records
quic
qlog
file_base
/my/logs/test1
The above configuration will make Traffic Server to generate Qlogs with the following format:
/my/logs/test1-e9158839e54cb8f34ab00d34236ad5e19a49.sqlog
proxy.config.quic.instance_id
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
yaml:
records
quic
instance_id
A static key used for calculating Stateless Reset Token. All instances in a
cluster need to share the same value.
proxy.config.quic.connection_table.size
Scope
CONFIG
Type
INT
Default
65521
yaml:
records
quic
connection_table
size
65521
A size of hash table that stores connection information.
proxy.config.quic.proxy.config.quic.num_alt_connection_ids
Scope
CONFIG
Type
INT
Default
65521
Reloadable
Yes
yaml:
records
quic
proxy
config
quic
num_alt_connection_ids
65521
A number of alternate Connection IDs that Traffic Server provides to a peer. It has to
be at least 8.
proxy.config.quic.stateless_retry_enabled
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
yaml:
records
quic
stateless_retry_enabled
Enables Stateless Retry.
proxy.config.quic.client.vn_exercise_enabled
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
yaml:
records
quic
client
vn_exercise_enabled
Enables version negotiation exercise on origin server connections.
proxy.config.quic.client.cm_exercise_enabled
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
yaml:
records
quic
client
cm_exercise_enabled
Enables connection migration exercise on origin server connections.
proxy.config.quic.server.supported_groups
Scope
CONFIG
Type
STRING
Default
“P-256:X25519:P-384:P-521”
Reloadable
Yes
yaml:
records
quic
server
supported_groups
'"P-256:X25519:P-384:P-521"'
Configures the list of supported groups provided by OpenSSL which will be
used to determine the set of shared groups on QUIC origin server connections.
proxy.config.quic.client.supported_groups
Scope
CONFIG
Type
STRING
Default
“P-256:X25519:P-384:P-521”
Reloadable
Yes
yaml:
records
quic
client
supported_groups
'"P-256:X25519:P-384:P-521"'
Configures the list of supported groups provided by OpenSSL which will be
used to determine the set of shared groups on QUIC client connections.
proxy.config.quic.client.session_file
Scope
CONFIG
Type
STRING
Default
“”
Reloadable
Yes
yaml:
records
quic
client
session_file
'""'
Only available for
traffic_quic
If specified, TLS session data will be stored to the file, and will be used
for resuming a session.
proxy.config.quic.no_activity_timeout_in
Scope
CONFIG
Type
INT
Default
30000
Reloadable
Yes
yaml:
records
quic
no_activity_timeout_in
30000
The max idle timeout in milliseconds.
This value will be advertised as
idle_timeout
Transport Parameter.
Transport Parameter.
Important
QUIC ignores any settings for
proxy.config.net.default_inactivity_timeout
and only
honors the
proxy.config.quic.no_activity_timeout_in
proxy.config.quic.no_activity_timeout_out
Scope
CONFIG
Type
INT
Default
30000
Reloadable
Yes
yaml:
records
quic
no_activity_timeout_out
30000
The max idle timeout in milliseconds.
This value will be advertised as
idle_timeout
Transport Parameter.
Transport Parameter.
proxy.config.quic.preferred_address_ipv4
Scope
CONFIG
Type
STRING
Default
“”
Reloadable
Yes
yaml:
records
quic
preferred_address_ipv4
'""'
This value will be advertised as a part of
preferred_address
Transport Parameter.
proxy.config.quic.preferred_address_ipv6
Scope
CONFIG
Type
STRING
Default
“”
Reloadable
Yes
yaml:
records
quic
preferred_address_ipv6
'""'
This value will be advertised as a part of
preferred_address
Transport Parameter.
proxy.config.quic.initial_max_data_in
Scope
CONFIG
Type
INT
Default
65536
Reloadable
Yes
yaml:
records
quic
initial_max_data_in
65536
Integer value that contains the initial value for the maximum amount of data
that can be sent on the connection.
This value will be advertised as
initial_max_data
Transport Parameter.
proxy.config.quic.initial_max_data_out
Scope
CONFIG
Type
INT
Default
65536
Reloadable
Yes
yaml:
records
quic
initial_max_data_out
65536
This value will be advertised as
initial_max_data
Transport Parameter.
proxy.config.quic.max_stream_data_bidi_local_in
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
yaml:
records
quic
max_stream_data_bidi_local_in
This value will be advertised as
initial_max_stream_data_bidi_local
Transport Parameter.
proxy.config.quic.max_stream_data_bidi_local_out
Scope
CONFIG
Type
INT
Default
4096
Reloadable
Yes
yaml:
records
quic
max_stream_data_bidi_local_out
4096
This value will be advertised as
initial_max_stream_data_bidi_local
Transport Parameter.
proxy.config.quic.max_stream_data_bidi_remote_in
Scope
CONFIG
Type
INT
Default
4096
Reloadable
Yes
yaml:
records
quic
max_stream_data_bidi_remote_in
4096
This value will be advertised as
initial_max_stream_data_bidi_remote
Transport Parameter.
proxy.config.quic.max_stream_data_bidi_remote_out
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
yaml:
records
quic
max_stream_data_bidi_remote_out
This value will be advertised as
initial_max_stream_data_bidi_remote
Transport Parameter.
proxy.config.quic.max_stream_data_uni_in
Scope
CONFIG
Type
INT
Default
4096
Reloadable
Yes
yaml:
records
quic
max_stream_data_uni_in
4096
This value will be advertised as
initial_max_stream_data_uni
Transport Parameter.
proxy.config.quic.max_stream_data_uni_out
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
yaml:
records
quic
max_stream_data_uni_out
This value will be advertised as
initial_max_stream_data_uni
Transport Parameter.
proxy.config.quic.max_streams_bidi_in
Scope
CONFIG
Type
INT
Default
100
Reloadable
Yes
yaml:
records
quic
max_streams_bidi_in
100
This value will be advertised as
initial_max_streams_bidi
Transport Parameter.
proxy.config.quic.max_streams_bidi_out
Scope
CONFIG
Type
INT
Default
100
Reloadable
Yes
yaml:
records
quic
max_streams_bidi_out
100
This value will be advertised as
initial_max_streams_bidi
Transport Parameter.
proxy.config.quic.max_streams_uni_in
Scope
CONFIG
Type
INT
Default
100
Reloadable
Yes
yaml:
records
quic
max_streams_uni_in
100
This value will be advertised as
initial_max_streams_uni
Transport Parameter.
proxy.config.quic.max_streams_uni_out
Scope
CONFIG
Type
INT
Default
100
Reloadable
Yes
yaml:
records
quic
max_streams_uni_out
100
This value will be advertised as
initial_max_streams_uni
Transport Parameter.
proxy.config.quic.ack_delay_exponent_in
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
yaml:
records
quic
ack_delay_exponent_in
This value will be advertised as
ack_delay_exponent
Transport Parameter.
proxy.config.quic.ack_delay_exponent_out
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
yaml:
records
quic
ack_delay_exponent_out
This value will be advertised as
ack_delay_exponent
Transport Parameter.
proxy.config.quic.max_ack_delay_in
Scope
CONFIG
Type
INT
Default
25
Reloadable
Yes
yaml:
records
quic
max_ack_delay_in
25
This value will be advertised as
max_ack_delay
Transport Parameter.
proxy.config.quic.max_ack_delay_out
Scope
CONFIG
Type
INT
Default
25
Reloadable
Yes
yaml:
records
quic
max_ack_delay_out
25
This value will be advertised as
max_ack_delay
Transport Parameter.
proxy.config.quic.active_cid_limit_in
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
yaml:
records
quic
active_cid_limit_in
Integer value specifying the maximum number of connection IDs from the peer
that Traffic Server is willing to store. The value MUST be at least 2.
Transport Parameter.
proxy.config.quic.max_recv_udp_payload_size_in
Scope
CONFIG
Type
INT
Default
65527
yaml:
records
quic
max_recv_udp_payload_size_in
65527
This value will be advertised as
max_udp_payload_size
Transport Parameter.
proxy.config.quic.max_recv_udp_payload_size_out
Scope
CONFIG
Type
INT
Default
65527
yaml:
records
quic
max_recv_udp_payload_size_out
65527
This value will be advertised as
max_udp_payload_size
Transport Parameter.
proxy.config.quic.max_send_udp_payload_size_in
Scope
CONFIG
Type
INT
Default
65527
yaml:
records
quic
max_send_udp_payload_size_in
65527
Specified the maximum outgoing UDP payload size.
proxy.config.quic.max_send_udp_payload_size_out
Scope
CONFIG
Type
INT
Default
65527
yaml:
records
quic
max_send_udp_payload_size_out
65527
Specified the maximum outgoing UDP payload size.
proxy.config.quic.disable_http_0_9
Scope
CONFIG
Type
INT
Default
yaml:
records
quic
disable_http_0_9
Disables HTTP/0.9 over QUIC by default.
proxy.config.quic.cc_algorithm
Scope
CONFIG
Type
INT
Default
yaml:
records
quic
cc_algorithm
Specified the congestion control algorithm.
Value
Description
RENO (default).
CUBIC.
UDP Configuration
proxy.config.udp.poll_timeout
Scope
CONFIG
Type
INT
Default
100
Units
milliseconds
yaml:
records
udp
poll_timeout
100
This is the timeout for listening UDP connections to
epoll_wait()
on
Linux platforms, and to
kevent()
on BSD type OSs. The default value is
100. See
proxy.config.net.poll_timeout
for general information on
poll_timeout.
proxy.config.udp.threads
Scope
CONFIG
Type
INT
Default
yaml:
records
udp
threads
Specifies the number of UDP threads to run. By default 0 threads are dedicated to UDP,
which results in effectively disabling UDP support.
proxy.config.udp.enable_gso
Scope
CONFIG
Type
INT
Default
yaml:
records
udp
enable_gso
Enables (
) or disables (
) UDP GSO. When enabled, Traffic Server tries to use UDP GSO,
and disables it automatically if it causes send errors.
proxy.config.udp.enable_gro
Scope
CONFIG
Type
INT
Default
yaml:
records
udp
enable_gro
Enables (
) or disables (
) UDP GRO. When enabled, Traffic Server will try to use it
when reading the UDP socket.
Plug-in Configuration
proxy.config.plugin.plugin_dir
Scope
CONFIG
Type
STRING
Default
config/plugins
yaml:
records
plugin
plugin_dir
config/plugins
Specifies the location of Traffic Server plugins.
proxy.config.plugin.dynamic_reload_mode
Scope
CONFIG
Type
INT
Default
yaml:
records
plugin
dynamic_reload_mode
Enables (
) or disables (
) the dynamic reload feature for remap
plugins (
remap.config
). Global plugins (
plugin.config
) do not have dynamic reload feature yet.
proxy.config.plugin.compiler_path
Scope
CONFIG
Type
STRING
Default
“”
yaml:
records
plugin
compiler_path
'""'
Specifies an optional compiler tool path for compiling plugins. This tool should
be an executable, which takes two arguments:
Arg
Description
This is the path to the source file, which should be compiled
This is the path to the DSO file, which will be created and loaded
The script should exit with a status code of
if the compilation was successful.
proxy.config.plugin.vc.default_buffer_index
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
Overridable
Yes
yaml:
records
plugin
vc
default_buffer_index
Specifies the buffer index and thus size to use when constructing IO buffers within the PluginVC.
Tuning this can impact performance of intercept plugins. Default is 8, which aligns with the
default value of ts:cv:
CONFIG proxy.config.http.default_buffer_size
proxy.config.plugin.vc.default_buffer_water_mark
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
Overridable
Yes
yaml:
records
plugin
vc
default_buffer_water_mark
Specifies the buffer water mark size in bytes used to control the flow of data through IO buffers
within the PluginVC. Default is zero to preserve existing PluginVC water marking behavior.
SOCKS Processor
proxy.config.socks.socks_needed
Scope
CONFIG
Type
INT
Default
yaml:
records
socks
socks_needed
Enables (
) or disables (
) the SOCKS processor
proxy.config.socks.socks_version
Scope
CONFIG
Type
INT
Default
yaml:
records
socks
socks_version
Specifies the SOCKS version (
) or (
proxy.config.socks.socks_config_file
Scope
CONFIG
Type
STRING
Default
socks.config
Deprecated
Yes
yaml:
records
socks
socks_config_file
socks.config
The socks.config file allows you to specify ranges of IP addresses
that will not be relayed to the SOCKS server. It can also be used
to configure AUTH information for SOCKSv5 servers.
proxy.config.socks.socks_timeout
Scope
CONFIG
Type
INT
Default
100
yaml:
records
socks
socks_timeout
100
The activity timeout value (in seconds) for SOCKS server connections.
See
Timeout Settings
for more discussion on Traffic Server timeouts.
proxy.config.socks.server_connect_timeout
Scope
CONFIG
Type
INT
Default
10
yaml:
records
socks
server_connect_timeout
10
The timeout value (in seconds) for SOCKS server connection attempts.
See
Timeout Settings
for more discussion on Traffic Server timeouts.
proxy.config.socks.per_server_connection_attempts
Scope
CONFIG
Type
INT
Default
yaml:
records
socks
per_server_connection_attempts
The total number of connection attempts allowed per SOCKS server,
if multiple servers are used.
proxy.config.socks.connection_attempts
Scope
CONFIG
Type
INT
Default
yaml:
records
socks
connection_attempts
The total number of connection attempts allowed to a SOCKS server
Traffic Server bypasses the server or fails the request
proxy.config.socks.server_retry_timeout
Scope
CONFIG
Type
INT
Default
300
yaml:
records
socks
server_retry_timeout
300
The timeout value (in seconds) for SOCKS server connection retry attempts.
See
Timeout Settings
for more discussion on Traffic Server timeouts.
proxy.config.socks.default_servers
Scope
CONFIG
Type
STRING
Default
“”
yaml:
records
socks
default_servers
'""'
Default list of SOCKS servers and their ports.
proxy.config.socks.server_retry_time
Scope
CONFIG
Type
INT
Default
300
yaml:
records
socks
server_retry_time
300
The amount of time allowed between connection retries to a SOCKS
server that is unavailable.
proxy.config.socks.server_fail_threshold
Scope
CONFIG
Type
INT
Default
yaml:
records
socks
server_fail_threshold
The number of times the connection to the SOCKS server can fail
before Traffic Server considers the server unavailable.
proxy.config.socks.accept_enabled
Scope
CONFIG
Type
INT
Default
yaml:
records
socks
accept_enabled
Enables (1) or disables (0) the SOCKS proxy option. As a SOCKS
proxy, Traffic Server receives SOCKS traffic (usually on port
1) and forwards all requests directly to the SOCKS server.
proxy.config.socks.accept_port
Scope
CONFIG
Type
INT
Default
1080
yaml:
records
socks
accept_port
1080
Specifies the port on which Traffic Server accepts SOCKS traffic.
proxy.config.socks.http_port
Scope
CONFIG
Type
INT
Default
80
yaml:
records
socks
http_port
80
Specifies the port on which Traffic Server accepts HTTP proxy requests
over SOCKS connections..
Sockets
proxy.config.net.defer_accept
Scope
CONFIG
Type
INT
Default
yaml:
records
net
defer_accept
default:
meaning
on
all Platforms except Linux:
45
seconds
This directive enables operating system specific optimizations for a listening socket.
defer_accept
holds a call to
accept(2)
back until data has arrived. In Linux’ special case this is up to a maximum of 45 seconds. Note in Linux, additional delays may
occur as kernel handles retries using exponential backoff algorithm. On FreeBSD,
accf_data
module needs to be loaded.
Note: If MPTCP is enabled, TCP_DEFER_ACCEPT is only supported on Linux kernels 5.19+.
proxy.config.net.listen_backlog
Scope
CONFIG
Type
INT
Default
-1
Reloadable
Yes
yaml:
records
net
listen_backlog
-1
This directive sets the maximum number of pending connections.
If it is set to -1, Traffic Server will automatically set this
to a platform-specific maximum.
proxy.config.net.tcp_congestion_control_in
Scope
CONFIG
Type
STRING
Default
“”
yaml:
records
net
tcp_congestion_control_in
'""'
This directive will override the congestion control algorithm for incoming
connections (accept sockets). On Linux, the allowed values are typically
specified in a space separated list in /proc/sys/net/ipv4/tcp_allowed_congestion_control
proxy.config.net.tcp_congestion_control_out
Scope
CONFIG
Type
STRING
Default
“”
yaml:
records
net
tcp_congestion_control_out
'""'
This directive will override the congestion control algorithm for outgoing
connections (connect sockets). On Linux, the allowed values are typically
specified in a space separated list in /proc/sys/net/ipv4/tcp_allowed_congestion_control
proxy.config.net.sock_send_buffer_size_in
Scope
CONFIG
Type
INT
Default
yaml:
records
net
sock_send_buffer_size_in
Sets the send buffer size for connections from the client to Traffic Server.
proxy.config.net.sock_recv_buffer_size_in
Scope
CONFIG
Type
INT
Default
yaml:
records
net
sock_recv_buffer_size_in
Sets the receive buffer size for connections from the client to Traffic Server.
proxy.config.net.sock_option_flag_in
Scope
CONFIG
Type
INT
Default
0x1
yaml:
records
net
sock_option_flag_in
'0x1'
Turns different options “on” for the socket handling client connections::
TCP_NODELAY
SO_KEEPALIVE
SO_LINGER
with
timeout
of
seconds
TCP_FASTOPEN
PACKET_MARK
16
PACKET_TOS
32
TCP_NOTSENT_LOWAT
64
INCOMING_CPU
128
Note: If MPTCP is enabled, TCP_NODELAY is only supported on Linux kernels 5.17+ and TCP_FASTOPEN is
only supported on Linux kernels 6.2+. TCP_NOTSENT_LOWAT socket option is currently not supported.
Note
This is a bitmask and you need to decide what bits to set. Therefore,
you must set the value to
if you want to enable nodelay and
keepalive options above.
Note
To allow TCP Fast Open for client sockets on Linux, bit 2 of
the
net.ipv4.tcp_fastopen
sysctl must be set.
Note
As for SO_INCOMING_CPU, using it with SO_REUSEPORT and exec_thread affinity 4 is recommended.
records
accept_threads
exec_thread
listen
affinity
net
sock_option_flag_in
0x80
proxy.config.net.sock_send_buffer_size_out
Scope
CONFIG
Type
INT
Default
Overridable
Yes
yaml:
records
net
sock_send_buffer_size_out
Sets the send buffer size for connections from Traffic Server to the origin server.
proxy.config.net.sock_recv_buffer_size_out
Scope
CONFIG
Type
INT
Default
Overridable
Yes
yaml:
records
net
sock_recv_buffer_size_out
Sets the receive buffer size for connections from Traffic Server to
the origin server.
proxy.config.net.sock_option_flag_out
Scope
CONFIG
Type
INT
Default
0x1
Overridable
Yes
yaml:
records
net
sock_option_flag_out
'0x1'
Turns different options “on” for the origin server socket::
TCP_NODELAY
SO_KEEPALIVE
SO_LINGER
with
timeout
of
seconds
TCP_FASTOPEN
PACKET_MARK
16
PACKET_TOS
32
TCP_NOTSENT_LOWAT
64
Note
This is a bitmask and you need to decide what bits to set. Therefore,
you must set the value to
if you want to enable nodelay and
keepalive options above.
When SO_LINGER is enabled, the linger timeout time is set
to 0. This is useful when Traffic Server and the origin server
are co-located and large numbers of sockets are retained
in the TIME_WAIT state.
Note
To allow TCP Fast Open for server sockets on Linux, bit 1 of
the
net.ipv4.tcp_fastopen
sysctl must be set.
proxy.config.net.sock_mss_in
Scope
CONFIG
Type
INT
Default
yaml:
records
net
sock_mss_in
Same as the command line option
--accept_mss
that sets the MSS for all incoming requests.
Note: If MPTCP is enabled, TCP_MAXSEG socket option is not supported.
proxy.config.net.sock_packet_mark_in
Scope
CONFIG
Type
INT
Default
0x0
yaml:
records
net
sock_packet_mark_in
'0x0'
Set the packet mark on traffic destined for the client
(the packets that make up a client response).
See also
Traffic Shaping
proxy.config.net.sock_packet_mark_out
Scope
CONFIG
Type
INT
Default
0x0
Overridable
Yes
yaml:
records
net
sock_packet_mark_out
'0x0'
Set the packet mark on traffic destined for the origin
(the packets that make up an origin request).
See also
Traffic Shaping
proxy.config.net.sock_packet_tos_in
Scope
CONFIG
Type
INT
Default
0x0
yaml:
records
net
sock_packet_tos_in
'0x0'
Set the ToS/DiffServ Field on packets sent to the client
(the packets that make up a client response).
See also
Traffic Shaping
proxy.config.net.sock_packet_tos_out
Scope
CONFIG
Type
INT
Default
0x0
Overridable
Yes
yaml:
records
net
sock_packet_tos_out
'0x0'
Set the ToS/DiffServ Field on packets sent to the origin
(the packets that make up an origin request).
See also
Traffic Shaping
proxy.config.net.sock_notsent_lowat
Scope
CONFIG
Type
INT
Default
16384
Overridable
Yes
yaml:
records
net
sock_notsent_lowat
16384
Set socket option TCP_NOTSENT_LOWAT to specified value for a connection
proxy.config.net.poll_timeout
Scope
CONFIG
Type
INT
Default
10
yaml:
records
net
poll_timeout
10
Same as the command line option
--poll_timeout
, or
-t
, which
specifies the timeout used for the polling mechanism used. This timeout is
always in milliseconds (ms). This is the timeout to
epoll_wait()
on
Linux platforms, and to
kevent()
on BSD type OSs. The default value is
10
on all platforms.
Changing this configuration can reduce CPU usage on an idle system, since
periodic tasks gets processed at these intervals. On busy servers, this
overhead is diminished, since polled events triggers more frequently.
However, increasing the setting can also introduce additional latency for
certain operations, and timed events. It’s recommended not to touch this
setting unless your CPU usage is unacceptable at idle workload. Some
alternatives to this could be:
Reduce
the
number
of
worker
threads
net
threads
Reduce
the
number
of
disk
AIO
threads
Make sure accept threads are enabled
The relevant configurations for this are
records
exec_thread
autoconfig
enabled
limit
accept_threads
cache
threads_per_disk
See
Timeout Settings
for more discussion on Traffic Server timeouts.
proxy.config.task_threads
Scope
CONFIG
Type
INT
Default
yaml:
records
task_threads
Specifies the number of task threads to run. These threads are used for
various tasks that should be off-loaded from the normal network
threads. You must have at least one task thread available.
proxy.config.allocator.thread_freelist_size
Scope
CONFIG
Type
INT
Default
512
yaml:
records
allocator
thread_freelist_size
512
Sets the maximum number of elements that can be contained in a ProxyAllocator (per-thread)
before returning the objects to the global pool. If set to
, there is no limit enforced.
proxy.config.allocator.thread_freelist_low_watermark
Scope
CONFIG
Type
INT
Default
32
yaml:
records
allocator
thread_freelist_low_watermark
32
Sets the minimum number of items a ProxyAllocator (per-thread) will guarantee to be
holding at any one time.
proxy.config.allocator.hugepages
Scope
CONFIG
Type
INT
Default
yaml:
records
allocator
hugepages
Enable (1) the use of huge pages on supported platforms. (Currently only Linux)
You must also enable hugepages at the OS level. In modern Linux kernels,
this can be done by setting
/proc/sys/vm/nr_hugepages
and/or
/proc/sys/vm/nr_overcommit_hugepages
to a sufficiently large value. Check your system hugepage size (typically 2MB) using
/proc/meminfo
(look for
Hugepagesize
). The configured number of
nr_hugepages
plus
nr_overcommit_hugepages
times the hugepage size will be the amount of ram availabe for hugepages.
For more information on the implications of enabling huge pages, see
Wikipedia _
If hugepages are enabled, then the iobuffer allocator and cache directory entries will attempt to allocate
hugepages for storage. If the number of hugepages is exhausted, the allocators will revert back to regular
size pages.
proxy.config.dump_mem_info_frequency
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
yaml:
records
dump_mem_info_frequency
Enable . When enabled makes Traffic Server dump IO Buffer memory information
to
traffic.out
at

(intervals are in seconds). A zero value implies it is
disabled
proxy.config.res_track_memory
Scope
CONFIG
Type
INT
Default
yaml:
records
res_track_memory
When enabled makes Traffic Server track memory usage (allocations and releases). This
information is dumped to
traffic.out
when the user sends a SIGUSR1 signal or
periodically when
proxy.config.dump_mem_info_frequency
is enabled.
Value
Description
Memory tracking Disabled
Tracks IO Buffer Memory allocations and releases
Tracks IO Buffer Memory and OpenSSL Memory allocations and releases
proxy.config.system_clock
Scope
CONFIG
Type
INT
Default
yaml:
records
system_clock
For advanced users only
. This allows to specify the underlying system clock
used by ATS. The default is
CLOCK_REALTIME
), but a higher performance
option could be
CLOCK_REALTIME_COARSE
). See
clock_gettime(2)
for
more details. On Linux, these definitions can be found in

proxy.config.allocator.dontdump_iobuffers
Scope
CONFIG
Type
INT
Default
yaml:
records
allocator
dontdump_iobuffers
Enable (1) the exclusion of IO buffers from core files when ATS crashes on supported
platforms. (Currently only Linux). IO buffers are allocated with the MADV_DONTDUMP
with madvise() on Linux platforms that support MADV_DONTDUMP. Enabled by default.
proxy.config.allocator.iobuf_chunk_sizes
Scope
CONFIG
Type
STRING
Default
*NONE*
yaml:
records
allocator
iobuf_chunk_sizes
null
This configures the chunk sizes of each of the IO buffer allocators. The chunk size is the number
of buffers allocated in a batch when the allocator’s freelist is exhausted. This must be specified as a
space separated list of up to 15 numbers. If not specified or if any value specified is 0, the default
value will be used.
The list of numbers will specify the chunk sizes in the following order:
128
256
512
1k
2k
4k
8k
16k
32k
64k
128k
256k
512k
1M
2M
The defaults for each allocator is:
128
128
128
128
128
128
32
32
32
32
32
32
32
32
32
Even though this is specified, the actual chunk size might be modified based on the system’s page size (or hugepage
size if enabled).
You might want to adjust these values to reduce the overall number of allocations that ATS needs to make based
on your configured RAM cache size. On a running system, you can send SIGUSR1 to the ATS process to have it
log the allocator statistics and see how many of each buffer size have been allocated.
proxy.config.ssl.misc.io.max_buffer_index
Scope
CONFIG
Type
INT
Default
yaml:
records
ssl
misc
io
max_buffer_index
Configures the max IOBuffer Block index used for various SSL Operations
such as Handshake or Protocol Probe. Default value is 8 which maps to a 32K buffer
proxy.config.hostdb.io.max_buffer_index
Scope
CONFIG
Type
INT
Default
yaml:
records
hostdb
io
max_buffer_index
Configures the max IOBuffer Block index used for storing HostDB records.
Default value is 8 which maps to a 32K buffer
proxy.config.payload.io.max_buffer_index
Scope
CONFIG
Type
INT
Default
yaml:
records
payload
io
max_buffer_index
Configures the max IOBuffer Block index used for storing request payload buffer
for a POST request. Default value is 8 which maps to a 32K buffer
proxy.config.msg.io.max_buffer_index
Scope
CONFIG
Type
INT
Default
yaml:
records
msg
io
max_buffer_index
Configures the max IOBuffer Block index used for storing miscellaneous transactional
buffers such as error response body. Default value is 8 which maps to a 32K buffer
proxy.config.log.io.max_buffer_index
Scope
CONFIG
Type
INT
Default
yaml:
records
log
io
max_buffer_index
Configures the max IOBuffer Block index used for storing an access log entry.
Default value is 8 which maps to a 32K buffer
proxy.config.http.enabled
Scope
CONFIG
Type
INT
Default
yaml:
records
http
enabled
Turn on or off support for HTTP proxying. This is rarely used, the one
exception being if you run Traffic Server with a protocol plugin, and would
like for it to not support HTTP requests at all.
proxy.config.http.allow_half_open
Scope
CONFIG
Type
INT
Default
Reloadable
Yes
Overridable
Yes
yaml:
records
http
allow_half_open
Turn on or off support for connection half open for client side. Default is on, so
after client sends FIN, the connection is still there.
proxy.config.http.wait_for_cache
Scope
CONFIG
Type
INT
Default
yaml:
records
http
wait_for_cache
Accepting inbound connections and starting the cache are independent
operations in Traffic Server. This variable controls the relative timing of these
operations and Traffic Server dependency on cache because if cache is required then
inbound connection accepts should be deferred until the validity of the
cache requirement is determined. Cache initialization failure will be logged
in
diags.log
Value
Description
Decouple inbound connections and cache initialization. Connections
will be accepted as soon as possible and Traffic Server will run regardless of
the results of cache initialization.
Do not accept inbound connections until cache initialization has
finished. Traffic Server will run regardless of the results of cache
initialization.
Do not accept inbound connections until cache initialization has
finished and been sufficiently successful that cache is enabled. This
means at least one cache span is usable. If there are no spans in
storage.config
or none of the spans can be successfully parsed
and initialized then Traffic Server will shut down.
Do not accept inbound connections until cache initialization has
finished and been completely successful. This requires at least one
cache span in
storage.config
and that every span specified is
valid and successfully initialized. Any error will cause Traffic Server to shut
down.
IO_URING
proxy.config.io_uring.entries
Scope
CONFIG
Type
INT
Default
32
yaml:
records
io_uring
entries
32
Specify the number of entries in each io_uring. There will be on io_uring instance per thread that uses io_uring
for IO. This parameter is passed to io_uring_queue_init.
proxy.config.io_uring.sq_poll_ms
Scope
CONFIG
Type
INT
Default
yaml:
records
io_uring
sq_poll_ms
If this value is >0 then use submit queue polling mode. The value will be used to specifiy the sq_thread_idle parameter
to io_uring setup. More information about submit queue polling mode can be found here:
proxy.config.io_uring.attach_wq
Scope
CONFIG
Type
INT
Default
yaml:
records
io_uring
attach_wq
Set this to 1 if you want io_uring to re-use the same worker queue backend for each thread.
proxy.config.io_uring.wq_workers_bounded
Scope
CONFIG
Type
INT
Default
yaml:
records
io_uring
wq_workers_bounded
proxy.config.io_uring.wq_workers_unbounded
Scope
CONFIG
Type
INT
Default
yaml:
records
io_uring
wq_workers_unbounded
These settings configured the number of threads for the io_uring worker queue backend. See the manpage for
io_uring_register_iowq_max_workers for more information.
AIO
proxy.config.aio.mode
Scope
CONFIG
Type
STRING
Default
auto
yaml:
records
aio
mode
auto
(Only if io_uring is enabled in the build)
Normally, ATS will detect if io_uring can be used for async disk IO. Using this config item, the AIO mode
can instead be specified. The value can be one of:
Value
Description
auto
Use the default detection logic
thread
Use the AIO thread pool for disk IO
io_uring
Use io_uring for disk IO
Note: If you force the backend to use io_uring, you might experience failures with some (older, pre 5.4) kernel versions
Apache Traffic Server
v: 11.0.0
Languages
Versions