Provided by: trafficserver_9.2.3+ds-1+deb12u1build4_amd64 
NAME
records.config - the records.config file (by default, located in
/usr/local/etc/trafficserver/) is a list of configurable variables used by the Traffic
Server software. Many of the variables in records.config are set automatically when you
set configuration options with traffic_ctl config set. After you modify records.config,
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.
FORMAT
Each variable has the following format:
CONFIG variable_name DATATYPE variable_value
Data Type
A variable's type is defined by the DATATYPE and must be one of:
┌───────┬──────────────────────────────────┐
│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). │
├───────┼──────────────────────────────────┤
│STRING │ String of characters up to the │
│ │ first newline. No quoting │
│ │ necessary. │
└───────┴──────────────────────────────────┘
Values
The variable_value must conform to the variable's type. For STRING, this is simply any
character data until the first newline.
For integer (INT) variables, 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 │
├───────┼─────────────┼──────────────────────────┤
│K │ Kilobytes │ 1,024 bytes │
├───────┼─────────────┼──────────────────────────┤
│M │ Megabytes │ 1,048,576 bytes (10242) │
├───────┼─────────────┼──────────────────────────┤
│G │ Gigabytes │ 1,073,741,824 bytes │
│ │ │ (10243) │
├───────┼─────────────┼──────────────────────────┤
│T │ Terabytes │ 1,099,511,627,776 bytes │
│ │ │ (10244) │
└───────┴─────────────┴──────────────────────────┘
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.
EXAMPLES
In the following example, the variable proxy.config.proxy_name is a STRING datatype with
the value my_server. This means that the name of the Traffic Server proxy is my_server.
CONFIG proxy.config.proxy_name STRING my_server
If the server name should be that_server the line would be
CONFIG proxy.config.proxy_name STRING that_server
In the following example, the variable proxy.config.arm.enabled is a yes/no flag. A value
of 0 (zero) disables the option; a value of 1 enables the option.
CONFIG proxy.config.arm.enabled INT 0
In the following example, the variable sets the time to wait for a DNS response to 10
seconds.
CONFIG proxy.config.hostdb.lookup_timeout INT 10
The last examples configures a 64GB RAM cache, using a human readable prefix.
CONFIG proxy.config.cache.ram_cache.size INT 64G
ENVIRONMENT OVERRIDES
Every records.config configuration variable can be overridden by a corresponding
environment variable. This can be useful in situations where you need a static
records.config but still want to tweak one or two settings. The override variable is
formed by converting the records.config 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.config or applied with traffic_ctl.
For example, we could override the proxy.config.product_company variable like this:
$ PROXY_CONFIG_PRODUCT_COMPANY=example traffic_manager &
$ traffic_ctl config get proxy.config.product_company
CONFIGURATION VARIABLES
The following list describes the configuration variables available in the records.config
file.
System Variables
proxy.config.product_company
Scope CONFIG.TP Type STRING.TP Default Apache Software Foundation.UNINDENT The name of
the organization developing Traffic Server.
proxy.config.product_vendor
Scope CONFIG.TP Type STRING.TP Default Apache.UNINDENT The name of the vendor providing
Traffic Server.
proxy.config.product_name
Scope CONFIG.TP Type STRING.TP Default |TS|.UNINDENT The name of the product.
proxy.config.proxy_name
Scope CONFIG.TP Type STRING.TP Default build_machine.TP Reloadable Yes.UNINDENT The name
of the Traffic Server node.
proxy.config.bin_path
Scope CONFIG.TP Type STRING.TP Default bin.UNINDENT The location of the Traffic Server
bin directory.
proxy.config.proxy_binary
Scope CONFIG.TP Type STRING.TP Default traffic_server.UNINDENT The name of the executable
that runs the traffic_server process.
If you want to set Environment Variables for traffic_server process, use a wrapper
script like below.
CONFIG proxy.config.proxy_binary STRING start_traffic_server.sh
#!/bin/sh
export ASAN_OPTIONS=detect_leaks=1
/opt/ats/bin/traffic_server "$@"
proxy.config.proxy_binary_opts
Scope CONFIG.TP Type STRING.TP Default -M.UNINDENT The command-line options for starting
Traffic Server.
proxy.config.manager_binary
Scope CONFIG.TP Type STRING.TP Default traffic_manager.UNINDENT The name of the
executable that runs the traffic_manager process.
proxy.config.memory.max_usage
Scope CONFIG.TP Type INT.TP Default 0.TP Units bytes.UNINDENT Throttle incoming
connections if resident memory usage exceeds this value. Setting the option to 0
disables the feature.
proxy.config.env_prep
Scope CONFIG.TP Type STRING.TP Default *NONE*.UNINDENT The script executed before the
traffic_manager process spawns the traffic_server process.
proxy.config.syslog_facility
Scope CONFIG.TP Type STRING.TP Default LOG_DAEMON.UNINDENT 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
Scope CONFIG.TP Type STRING.TP Default traffic.out.UNINDENT 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 and
traffic_manager process output that is set via the --bind_stdout and --bind_stderr
command-line options. proxy.config.output.logfile 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.TP Type STRING.TP Default rw-r--r--.UNINDENT 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. │
├──────┼─────────────────────┤
│r │ Read permission. │
├──────┼─────────────────────┤
│w │ Write permission. │
├──────┼─────────────────────┤
│x │ 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.TP Type INT.TP Default 0.TP Reloadable Yes.UNINDENT Specifies how the output
log is rolled. You can specify the following values:
┌──────┬──────────────────────────────────────────────────┐
│Value │ Description │
├──────┼──────────────────────────────────────────────────┤
│0 │ Disables output log rolling. │
├──────┼──────────────────────────────────────────────────┤
│1 │ 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. │
├──────┼──────────────────────────────────────────────────┤
│2 │ Enables output log rolling when the output log │
│ │ reaches a specific size (specified with │
│ │ proxy.config.output.logfile.rolling_size_mb). │
├──────┼──────────────────────────────────────────────────┤
│3 │ 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.TP Type INT.TP Default 3600.TP Units seconds.TP Reloadable Yes.UNINDENT
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.TP Type INT.TP Default 100.TP Units megabytes.TP Reloadable Yes.UNINDENT
Specifies at what size to roll the output log at.
proxy.config.output.logfile.rolling_min_count
Scope CONFIG.TP Type INT.TP Default 0.TP Reloadable Yes.UNINDENT 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
Scope CONFIG.TP Type INT.TP Default 1.UNINDENT When enabled (the default, 1), Traffic
Server scales threads according to the available CPU cores. See the config option
below.
proxy.config.exec_thread.autoconfig.scale
Scope CONFIG.TP Type FLOAT.TP Default 1.0.UNINDENT 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.TP Type INT.TP Default 2.UNINDENT The number of threads Traffic Server will
create if proxy.config.exec_thread.autoconfig is set to 0, otherwise this option is
ignored.
proxy.config.exec_thread.listen
Scope CONFIG.TP Type INT.TP Default 0.UNINDENT If enabled (1) all the exec_threads listen
for incoming connections. proxy.config.accept_threads should be disabled to enable
this variable.
proxy.config.accept_threads
Scope CONFIG.TP Type INT.TP Default 1.UNINDENT The number of accept threads. If disabled
(0), then accepts will be done in each of the worker threads.
┌───────────────┬────────────────────┬──────────────────────────┐
│accept_threads │ exec_thread.listen │ Effect │
├───────────────┼────────────────────┼──────────────────────────┤
│0 │ 0 │ All worker threads │
│ │ │ accept new connections │
│ │ │ and share listen fd. │
├───────────────┼────────────────────┼──────────────────────────┤
│1 │ 0 │ New connections are │
│ │ │ accepted on a dedicated │
│ │ │ accept thread and │
│ │ │ distributed to worker │
│ │ │ threads in round robin │
│ │ │ fashion. │
├───────────────┼────────────────────┼──────────────────────────┤
│0 │ 1 │ 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.TP Type INT.TP Default 1048576.UNINDENT Default thread stack size, in bytes,
for all threads (default is 1 MB).
proxy.config.exec_thread.affinity
Scope CONFIG.TP Type INT.TP Default 1.UNINDENT Bind threads to specific processing units.
┌──────┬──────────────────────────────────┐
│Value │ Effect │
├──────┼──────────────────────────────────┤
│0 │ Assign threads to machine. │
├──────┼──────────────────────────────────┤
│1 │ Assign threads to NUMA nodes │
│ │ [default]. │
├──────┼──────────────────────────────────┤
│2 │ Assign threads to sockets. │
├──────┼──────────────────────────────────┤
│3 │ Assign threads to cores. │
├──────┼──────────────────────────────────┤
│4 │ Assign threads to processing │
│ │ units. │
└──────┴──────────────────────────────────┘
NOTE:
This option only has an affect when Traffic Server has been compiled with
--enable-hwloc.
proxy.config.system.file_max_pct
Scope CONFIG.TP Type FLOAT.TP Default 0.9.UNINDENT 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.TP Type STRING.TP Default traffic_crashlog.UNINDENT 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.active_client_threshold
Scope CONFIG.TP Type INT.TP Default 0.TP Reloadable Yes.UNINDENT This setting specifies
the number of active client connections for use by traffic_ctl server restart
--drain.
proxy.config.restart.stop_listening
Scope CONFIG.TP Type INT.TP Default 0.TP Reloadable Yes.UNINDENT This option specifies
whether Traffic Server should close listening sockets while shutting down
gracefully.
┌──────┬──────────────────────────────────┐
│Value │ Description │
├──────┼──────────────────────────────────┤
│0 │ Listening sockets will be kept │
│ │ open. │
├──────┼──────────────────────────────────┤
│1 │ Listening sockets will be closed │
│ │ when Traffic Server starts │
│ │ shutting down. │
└──────┴──────────────────────────────────┘
proxy.config.stop.shutdown_timeout
Scope CONFIG.TP Type INT.TP Default 0.TP Reloadable Yes.UNINDENT 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.TP Type INT.TP Default 60.TP Units milliseconds.UNINDENT 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.connections_throttle
Scope CONFIG.TP Type INT.TP Default 30000.UNINDENT 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.TP Type INT.TP Default 30000.UNINDENT 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.
proxy.config.net.max_requests_in
Scope CONFIG.TP Type INT.TP Default 0.UNINDENT 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.TP Type INT.TP Default 86400.TP Reloadable Yes.UNINDENT 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.
See Timeout Settings for more discussion on Traffic Server timeouts.
proxy.config.net.inactivity_check_frequency
Scope CONFIG.TP Type INT.TP Default 1.UNINDENT 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.local.incoming_ip_to_bind
Scope LOCAL.TP Type STRING.TP Default 0.0.0.0 [::].UNINDENT 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:
LOCAL proxy.local.incoming_ip_to_bind STRING 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:
LOCAL proxy.local.incoming_ip_to_bind STRING 192.168.101.18 [fc07:192:168:101::17]
proxy.local.outgoing_ip_to_bind
Scope LOCAL.TP Type STRING.TP Default 0.0.0.0 [::].UNINDENT 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.:
LOCAL proxy.local.outgoing_ip_to_bind STRING 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.:
LOCAL proxy.local.outgoing_ip_to_bind STRING 192.168.101.17 [fc07:192:168:101::17]
proxy.config.net.event_period
Scope CONFIG.TP Type INT.TP Default 10.UNINDENT 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.TP Type INT.TP Default 10.UNINDENT 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.TP Type INT.TP Default 10.TP Reloadable Yes.UNINDENT 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.TP Type INT.TP Default 50.TP Reloadable Yes.UNINDENT When we trigger a
throttling scenario, this how long our accept() are delayed.
LOCAL MANAGER
proxy.node.config.manager_log_filename
Scope CONFIG.TP Type STRING.TP Default manager.log.UNINDENT The name of the file to which
traffic_manager logs will be emitted.
If this is set to stdout or stderr, then all traffic_manager logging will go to the
stdout or stderr stream, respectively.
proxy.config.admin.user_id
Scope CONFIG.TP Type STRING.TP Default nobody.UNINDENT 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.TP Type INT.TP Default 0.UNINDENT This setting specifies whether the
management API should be restricted to root processes. If this is set to 0, then on
platforms that support passing process credentials, non-root processes will be
allowed to make read-only management API calls. Any management API calls that
modify server state (eg. setting a configuration variable) will still be restricted
to root processes.
This setting is not reloadable, since it is must be applied when traffic_manager
initializes.
proxy.config.track_config_files
Scope CONFIG.TP Type INT.TP Default 1.UNINDENT Enables (1) or disables (0) tracking
configuration file updates. This setting is enabled by default, meaning that
configuration files are monitored for changes. Having tracking enabled is a
dependency for traffic_ctl config status to function. However, tracking the files
is implemented via a frequent call to stat() which may be problematic in some
deployments. If the call to stat() on configuration files causes problems, then it
can be avoided by setting this value to 0 at the cost of disabling the config
status feature for traffic_ctl.
This setting is not reloadable, since it is must be applied when traffic_manager
initializes.
proxy.node.config.manager_exponential_sleep_ceiling
Scope CONFIG.TP Type INT.TP Default 60.UNINDENT In case of traffic_manager is unable to
start traffic_server, this setting specifies the maximum amount of seconds that the
traffic_manager process should wait until it tries again to restart traffic_server.
In case of traffic_manager failing to start traffic_server, it will retry
exponentially until it reaches the ceiling time.
proxy.node.config.manager_retry_cap
Scope CONFIG.TP Type INT.TP Default 5.UNINDENT This setting specifies the number of times
that traffic_manager will retry to restart traffic_server once the maximum ceiling
time is reached.
NOTE:
If set to 0, no cap will take place.
ALARM CONFIGURATION
proxy.config.alarm.abs_path
Scope CONFIG.TP Type STRING.TP Default NULL.TP Reloadable Yes.UNINDENT The absolute path
to the directory containing the alarm script. If this is not set, the script will
be located relative to proxy.config.bin_path.
proxy.config.alarm.script_runtime
Scope CONFIG.TP Type INT.TP Default 5.TP Reloadable Yes.UNINDENT The number of seconds
that Traffic Server allows the alarm script to run before aborting it.
HTTP ENGINE
proxy.config.http.server_ports
Scope CONFIG.TP Type STRING.TP Default 8080 8080:ipv6.UNINDENT 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 │
├───────────┼─────────────────┼──────────────────────────┤
│number │ Required │ The local port. │
└───────────┴─────────────────┴──────────────────────────┘
│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. │
├───────────┼─────────────────┼──────────────────────────┤
│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. │
└───────────┴─────────────────┴──────────────────────────┘
number Local IP port to bind. This is the port to which ATS clients will connect.
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.
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, all
incoming requests must be prefaced with the PROXY header. 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.local.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.local.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.local.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.local.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 https://multipath-tcp.org.
Example
Listen on port 80 on any address for IPv4 and IPv6.:
80 80:ipv6
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:1::1]: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.local.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:1::1]: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.TP Type STRING.TP Default 443.UNINDENT The range of origin server ports that
can be used for tunneling via CONNECT.
Traffic Server allows tunnels only to the specified ports. Supports both wildcards
(*) and ranges (e.g. 0-1023).
NOTE:
These are the ports on the origin server, not Traffic Server proxy ports.
proxy.config.http.forward_connect_method
Scope CONFIG.TP Type INT.TP Default 0.TP Reloadable Yes.TP Overridable Yes.UNINDENT 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.local.http.parent_proxy.disable_connect_tunneling to 0 when parent proxying
is enabled.
proxy.config.http.insert_request_via_str
Scope CONFIG.TP Type INT.TP Default 1.TP Reloadable Yes.TP Overridable Yes.UNINDENT Set
how the Via field is handled on a request to the origin server.
┌──────┬──────────────────────────────────┐
│Value │ Effect │
├──────┼──────────────────────────────────┤
│0 │ Do not modify or set this Via │
│ │ header. │
├──────┼──────────────────────────────────┤
│1 │ Add the basic protocol and proxy │
│ │ identifier. │
├──────┼──────────────────────────────────┤
│2 │ Add basic transaction codes. │
├──────┼──────────────────────────────────┤
│3 │ Add detailed transaction codes. │
├──────┼──────────────────────────────────┤
│4 │ 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.TP Type STRING.TP Default ApacheTrafficServer/${PACKAGE_VERSION}.TP
Reloadable Yes.TP Overridable Yes.UNINDENT 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 0. 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.config file. If you want to hide the version, you can set
this value to ApacheTrafficServer.
proxy.config.http.insert_response_via_str
Scope CONFIG.TP Type INT.TP Default 0.TP Reloadable Yes.TP Overridable Yes.UNINDENT Set
how the Via field is handled on the response to the client.
┌──────┬──────────────────────────────────┐
│Value │ Effect │
├──────┼──────────────────────────────────┤
│0 │ Do not modify or set this Via │
│ │ header. │
├──────┼──────────────────────────────────┤
│1 │ Add the basic protocol and proxy │
│ │ identifier. │
├──────┼──────────────────────────────────┤
│2 │ Add basic transaction codes. │
├──────┼──────────────────────────────────┤
│3 │ Add detailed transaction codes. │
├──────┼──────────────────────────────────┤
│4 │ 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.TP Type STRING.TP Default ApacheTrafficServer/${PACKAGE_VERSION}.TP
Reloadable Yes.TP Overridable Yes.UNINDENT 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 0. 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.config file. If you want to hide the version, you can set
this value to ApacheTrafficServer.
proxy.config.http.send_100_continue_response
Scope CONFIG.TP Type INT.TP Default 0.TP Reloadable Yes.UNINDENT You can specify one of
the following:
┌──────┬──────────────────────────────────┐
│Value │ Description │
├──────┼──────────────────────────────────┤
│0 │ Traffic Server will buffer the │
│ │ request until the post body has │
│ │ been received and then send the │
│ │ request to the origin server. │
├──────┼──────────────────────────────────┤
│1 │ Immediately return a 100 │
│ │ Continue from Traffic Server │
│ │ without waiting for the post │
│ │ body. │
└──────┴──────────────────────────────────┘
proxy.config.http.response_server_enabled
Scope CONFIG.TP Type INT.TP Default 1.TP Reloadable Yes.TP Overridable Yes.UNINDENT You
can specify one of the following:
┌──────┬────────────────────────────────────────┐
│Value │ Description │
├──────┼────────────────────────────────────────┤
│0 │ No Server header is added to the │
│ │ response. │
├──────┼────────────────────────────────────────┤
│1 │ The Server header is added │
│ │ according to │
│ │ proxy.config.http.response_server_str. │
├──────┼────────────────────────────────────────┤
│2 │ The Server header is added only if the │
│ │ response from origin does not have one │
│ │ already. │
└──────┴────────────────────────────────────────┘
proxy.config.http.response_server_str
Scope CONFIG.TP Type STRING.TP Default ATS/${PACKAGE_VERSION}.TP Reloadable Yes.TP
Overridable Yes.UNINDENT 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.config. If you want
to hide the version, you can set this value to ATS.
proxy.config.http.insert_age_in_response
Scope CONFIG.TP Type INT.TP Default 1.TP Reloadable Yes.TP Overridable Yes.UNINDENT 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 │
├──────┼─────────────────────────┤
│0 │ No Age header is added. │
├──────┼─────────────────────────┤
│1 │ Age header is added. │
└──────┴─────────────────────────┘
proxy.config.http.chunking_enabled
Scope CONFIG.TP Type INT.TP Default 1.TP Reloadable Yes.TP Overridable Yes.UNINDENT
Specifies whether Traffic Server can generate a chunked response:
┌──────┬──────────────────────────────────┐
│Value │ Description │
├──────┼──────────────────────────────────┤
│0 │ Never respond with chunked │
│ │ encoding. │
├──────┼──────────────────────────────────┤
│1 │ Always respond with chunked │
│ │ encoding. │
├──────┼──────────────────────────────────┤
│2 │ Generate a chunked response if │
│ │ the origin server has previously │
│ │ returned HTTP/1.1. │
├──────┼──────────────────────────────────┤
│3 │ 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.TP Type INT.TP Default 4096.TP Overridable Yes.UNINDENT 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.send_http11_requests
Scope CONFIG.TP Type INT.TP Default 1.TP Reloadable Yes.TP Overridable Yes.UNINDENT
Specifies when and how Traffic Server uses HTTP/1.1 to communicate with the origin
server.
┌──────┬──────────────────────────────────┐
│Value │ Description │
├──────┼──────────────────────────────────┤
│0 │ Never use HTTP/1.1. │
├──────┼──────────────────────────────────┤
│1 │ Always use HTTP/1.1. │
├──────┼──────────────────────────────────┤
│2 │ Use HTTP/1.1 with origin │
│ │ connections only if the server │
│ │ has previously returned │
│ │ HTTP/1.1. │
├──────┼──────────────────────────────────┤
│3 │ 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 1, then options 2 and 3 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.TP Type INT.TP Default 1.TP Overridable Yes.UNINDENT If enabled (1) anytime
a request contains a Authorization, Proxy-Authorization, or Www-Authenticate header
the connection will be closed and not reused. This marks the connection as private.
When disabled (0) the connection will be available for reuse.
proxy.config.http.server_session_sharing.match
Scope CONFIG.TP Type STRING.TP Default both.TP Overridable Yes.UNINDENT 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.TP Type STRING.TP Default thread.UNINDENT 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. │
└───────┴──────────────────────────────────┘
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.
proxy.config.http.attach_server_session_to_client
Scope CONFIG.TP Type INT.TP Default 0.TP Overridable Yes.UNINDENT 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 0 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 0 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.TP Type INT.TP Default 0.TP Overridable Yes.UNINDENT Control the proxy cycle
detection function in the following manner --
If this setting is 0, 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 1 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 0, 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 1, 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.TP Type INT.TP Default 0.UNINDENT 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 │
├──────┼──────────────────────────────────┤
│0 │ Disables the feature. │
├──────┼──────────────────────────────────┤
│1 │ 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. │
├──────┼──────────────────────────────────┤
│2 │ 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:
1. 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.
2. 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.TP Type INT.TP Default 1.TP Overridable Yes.UNINDENT Enables (1) or disables
(0) incoming keep-alive connections.
proxy.config.http.keep_alive_enabled_out
Scope CONFIG.TP Type INT.TP Default 1.TP Overridable Yes.UNINDENT Enables (1) or disables
(0) 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.TP Type INT.TP Default 1.TP Overridable Yes.UNINDENT Controls whether new
POST requests re-use keep-alive sessions (1) or create new connections per request
(0).
proxy.config.http.disallow_post_100_continue
Scope CONFIG.TP Type INT.TP Default 0.UNINDENT 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.TP Type INT.TP Default 8.TP Reloadable Yes.TP Overridable Yes.UNINDENT
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.TP Type INT.TP Default 32768.TP Reloadable Yes.TP Overridable Yes.UNINDENT
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.TP Type INT.TP Default 0.TP Overridable Yes.UNINDENT 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.TP Type INT.TP Default 65535.TP Reloadable Yes.UNINDENT 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.TP Type INT.TP Default 131070.TP Reloadable Yes.UNINDENT 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.TP Type INT.TP Default 131072.TP Reloadable Yes.TP Overridable Yes.UNINDENT
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.TP Type INT.TP Default 131072.TP Reloadable Yes.TP Overridable Yes.UNINDENT
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.TP Type STRING.TP Default null.TP Overridable Yes.UNINDENT 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.TP Type INT.TP Default 2.UNINDENT Takes a value between 0 and 2. 0 disables
strict_uri_parsing. Any character can appears in the URI. 1 causes Traffic Server
to return 400 Bad Request if client's request URI includes character which is not
RFC 3986 compliant. 2 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.TP Type INT.TP Default 1.TP Reloadable Yes.UNINDENT Enables (1) or disables
(0) the logging of responses to bad requests to the error logging destination.
Disabling this option prevents error responses (such as 403s) 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.TP Type INT.TP Default 300.TP Reloadable Yes.TP Overridable Yes.UNINDENT 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.TP Type INT.TP Default 2.UNINDENT 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.TP Type INT.TP Default 10.TP Reloadable Yes.TP Overridable Yes.UNINDENT 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.TP Type INT.TP Default 4.TP Reloadable Yes.TP Overridable Yes.UNINDENT 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.TP Type INT.TP Default 2.TP Reloadable Yes.TP Overridable Yes.UNINDENT The
total number of connection attempts allowed per parent for a specific transaction,
if multiple parents are used.
proxy.config.http.parent_proxy.connect_attempts_timeout
Scope CONFIG.TP Type INT.TP Default 30.TP Reloadable Yes.TP Overridable Yes.UNINDENT The
timeout value (in seconds) for parent cache connection attempts.
See Timeout Settings for more discussion on Traffic Server timeouts.
proxy.config.http.parent_proxy.mark_down_hostdb
Scope CONFIG.TP Type INT.TP Default 0.TP Reloadable Yes.TP Overridable Yes.UNINDENT
Enables (1) or disables (0) 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.TP Type INT.TP Default 0.TP Reloadable Yes.TP Overridable Yes.UNINDENT
Configures Traffic Server to send proxy authentication headers on to the parent
cache.
proxy.config.http.no_dns_just_forward_to_parent
Scope CONFIG.TP Type INT.TP Default 0.TP Reloadable Yes.UNINDENT Don't try to resolve
DNS, forward all DNS requests to the parent. This is off (0) by default.
proxy.local.http.parent_proxy.disable_connect_tunneling
Scope CONFIG.TP Type INT.TP Default 0.UNINDENT
proxy.config.http.parent_proxy.self_detect
Scope CONFIG.TP Type INT.TP Default 2.UNINDENT 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 │
├──────┼──────────────────────────────────┤
│0 │ Disables the feature by not │
│ │ checking for matches. │
├──────┼──────────────────────────────────┤
│1 │ Remove the matching host from │
│ │ the list. │
├──────┼──────────────────────────────────┤
│2 │ Mark the host down. This is the │
│ │ default. │
└──────┴──────────────────────────────────┘
proxy.config.http.parent_proxy.enable_parent_timeout_markdowns
Scope CONFIG.TP Type INT.TP Default 0.TP Reloadable Yes.TP Overridable Yes.UNINDENT
Enables (1) or disables (0) 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 (0). 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.TP Type INT.TP Default 0.TP Reloadable Yes.TP Overridable Yes.UNINDENT
Enables (1) or disables (0) 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.TP Type INT.TP Default 120.TP Reloadable Yes.TP Overridable Yes.UNINDENT
Specifies how long Traffic Server keeps connections to clients open for a
subsequent request after a transaction ends. A value of 0 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.TP Type INT.TP Default 120.TP Reloadable Yes.TP Overridable Yes.UNINDENT
Specifies how long Traffic Server keeps connections to origin servers open for a
subsequent transfer of data after a transaction ends. A value of 0 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.TP Type INT.TP Default 30.TP Reloadable Yes.TP Overridable Yes.UNINDENT
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.TP Type INT.TP Default 30.TP Reloadable Yes.TP Overridable Yes.UNINDENT
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.TP Type INT.TP Default 600.TP Reloadable Yes.TP Overridable Yes.UNINDENT
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.TP Type INT.TP Default 3600.TP Reloadable Yes.TP Overridable Yes.UNINDENT
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.TP Type INT.TP Default 900.TP Reloadable Yes.TP Overridable Yes.UNINDENT 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 0 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.TP Type INT.TP Default 0.TP Reloadable Yes.TP Overridable Yes.UNINDENT 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 0 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.TP Type INT.TP Default 120.TP Reloadable Yes.UNINDENT 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.TP Type INT.TP Default 0.TP Reloadable Yes.TP Overridable Yes.UNINDENT
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.TP Type FLOAT.TP Default 0.0.TP Reloadable Yes.TP Overridable Yes.UNINDENT
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.TP Type INT.TP Default 0.TP Reloadable Yes.TP Overridable Yes.UNINDENT 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.TP Type INT.TP Default 1.TP Reloadable Yes.UNINDENT 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.TP Type INT.TP Default 0.TP Reloadable Yes.TP Overridable Yes.UNINDENT 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.TP Type INT.TP Default 2048.TP Reloadable Yes.UNINDENT 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.TP Type STRING.TP Default routable:follow.TP Reloadable Yes.UNINDENT 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.TP Type INT.TP Default 3.TP Reloadable Yes.TP Overridable Yes.UNINDENT 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 dead (as controlled by
proxy.config.http.connect.dead.policy. After this, the setting
proxy.config.http.connect_attempts_max_retries_dead_server is used to limit the
number of retry attempts to the known dead origin.
proxy.config.http.connect_attempts_max_retries_dead_server
Scope CONFIG.TP Type INT.TP Default 1.TP Reloadable Yes.TP Overridable Yes.UNINDENT
Maximum number of connection attempts Traffic Server can make while an origin is
marked dead 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 dead origin. The timeout interval
proxy.config.http.connect_attempts_timeout in seconds is used with this setting.
proxy.config.http.connect.dead.policy
Scope CONFIG.TP Type INT.TP Default 2.TP Overridable Yes.UNINDENT Controls what origin
server connection failures contribute to marking a server dead. When set to 2, any
connection failure during the TCP and TLS handshakes will contribute to marking the
server dead. When set to 1, only TCP handshake failures will contribute to marking
a server dead. When set to 0, no connection failures will be used towards marking
a server dead.
proxy.config.http.server_max_connections
Scope CONFIG.TP Type INT.TP Default 0.TP Reloadable Yes.UNINDENT Limits the number of
socket connections across all origin servers to the value specified. To disable,
set to zero (0).
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.TP Type INT.TP Default 0.TP Reloadable Yes.TP Overridable Yes.UNINDENT Set a
limit for the number of concurrent connections to an upstream server group. A value
of 0 disables checking. If a transaction attempts to connect to a group which
already has the maximum number of concurrent connections the transaction either
rechecks after a delay or a 503 (HTTP_STATUS_SERVICE_UNAVAILABLE) error response is
sent to the user agent. To configure
Number of transactions that can be delayed concurrently
See proxy.config.http.per_server.connection.queue_size.
How long to delay before rechecking
See proxy.config.http.per_server.connection.queue_delay.
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.TP Type STRING.TP Default both.TP Reloadable Yes.TP Overridable Yes.UNINDENT
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 0.
NOTE:
This setting is independent of the setting for upstream session sharing matching.
proxy.config.http.per_server.connection.queue_size
Scope CONFIG.TP Type INT.TP Default 0.TP Reloadable Yes.UNINDENT Controls the number of
transactions that can be waiting on an upstream server group.
-1 Unlimited.
0 Never wait. If the connection maximum has been reached immediately respond with an
error.
A positive number
If there are less than this many waiting transactions, delay this transaction and
try again. Otherwise respond immediately with an error.
proxy.config.http.per_server.connection.queue_delay
Scope CONFIG.TP Type INT.TP Default 100.TP Units milliseconds.TP Reloadable Yes.UNINDENT
If a transaction is delayed due to too many connections in an upstream server
group, delay this amount of time before checking again.
proxy.config.http.per_server.connection.alert_delay
Scope CONFIG.TP Type INT.TP Default 60.TP Units seconds.TP Reloadable Yes.UNINDENT
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.TP Type INT.TP Default 0.TP Reloadable Yes.TP Overridable Yes.UNINDENT 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.TP Type INT.TP Default 3.TP Reloadable Yes.TP Overridable Yes.UNINDENT 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.TP Type INT.TP Default 30.TP Reloadable Yes.TP Overridable Yes.UNINDENT 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_connect_attempts_timeout
Scope CONFIG.TP Type INT.TP Default 1800.TP Reloadable Yes.TP Overridable Yes.UNINDENT
The timeout value (in seconds) for an origin server connection when the client
request is a POST or PUT request.
See Timeout Settings for more discussion on Traffic Server timeouts.
proxy.config.http.post.check.content_length.enabled
Scope CONFIG.TP Type INT.TP Default 1.UNINDENT Enables (1) or disables (0) checking the
Content-Length: Header for a POST request.
proxy.config.http.down_server.cache_time
Scope CONFIG.TP Type INT.TP Default 60.TP Reloadable Yes.TP Overridable Yes.UNINDENT
Specifies how long (in seconds) Traffic Server remembers that an origin server was
unreachable.
proxy.config.http.uncacheable_requests_bypass_parent
Scope CONFIG.TP Type INT.TP Default 1.TP Reloadable Yes.TP Overridable Yes.UNINDENT 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.TP Type INT.TP Default 0.TP Overridable Yes.UNINDENT 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.TP Type INT.TP Default 0.TP Units bytes.TP Overridable Yes.UNINDENT 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.TP Type INT.TP Default 0.TP Units bytes.TP Overridable Yes.UNINDENT 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.TP Type INT.TP Default -1.TP Reloadable Yes.UNINDENT When enabled >= (0),
Traffic Server will enforce a maximum number of simultaneous websocket connections.
NEGATIVE RESPONSE CACHING
proxy.config.http.negative_caching_enabled
Scope CONFIG.TP Type INT.TP Default 0.TP Reloadable Yes.TP Overridable Yes.UNINDENT When
enabled (1), 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 (0), 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.TP Type INT.TP Default 1800.TP Reloadable Yes.TP Overridable Yes.UNINDENT
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.TP Type STRING.TP Default 204 305 403 404 414 500 501 502 503 504.TP
Reloadable Yes.UNINDENT 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.TP Type INT.TP Default 1.TP Reloadable Yes.TP Overridable Yes.UNINDENT
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.
A value of 0 disables serving stale content and a value of 1 enables keeping and
serving stale content if revalidation fails.
proxy.config.http.negative_revalidating_lifetime
Scope CONFIG.TP Type INT.TP Default 1800.UNINDENT 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 USER VARIABLES
proxy.config.http.anonymize_remove_from
Scope CONFIG.TP Type INT.TP Default 0.TP Reloadable Yes.TP Overridable Yes.UNINDENT When
enabled (1), Traffic Server removes the From header to protect the privacy of your
users.
proxy.config.http.anonymize_remove_referer
Scope CONFIG.TP Type INT.TP Default 0.TP Reloadable Yes.UNINDENT When enabled (1),
Traffic Server removes the Referrer header to protect the privacy of your site and
users.
proxy.config.http.anonymize_remove_user_agent
Scope CONFIG.TP Type INT.TP Default 0.TP Reloadable Yes.TP Overridable Yes.UNINDENT When
enabled (1), Traffic Server removes the User-agent header to protect the privacy of
your site and users.
proxy.config.http.anonymize_remove_cookie
Scope CONFIG.TP Type INT.TP Default 0.TP Reloadable Yes.TP Overridable Yes.UNINDENT When
enabled (1), Traffic Server removes the Cookie header to protect the privacy of
your site and users.
proxy.config.http.anonymize_remove_client_ip
Scope CONFIG.TP Type INT.TP Default 0.TP Reloadable Yes.TP Overridable Yes.UNINDENT When
enabled (1), Traffic Server removes Client-IP headers for more privacy.
proxy.config.http.insert_client_ip
Scope CONFIG.TP Type INT.TP Default 1.TP Reloadable Yes.TP Overridable Yes.UNINDENT
Specifies whether Traffic Server inserts Client-IP headers to retain the client IP
address:
┌──────┬──────────────────────────────────┐
│Value │ Description │
├──────┼──────────────────────────────────┤
│0 │ Don't insert the Client-ip │
│ │ header │
├──────┼──────────────────────────────────┤
│1 │ Insert the Client-ip header, but │
│ │ only if the UA did not send one │
├──────┼──────────────────────────────────┤
│2 │ Always insert the Client-ip │
│ │ header │
└──────┴──────────────────────────────────┘
proxy.config.http.anonymize_other_header_list
Scope CONFIG.TP Type STRING.TP Default NULL.TP Reloadable Yes.UNINDENT Comma separated
list of headers Traffic Server should remove from outgoing requests.
proxy.config.http.insert_squid_x_forwarded_for
Scope CONFIG.TP Type INT.TP Default 1.TP Reloadable Yes.TP Overridable Yes.UNINDENT When
enabled (1), Traffic Server adds the client IP address to the X-Forwarded-For
header.
proxy.config.http.insert_forwarded
Scope CONFIG.TP Type STRING.TP Default none.TP Reloadable Yes.TP Overridable Yes.UNINDENT
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.TP Type STRING.TP Default ```<ip list>```.UNINDENT 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.TP Type INT.TP Default ``-1``.TP Reloadable Yes.TP Overridable Yes.UNINDENT
Set the behavior of outbound PROXY Protocol.
┌──────┬──────────────────────────────────┐
│Value │ Description │
├──────┼──────────────────────────────────┤
│-1 │ Disable (default) │
├──────┼──────────────────────────────────┤
│0 │ Forward received PROXY protocol │
│ │ to the next hop │
├──────┼──────────────────────────────────┤
│1 │ Send client information in PROXY │
│ │ protocol version 1 │
├──────┼──────────────────────────────────┤
│2 │ Send client information in PROXY │
│ │ protocol version 2 │
└──────┴──────────────────────────────────┘
proxy.config.http.normalize_ae
Scope CONFIG.TP Type INT.TP Default 1.TP Reloadable Yes.TP Overridable Yes.UNINDENT
Specifies normalization, if any, of Accept-Encoding: headers.
┌──────┬──────────────────────────────────┐
│Value │ Description │
├──────┼──────────────────────────────────┤
│0 │ No normalization. │
├──────┼──────────────────────────────────┤
│1 │ Accept-Encoding: gzip (if the │
│ │ header has gzip or x-gzip with │
│ │ any q) OR blank (for any header │
│ │ that does not include gzip) │
├──────┼──────────────────────────────────┤
│2 │ Accept-Encoding: br if the │
│ │ header has br (with any q) ELSE │
│ │ normalize as for value 1 │
├──────┼──────────────────────────────────┤
│3 │ Accept-Encoding: br, gzip (if │
│ │ the header has br and gzip (with │
│ │ any q for either) then br, gzip) │
│ │ ELSE normalize as for value 2 │
└──────┴──────────────────────────────────┘
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 or br (Brotli).
SECURITY
proxy.config.http.push_method_enabled
Scope CONFIG.TP Type INT.TP Default 0.TP Reloadable Yes.UNINDENT Enables (1) or disables
(0) 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.TP Type INT.TP Default 0.TP Reloadable Yes.UNINDENT This feature is disabled
by default with a value of (0), 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.TP Type INT.TP Default 0.TP Reloadable Yes.TP Overridable Yes.UNINDENT This
option allows the administrator to configure different behavior and handling of
requests with multiple ranges in the Range header.
┌──────┬──────────────────────────────────┐
│Value │ Description │
├──────┼──────────────────────────────────┤
│0 │ Do not allow multiple ranges, │
│ │ effectively ignoring the Range │
│ │ header │
└──────┴──────────────────────────────────┘
│1 │ Allows multiple ranges. This can │
│ │ be potentially dangerous since │
│ │ well formed requests can cause │
│ │ excessive resource consumption │
│ │ on the server. │
├──────┼──────────────────────────────────┤
│2 │ Similar to 0, except return a │
│ │ 416 error code and no response │
│ │ body. │
└──────┴──────────────────────────────────┘
proxy.config.http.host_sni_policy
Scope CONFIG.TP Type INT.TP Default 2.UNINDENT 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.config 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.
CACHE CONTROL
proxy.config.cache.enable_read_while_writer
Scope CONFIG.TP Type INT.TP Default 1.TP Reloadable Yes.UNINDENT 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 │
├──────┼──────────────────────────────────┤
│0 │ Never read while writing. │
├──────┼──────────────────────────────────┤
│1 │ Always read while writing. │
├──────┼──────────────────────────────────┤
│2 │ Always read while writing, but │
│ │ allow non-cached Range requests │
│ │ through to the origin server. │
└──────┴──────────────────────────────────┘
The 2 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.TP Type INT.TP Default 10.TP Reloadable Yes.UNINDENT 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.TP Type INT.TP Default 50.TP Reloadable Yes.UNINDENT 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.TP Type INT.TP Default 0.TP Reloadable Yes.UNINDENT 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.TP Type INT.TP Default 1.TP Reloadable Yes.TP Overridable Yes.UNINDENT
Enables (1) or disables (0) caching of HTTP requests.
proxy.config.http.cache.post_method
Scope CONFIG.TP Type INT.TP Default 0.TP Reloadable Yes.TP Overridable Yes.UNINDENT
Enables (1) or disables (0) caching of HTTP POST requests.
proxy.config.http.cache.generation
Scope CONFIG.TP Type INT.TP Default -1.TP Reloadable Yes.TP Overridable Yes.UNINDENT 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.doc_in_cache_skip_dns
Scope CONFIG.TP Type INT.TP Default 1.TP Reloadable Yes.TP Overridable Yes.UNINDENT When
enabled (1), 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 (0)
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.TP Type INT.TP Default 1.TP Reloadable Yes.TP Overridable Yes.UNINDENT When
enabled (1), 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.TP Type INT.TP Default 1.TP Reloadable Yes.TP Overridable Yes.UNINDENT When
enabled (1), 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.TP Type INT.TP Default 0.TP Reloadable Yes.TP Overridable Yes.UNINDENT When
enabled (1), 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.TP Type INT.TP Default 1.TP Reloadable Yes.TP Overridable Yes.UNINDENT
Specifies how cookies are cached:
┌──────┬──────────────────────────────────┐
│Value │ Description │
├──────┼──────────────────────────────────┤
│0 │ Do not cache any responses to │
│ │ cookies. │
├──────┼──────────────────────────────────┤
│1 │ Cache for any content-type. │
├──────┼──────────────────────────────────┤
│2 │ Cache only for image types. │
├──────┼──────────────────────────────────┤
│3 │ Cache for all but text │
│ │ content-types. │
├──────┼──────────────────────────────────┤
│4 │ 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.TP Type INT.TP Default 0.TP Overridable Yes.UNINDENT When enabled (1),
Traffic Server ignores WWW-Authentication headers in responses and the responses
are cached.
proxy.config.http.cache.cache_urls_that_look_dynamic
Scope CONFIG.TP Type INT.TP Default 1.TP Reloadable Yes.TP Overridable Yes.UNINDENT
Enables (1) or disables (0) 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.TP Type INT.TP Default 0.TP Reloadable Yes.TP Overridable Yes.UNINDENT
Specifies when to revalidate content:
┌──────┬──────────────────────────────────┐
│Value │ Description │
├──────┼──────────────────────────────────┤
│0 │ Use cache directives or │
│ │ heuristic (the default value). │
├──────┼──────────────────────────────────┤
│1 │ Stale if heuristic. │
├──────┼──────────────────────────────────┤
│2 │ Always stale (always │
│ │ revalidate). │
├──────┼──────────────────────────────────┤
│3 │ Never stale. │
├──────┼──────────────────────────────────┤
│4 │ 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.TP Type INT.TP Default 2.TP Reloadable Yes.TP Overridable Yes.UNINDENT The
type of headers required in a request for the request to be cacheable.
┌──────┬──────────────────────────────────┐
│Value │ Description │
├──────┼──────────────────────────────────┤
│0 │ No headers required to make │
│ │ document cacheable. │
├──────┼──────────────────────────────────┤
│1 │ Either the Last-Modified header, │
│ │ or an explicit lifetime header │
│ │ (Expires or Cache-Control: │
│ │ max-age) is required. │
├──────┼──────────────────────────────────┤
│2 │ Explicit lifetime is required, │
│ │ from either Expires or │
│ │ Cache-Control: max-age. │
└──────┴──────────────────────────────────┘
proxy.config.http.cache.max_stale_age
Scope CONFIG.TP Type INT.TP Default 604800.TP Reloadable Yes.TP Overridable Yes.UNINDENT
The maximum age in seconds allowed for a stale response before it cannot be cached.
proxy.config.http.cache.guaranteed_min_lifetime
Scope CONFIG.TP Type INT.TP Default 0.TP Reloadable Yes.TP Overridable Yes.UNINDENT
Establishes a guaranteed minimum lifetime boundary for object freshness. Setting
this to 0 (default) disables the feature.
proxy.config.http.cache.guaranteed_max_lifetime
Scope CONFIG.TP Type INT.TP Default 31536000.TP Reloadable Yes.TP Overridable
Yes.UNINDENT Establishes a guaranteed maximum lifetime boundary for object
freshness. Setting this to 0 disables the feature.
proxy.config.http.cache.range.lookup
Scope CONFIG.TP Type INT.TP Default 1.TP Overridable Yes.UNINDENT When enabled (1),
Traffic Server looks up range requests in the cache.
proxy.config.http.cache.range.write
Scope CONFIG.TP Type INT.TP Default 0.TP Overridable Yes.UNINDENT When enabled (1),
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.TP Type INT.TP Default 2.TP Reloadable Yes.TP Overridable Yes.UNINDENT When
enabled with a value of 1, 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 2 (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 1 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 1.
proxy.config.http.cache.ignore_accept_language_mismatch
Scope CONFIG.TP Type INT.TP Default 2.TP Reloadable Yes.TP Overridable Yes.UNINDENT When
enabled with a value of 1, 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 2 (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 1 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 1.
proxy.config.http.cache.ignore_accept_encoding_mismatch
Scope CONFIG.TP Type INT.TP Default 2.TP Reloadable Yes.TP Overridable Yes.UNINDENT When
enabled with a value of 1, 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 2 (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 1 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 1.
proxy.config.http.cache.ignore_accept_charset_mismatch
Scope CONFIG.TP Type INT.TP Default 2.TP Reloadable Yes.TP Overridable Yes.UNINDENT When
enabled with a value of 1, 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 2 (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 1 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 1.
proxy.config.http.cache.ignore_client_cc_max_age
Scope CONFIG.TP Type INT.TP Default 1.TP Reloadable Yes.TP Overridable Yes.UNINDENT When
enabled (1), 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.TP Type INT.TP Default 0.UNINDENT Specifies the maximum object size that
will be cached. 0 is unlimited.
proxy.config.cache.min_average_object_size
Scope CONFIG.TP Type INT.TP Default 8000.UNINDENT 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.permit.pinning
Scope CONFIG.TP Type INT.TP Default 0.TP Reloadable Yes.UNINDENT When enabled (1),
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.TP Type INT.TP Default 0.UNINDENT 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.TP Type INT.TP Default 0.TP Units bytes.UNINDENT 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.limits.http.max_alts
Scope CONFIG.TP Type INT.TP Default 5.UNINDENT 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.TP Type INT.TP Default 0.UNINDENT When enabled (1), 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 0).
proxy.config.cache.target_fragment_size
Scope CONFIG.TP Type INT.TP Default 1048576.UNINDENT 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.TP Type INT.TP Default 4096.TP Reloadable Yes.UNINDENT 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.
RAM CACHE
proxy.config.cache.ram_cache.size
Scope CONFIG.TP Type INT.TP Default -1.UNINDENT 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)
proxy.config.cache.ram_cache_cutoff
Scope CONFIG.TP Type INT.TP Default 4194304.UNINDENT 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)
proxy.config.cache.ram_cache.algorithm
Scope CONFIG.TP Type INT.TP Default 1.UNINDENT 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.TP Type INT.TP Default 1.UNINDENT 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. 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.TP Type INT.TP Default 0.UNINDENT 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 │
├──────┼──────────────────────────────────┤
│0 │ No compression │
├──────┼──────────────────────────────────┤
│1 │ Fastlz (extremely fast, │
│ │ relatively low compression) │
├──────┼──────────────────────────────────┤
│2 │ Libz (moderate speed, reasonable │
│ │ compression) │
├──────┼──────────────────────────────────┤
│3 │ 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.TP Type INT.TP Default 3600.TP Reloadable Yes.TP Overridable Yes.UNINDENT
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.TP Type INT.TP Default 86400.TP Reloadable Yes.TP Overridable Yes.UNINDENT
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.TP Type FLOAT.TP Default 0.10.TP Reloadable Yes.TP Overridable Yes.UNINDENT
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.TP Type INT.TP Default 10.TP Reloadable Yes.TP Overridable Yes.UNINDENT
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.TP Type INT.TP Default -1.TP Reloadable Yes.TP Overridable Yes.UNINDENT
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.TP Type INT.TP Default 1.TP Reloadable Yes.TP Overridable Yes.UNINDENT
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 5.
proxy.config.http.cache.open_write_fail_action
Scope CONFIG.TP Type INT.TP Default 0.TP Reloadable Yes.TP Overridable Yes.UNINDENT
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 │
├──────┼─────────────────────────────────────────────┤
│0 │ Default. Disable cache and go to │
│ │ origin server. │
├──────┼─────────────────────────────────────────────┤
│1 │ Return a 502 error on a cache │
│ │ miss. │
├──────┼─────────────────────────────────────────────┤
│2 │ Serve stale if object's age is │
│ │ under │
│ │ proxy.config.http.cache.max_stale_age. │
│ │ Otherwise, go to origin server. │
├──────┼─────────────────────────────────────────────┤
│3 │ Return a 502 error on a cache miss or │
│ │ serve stale on a cache revalidate if │
│ │ object's age is under │
│ │ proxy.config.http.cache.max_stale_age. │
│ │ Otherwise, go to origin server. │
├──────┼─────────────────────────────────────────────┤
│4 │ Return a 502 error on either a cache │
│ │ miss or on a revalidation. │
├──────┼─────────────────────────────────────────────┤
│5 │ 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. Note that this option may │
│ │ result in CACHE_LOOKUP_COMPLETE HOOK │
│ │ being called back more than once. │
└──────┴─────────────────────────────────────────────┘
CUSTOMIZABLE USER RESPONSE PAGES
proxy.config.body_factory.enable_customizations
Scope CONFIG.TP Type INT.TP Default 1.UNINDENT Specifies whether customizable response
pages are language specific or not:
┌──────┬──────────────────────────────────┐
│Value │ Description │
├──────┼──────────────────────────────────┤
│1 │ Enable customizable user │
│ │ response pages in the default │
│ │ directory only. │
├──────┼──────────────────────────────────┤
│2 │ Enable language-targeted user │
│ │ response pages. │
├──────┼──────────────────────────────────┤
│3 │ Enable host-targeted user │
│ │ response pages. │
└──────┴──────────────────────────────────┘
proxy.config.body_factory.enable_logging
Scope CONFIG.TP Type INT.TP Default 0.UNINDENT Enables (1) or disables (0) 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.TP Type STRING.TP Default etc/trafficserver/body_factory.UNINDENT 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.TP Type STRING.TP Default "".TP Reloadable Yes.TP Overridable Yes.UNINDENT 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.TP Type INT.TP Default 8192.TP Reloadable Yes.UNINDENT Maximum size of the
error template response page.
proxy.config.body_factory.response_suppression_mode
Scope CONFIG.TP Type INT.TP Default 0
:reloadable:
:overridable:.UNINDENT Specifies when Traffic Server suppresses generated response
pages:
┌──────┬──────────────────────────────────┐
│Value │ Description │
├──────┼──────────────────────────────────┤
│0 │ Never suppress generated │
│ │ response pages. │
├──────┼──────────────────────────────────┤
│1 │ Always suppress generated │
│ │ response pages. │
├──────┼──────────────────────────────────┤
│2 │ Suppress response pages only for │
│ │ internal traffic. │
└──────┴──────────────────────────────────┘
proxy.config.http_ui_enabled
Scope CONFIG.TP Type INT.TP Default 0.UNINDENT Specifies which http Inspector UI
endpoints to allow within remap.config:
┌──────┬──────────────────────────────────┐
│Value │ Description │
├──────┼──────────────────────────────────┤
│0 │ Disable all http UI endpoints. │
├──────┼──────────────────────────────────┤
│1 │ Enable only Cache Inspector │
│ │ endpoints. │
├──────┼──────────────────────────────────┤
│2 │ Enable only stats endpoints. │
├──────┼──────────────────────────────────┤
│3 │ Enable all http UI endpoints. │
└──────┴──────────────────────────────────┘
To enable any endpoint there needs to be an entry in remap.config which
specifically enables it. Such a line would look like:
map / http://{cache}
The following are the cache endpoints:
┌──────┬────────────────────────────────┐
│Name │ Description │
├──────┼────────────────────────────────┤
│cache │ UI to interact with the cache. │
└──────┴────────────────────────────────┘
The following are the stats endpoints:
┌───────────────┬─────────────────────────────────────┐
│Name │ Description │
├───────────────┼─────────────────────────────────────┤
│cache-internal │ Statistics about cache │
│ │ evacuation and volumes. │
├───────────────┼─────────────────────────────────────┤
│hostdb │ Lookups against the hostdb. │
├───────────────┼─────────────────────────────────────┤
│http │ HTTPSM details, this endpoint is │
│ │ also gated by │
│ │ proxy.config.http.enable_http_info. │
├───────────────┼─────────────────────────────────────┤
│net │ Lookup and listing of open │
│ │ connections. │
└───────────────┴─────────────────────────────────────┘
proxy.config.http.enable_http_info
Scope CONFIG.TP Type INT.TP Default 0.UNINDENT Enables (1) or disables (0) access to an
endpoint within proxy.config.http_ui_enabled which shows details about inflight
transactions (HttpSM).
DNS
proxy.config.dns.search_default_domains
Scope CONFIG.TP Type INT.TP Default 0.TP Reloadable Yes.UNINDENT 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 │
├──────┼──────────────────────────────────┤
│0 │ Disable local domain expansion. │
├──────┼──────────────────────────────────┤
│1 │ Enable local domain expansion. │
├──────┼──────────────────────────────────┤
│2 │ Enable local domain expansion, │
│ │ but do not split local domain │
│ │ name. │
└──────┴──────────────────────────────────┘
proxy.config.dns.splitDNS.enabled
Scope CONFIG.TP Type INT.TP Default 0.TP Reloadable Yes.UNINDENT Enables (1) or disables
(0) 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.TP Type STRING.TP Default /etc/resolv.conf.UNINDENT 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.TP Type INT.TP Default 1.TP Reloadable Yes.UNINDENT Enables (1) or disables
(0) DNS server round-robin.
proxy.config.dns.nameservers
Scope CONFIG.TP Type STRING.TP Default NULL.TP Reloadable Yes.UNINDENT 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 [::1]:9999
proxy.config.srv_enabled
Scope CONFIG.TP Type INT.TP Default 0.TP Reloadable Yes.TP Overridable Yes.UNINDENT
Enables (1) or disables (0) 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
https://my.example.com, 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.TP Type INT.TP Default 0.UNINDENT 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.TP Type INT.TP Default 0.UNINDENT 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.TP Type INT.TP Default 0.UNINDENT Three connection modes between Traffic
Server and nameservers can be set -- UDP_ONLY, TCP_RETRY, TCP_ONLY.
┌──────┬──────────────────────────────────┐
│Value │ Description │
├──────┼──────────────────────────────────┤
│0 │ UDP_ONLY: Traffic Server always │
│ │ talks to nameservers over UDP. │
├──────┼──────────────────────────────────┤
│1 │ TCP_RETRY: Traffic Server first │
│ │ UDP, retries with TCP if UDP │
│ │ response is truncated. │
├──────┼──────────────────────────────────┤
│2 │ TCP_ONLY: Traffic Server always │
│ │ talks to nameservers over TCP. │
└──────┴──────────────────────────────────┘
proxy.config.dns.max_tcp_continuous_failures
Scope CONFIG.TP Type INT.TP Default 10.UNINDENT 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.TP Type INT.TP Default 2048.UNINDENT Maximum inflight DNS queries made by
Traffic Server at any given instant
proxy.config.dns.lookup_timeout
Scope CONFIG.TP Type INT.TP Default 20.UNINDENT Time to wait for a DNS response in
seconds.
proxy.config.dns.retries
Scope CONFIG.TP Type INT.TP Default 5.UNINDENT Maximum number of retries made by Traffic
Server on a given DNS query
proxy.config.dns.local_ipv4
Scope CONFIG.TP Type STRING.TP Default NULL.UNINDENT Local IPV4 address to bind to in
order to make DNS requests
proxy.config.dns.local_ipv6
Scope CONFIG.TP Type STRING.TP Default NULL.UNINDENT Local IPV6 address to bind to in
order to make DNS requests
HOSTDB
proxy.config.hostdb.lookup_timeout
Scope CONFIG.TP Type INT.TP Default 30.TP Units seconds.TP Reloadable Yes.UNINDENT 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.TP Type INT.TP Default *NONE*.TP Units seconds.TP Reloadable Yes.UNINDENT
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.TP Type INT.TP Default 10737418240.TP Units bytes.UNINDENT 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.TP Type INT.TP Default -1.UNINDENT 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.TP Type INT.TP Default 16.UNINDENT The maximum count of DNS answers per
round robin hostdb record. The default variable is 16.
proxy.config.hostdb.ttl_mode
Scope CONFIG.TP Type INT.TP Default 0.TP Reloadable Yes.UNINDENT 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 │
├──────┼──────────────────────────────────┤
│0 │ The TTL from the DNS response. │
├──────┼──────────────────────────────────┤
│1 │ The internal timeout value. │
├──────┼──────────────────────────────────┤
│2 │ The smaller of the DNS and │
│ │ internal TTL values. The │
│ │ internal timeout value becomes a │
│ │ maximum TTL. │
├──────┼──────────────────────────────────┤
│3 │ The larger of the DNS and │
│ │ internal TTL values. The │
│ │ internal timeout value become a │
│ │ minimum TTL. │
└──────┴──────────────────────────────────┘
proxy.config.hostdb.timeout
Scope CONFIG.TP Type INT.TP Default 86400.TP Units seconds.TP Reloadable Yes.UNINDENT
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.TP Type INT.TP Default 0.UNINDENT 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.TP Type INT.TP Default 0.TP Reloadable Yes.UNINDENT Set host resolution to
use strict round robin.
When this and proxy.config.hostdb.timed_round_robin are both disabled (set to 0),
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.TP Type INT.TP Default 0.TP Reloadable Yes.UNINDENT Set host resolution to
use timed round robin.
When this and proxy.config.hostdb.strict_round_robin are both disabled (set to 0),
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 N the IP address is
rotated if more than N seconds have passed since the first time the current address
was used.
proxy.config.hostdb.host_file.path
Scope CONFIG.TP Type STRING.TP Default NULL.UNINDENT 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.TP Type INT.TP Default 86400.TP Units seconds.TP Reloadable Yes.UNINDENT 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.TP Type INT.TP Default 64.UNINDENT 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.TP Type STRING.TP Default NULL.TP Overridable Yes.UNINDENT 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.TP Type INT.TP Default 720.UNINDENT Set the interval (in seconds) in which
to re-query DNS regardless of TTL status.
proxy.config.hostdb.filename
Scope CONFIG.TP Type STRING.TP Default host.db.UNINDENT The filename to persist hostdb to
on disk.
proxy.config.cache.hostdb.sync_frequency
Scope CONFIG.TP Type INT.TP Default 0.UNINDENT Set the frequency (in seconds) to sync
hostdb to disk. If set to zero (default as of v9.0.0), we won't sync to disk ever.
Note: hostdb is synced to disk on a per-partition basis (of which there are 64).
This means that the minimum time to sync all data to disk is
proxy.config.cache.hostdb.sync_frequency * 64
LOGGING CONFIGURATION
proxy.config.log.logging_enabled
Scope CONFIG.TP Type INT.TP Default 3.TP Reloadable Yes.UNINDENT Enables and disables
event logging:
┌──────┬──────────────────────────────────┐
│Value │ Effect │
├──────┼──────────────────────────────────┤
│0 │ Logging disabled. │
├──────┼──────────────────────────────────┤
│1 │ Log errors only. │
├──────┼──────────────────────────────────┤
│2 │ Log transactions only. │
├──────┼──────────────────────────────────┤
│3 │ Dual logging (errors and │
│ │ transactions). │
└──────┴──────────────────────────────────┘
Refer to Logging for more information on event logging.
proxy.config.log.max_secs_per_buffer
Scope CONFIG.TP Type INT.TP Default 5.TP Reloadable Yes.UNINDENT 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.TP Type INT.TP Default 25000.TP Units megabytes.TP Reloadable Yes.UNINDENT
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.TP Type INT.TP Default 1000.TP Units megabytes.TP Reloadable Yes.UNINDENT
The tolerance for the log space limit (in megabytes). If the variable
proxy.config.log.auto_delete_rolled_files is set to 1 (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.TP Type STRING.TP Default localhost.TP Reloadable Yes.UNINDENT The hostname
of the machine running Traffic Server.
proxy.config.log.logfile_dir
Scope CONFIG.TP Type STRING.TP Default var/log/trafficserver.TP Reloadable Yes.UNINDENT
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.TP Type STRING.TP Default rw-r--r--.TP Reloadable Yes.UNINDENT The log file
permissions. The standard UNIX file permissions are used (owner, group, other).
Permissible values are:
┌──────┬─────────────────────┐
│Value │ Description │
├──────┼─────────────────────┤
│- │ No permissions. │
├──────┼─────────────────────┤
│r │ Read permission. │
├──────┼─────────────────────┤
│w │ Write permission. │
├──────┼─────────────────────┤
│x │ 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.TP Type INT.TP Default 1.TP Reloadable Yes.UNINDENT Specifies how log files
are rolled. You can specify the following values:
┌──────┬───────────────────────────────────────┐
│Value │ Description │
├──────┼───────────────────────────────────────┤
│0 │ Disables log file rolling. │
├──────┼───────────────────────────────────────┤
│1 │ 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). │
├──────┼───────────────────────────────────────┤
│2 │ Enables log file rolling when log │
│ │ files reach a specific size │
│ │ (specified with │
│ │ proxy.config.log.rolling_size_mb). │
├──────┼───────────────────────────────────────┤
│3 │ Enables log file rolling at specific │
│ │ intervals during the day or when log │
│ │ files reach a specific size │
│ │ (whichever occurs first). │
├──────┼───────────────────────────────────────┤
│4 │ 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.TP Type INT.TP Default 86400.TP Reloadable Yes.UNINDENT 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.TP Type INT.TP Default 0.TP Reloadable Yes.UNINDENT The file rolling offset
hour. The hour of the day that starts the log rolling period.
proxy.config.log.rolling_size_mb
Scope CONFIG.TP Type INT.TP Default 10.TP Reloadable Yes.UNINDENT 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.TP Type INT.TP Default 0.TP Reloadable Yes.UNINDENT 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.TP Type INT.TP Default 0.TP Reloadable Yes.UNINDENT 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.TP Type INT.TP Default 0.TP Reloadable Yes.UNINDENT 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 │
├──────┼──────────────────────────────────┤
│0 │ No empty log files created and │
│ │ rolled if there was nothing to │
│ │ log │
├──────┼──────────────────────────────────┤
│1 │ 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.TP Type INT.TP Default 1.TP Reloadable Yes.UNINDENT Enables (1) or disables
(0) automatic deletion of rolled files.
proxy.config.log.sampling_frequency
Scope CONFIG.TP Type INT.TP Default 1.TP Reloadable Yes.UNINDENT Configures Traffic
Server to log only a sample of transactions rather than every transaction. You can
specify the following values:
┌──────┬───────────────────────────────┐
│Value │ Description │
├──────┼───────────────────────────────┤
│1 │ Log every transaction. │
├──────┼───────────────────────────────┤
│2 │ Log every second transaction. │
├──────┼───────────────────────────────┤
│3 │ Log every third transaction. │
├──────┼───────────────────────────────┤
│n │ ... and so on... │
└──────┴───────────────────────────────┘
proxy.config.log.periodic_tasks_interval
Scope CONFIG.TP Type INT.TP Default 5.TP Units seconds.TP Reloadable Yes.UNINDENT How
often Traffic Server executes log related periodic tasks, in seconds
proxy.config.log.proxy.config.log.throttling_interval_msec
Scope CONFIG.TP Type INT.TP Default 60000.TP Units milliseconds.TP Reloadable
Yes.UNINDENT 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.TP Type INT.TP Default 0.TP Units milliseconds.TP Reloadable Yes.UNINDENT If
set to a non-zero value N then any connection that takes longer than N 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.TP Type INT.TP Default 0.TP Units milliseconds.TP Reloadable Yes.UNINDENT If
set to a non-zero value N then any HTTP/2 connection that takes longer than N
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.TP Type INT.TP Default 0.TP Units milliseconds.TP Reloadable Yes.UNINDENT If
set to a non-zero value N then any HTTP/2 stream that takes longer than N
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.TP Type STRING.TP Default logging.yaml.TP Reloadable Yes.TP Deprecated
Yes.UNINDENT 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.TP Type INT.TP Default 9216.TP Units bytes.UNINDENT 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.TP Type INT.TP Default 36864.TP Units bytes.UNINDENT 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.TP Type INT.TP Default 9216.TP Units bytes.TP Reloadable Yes.UNINDENT 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.TP Type STRING.TP Default E.UNINDENT
proxy.config.diags.output.debug
Scope CONFIG.TP Type STRING.TP Default E.UNINDENT
proxy.config.diags.output.status
Scope CONFIG.TP Type STRING.TP Default L.UNINDENT
proxy.config.diags.output.note
Scope CONFIG.TP Type STRING.TP Default L.UNINDENT
proxy.config.diags.output.warning
Scope CONFIG.TP Type STRING.TP Default L.UNINDENT
proxy.config.diags.output.error
Scope CONFIG.TP Type STRING.TP Default SL.UNINDENT
proxy.config.diags.output.fatal
Scope CONFIG.TP Type STRING.TP Default SL.UNINDENT
proxy.config.diags.output.alert
Scope CONFIG.TP Type STRING.TP Default L.UNINDENT
proxy.config.diags.output.emergency
Scope CONFIG.TP Type STRING.TP Default SL.UNINDENT 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 │
├──────┼───────────────────────────────────────┤
│O │ Log to standard output. │
├──────┼───────────────────────────────────────┤
│E │ Log to standard error. │
├──────┼───────────────────────────────────────┤
│S │ Log to syslog. │
├──────┼───────────────────────────────────────┤
│L │ 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.TP Type INT.TP Default 1.UNINDENT Annotates diagnostic messages with the
source code location. Set to 1 to enable for Debug() messages only. Set to 2 to
enable for all messages.
proxy.config.diags.debug.enabled
Scope CONFIG.TP Type INT.TP Default 0.TP Reloadable Yes.UNINDENT 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.
proxy.config.diags.debug.client_ip
Scope CONFIG.TP Type STRING.TP Default NULL.UNINDENT 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.TP Type STRING.TP Default http|dns.UNINDENT 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 │
└───────────┴──────────────────────────────────┘
Traffic Server plugins will typically log debug messages using the TSDebug() API,
passing the plugin name as the debug tag.
proxy.config.diags.debug.throttling_interval_msec
Scope CONFIG.TP Type INT.TP Default 0.TP Units milliseconds.TP Reloadable Yes.UNINDENT
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.TP Type STRING.TP Default diags.log.UNINDENT 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.TP Type STRING.TP Default error.log.UNINDENT 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.TP Type STRING.TP Default rw-r--r--.UNINDENT The log file permissions. The
standard UNIX file permissions are used (owner, group, other). Permissible values
are:
┌──────┬─────────────────────┐
│Value │ Description │
├──────┼─────────────────────┤
│- │ No permissions. │
├──────┼─────────────────────┤
│r │ Read permission. │
├──────┼─────────────────────┤
│w │ Write permission. │
├──────┼─────────────────────┤
│x │ 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.TP Type INT.TP Default 0.TP Reloadable Yes.UNINDENT Specifies how the
diagnostics log is rolled. You can specify the following values:
┌──────┬───────────────────────────────────────────────────┐
│Value │ Description │
├──────┼───────────────────────────────────────────────────┤
│0 │ Disables diagnostics log │
│ │ rolling. │
├──────┼───────────────────────────────────────────────────┤
│1 │ Enables diagnostics log rolling │
│ │ at specific intervals (specified │
│ │ with │
│ │ proxy.config.diags.logfile.rolling_interval_sec). │
│ │ The "clock" starts ticking on │
│ │ Traffic Server startup. │
├──────┼───────────────────────────────────────────────────┤
│2 │ Enables diagnostics log rolling when the │
│ │ diagnostics log reaches a specific size │
│ │ (specified with │
│ │ proxy.config.diags.logfile.rolling_size_mb). │
└──────┴───────────────────────────────────────────────────┘
│3 │ 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.TP Type INT.TP Default 3600.TP Units seconds.TP Reloadable Yes.UNINDENT
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.TP Type INT.TP Default 100.TP Units megabytes.TP Reloadable Yes.UNINDENT
Specifies at what size to roll the diagnostics log at.
proxy.config.diags.logfile.rolling_min_count
Scope CONFIG.TP Type INT.TP Default 0.TP Reloadable Yes.UNINDENT 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.TP Type INT.TP Default 1.TP Reloadable Yes.UNINDENT Enables (1) or disables
(0) HTTP reverse proxy.
proxy.config.header.parse.no_host_url_redirect
Scope CONFIG.TP Type STRING.TP Default NULL.TP Reloadable Yes.UNINDENT The URL to which
to redirect requests with no host headers (reverse proxy).
URL REMAP RULES
proxy.config.url_remap.filename
Scope CONFIG.TP Type STRING.TP Default remap.config.TP Deprecated Yes.UNINDENT Sets the
name of the remap.config file.
proxy.config.url_remap.remap_required
Scope CONFIG.TP Type INT.TP Default 1.TP Reloadable Yes.UNINDENT Set this variable to 1
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.TP Type INT.TP Default 0.TP Reloadable Yes.TP Overridable Yes.UNINDENT Set
this variable to 1 if you want to retain the client host header in a request during
remapping.
SSL TERMINATION
proxy.config.ssl.server.cipher_suite
Scope CONFIG.TP Type STRING.TP Default <see notes>.UNINDENT 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.TP Type STRING.TP Default <See notes under
proxy.config.ssl.server.cipher_suite.>.UNINDENT 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.TP Type STRING.TP Default <See notes>.UNINDENT 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.
proxy.config.ssl.server.honor_cipher_order
Scope CONFIG.TP Type INT.TP Default 1.UNINDENT By default (1) Traffic Server will use the
server's cipher suites preferences instead of the client preferences. By disabling
it (0) Traffic Server will use client's cipher suites preferences.
proxy.config.ssl.server.prioritize_chacha
Scope CONFIG.TP Type INT.TP Default 0.UNINDENT By enabling it (1) 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.
proxy.config.ssl.client.TLSv1_3.cipher_suites
Scope CONFIG.TP Type STRING.TP Default <See notes under
proxy.config.ssl.server.tls.cipher_suites>.UNINDENT 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.
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.TP Type STRING.TP Default <See notes>.UNINDENT 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.TP Type STRING.TP Default <See notes under
proxy.config.ssl.server.groups_list.>.UNINDENT 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.TLSv1
Scope CONFIG.TP Type INT.TP Default 0.UNINDENT Enables (1) or disables (0) TLSv1.0. If
not specified, disabled by default.
proxy.config.ssl.TLSv1_1
Scope CONFIG.TP Type INT.TP Default 0.UNINDENT Enables (1) or disables (0) 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.TP Type INT.TP Default 1.UNINDENT Enables (1) or disables (0) TLS v1.2. If
not specified, enabled by default. [Requires OpenSSL v1.0.1 and higher]
proxy.config.ssl.TLSv1_3
Scope CONFIG.TP Type INT.TP Default 1.UNINDENT Enables (1) or disables (0) TLS v1.3. If
not specified, enabled by default. [Requires OpenSSL v1.1.1 and higher]
proxy.config.ssl.client.certification_level
Scope CONFIG.TP Type INT.TP Default 0.UNINDENT Sets the client certification level:
┌──────┬──────────────────────────────────┐
│Value │ Description │
└──────┴──────────────────────────────────┘
│0 │ 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). │
├──────┼──────────────────────────────────┤
│1 │ 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. │
├──────┼──────────────────────────────────┤
│2 │ 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.TP Type STRING.TP Default ssl_multicert.config.TP Deprecated Yes.UNINDENT
The location of the ssl_multicert.config 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.config
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.TP Type INT.TP Default 1.UNINDENT By default (1), Traffic Server will not
start unless all the SSL certificates listed in the ssl_multicert.config file
successfully load. If false (0), SSL certificate load failures will not prevent
Traffic Server from starting.
proxy.config.ssl.server.cert.path
Scope CONFIG.TP Type STRING.TP Default /config.UNINDENT 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.config will be loaded
relative to this path.
proxy.config.ssl.server.private_key.path
Scope CONFIG.TP Type STRING.TP Default NULL.UNINDENT 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.config will be
loaded relative to this path.
proxy.config.ssl.server.cert_chain.filename
Scope CONFIG.TP Type STRING.TP Default NULL.UNINDENT 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.config.
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.TP Type STRING.TP Default NULL.UNINDENT 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.TP Type STRING.TP Default NULL.UNINDENT The location of the certificate
authority file that client certificates will be verified against.
proxy.config.ssl.CA.cert.filename
Scope CONFIG.TP Type STRING.TP Default NULL.UNINDENT The filename of the certificate
authority that client certificates will be verified against.
proxy.config.ssl.server.ticket_key.filename
Scope CONFIG.TP Type STRING.TP Default NULL.UNINDENT 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.TP Type STRING.TP Default sni.yaml.TP Deprecated Yes.UNINDENT 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.TP Type INT.TP Default 0.UNINDENT 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 0 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
Scope CONFIG.TP Type INT.TP Default 1.UNINDENT This configuration enables the SSL session
cache for the origin server when set to 1.
Setting to 0 disables SSL session cache for the origin server.
proxy.config.ssl.origin_session_cache.size
Scope CONFIG.TP Type INT.TP Default 10240.UNINDENT 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 0 effectively disables SSL session cache for
the origin server.
proxy.config.ssl.session_cache
Scope CONFIG.TP Type INT.TP Default 2.UNINDENT Enables the SSL session cache:
┌──────┬──────────────────────────────────┐
│Value │ Description │
├──────┼──────────────────────────────────┤
│0 │ Disables the session cache │
│ │ entirely. │
├──────┼──────────────────────────────────┤
│1 │ Enables the session cache using │
│ │ OpenSSL's implementation. │
├──────┼──────────────────────────────────┤
│2 │ Default. Enables the session │
│ │ cache using Traffic Server's │
│ │ implementation. This │
│ │ implementation should perform │
│ │ much better than the OpenSSL │
│ │ implementation. │
└──────┴──────────────────────────────────┘
proxy.config.ssl.session_cache.timeout
Scope CONFIG.TP Type INT.TP Default 0.UNINDENT This configuration specifies the lifetime
of SSL session cache entries in seconds. If it is 0, then the SSL library will use
a default value, typically 300 seconds. Note: This option has no affect when using
the Traffic Server session cache (option 2 in proxy.config.ssl.session_cache)
See Timeout Settings for more discussion on Traffic Server timeouts.
proxy.config.ssl.session_cache.auto_clear
Scope CONFIG.TP Type INT.TP Default 1.UNINDENT This will set the OpenSSL auto clear flag.
Auto clear is enabled by default with 1 it can be disabled by changing this setting
to 0.
proxy.config.ssl.session_cache.size
Scope CONFIG.TP Type INT.TP Default 102400.UNINDENT This configuration specifies the
maximum number of entries the SSL session cache may contain.
proxy.config.ssl.session_cache.num_buckets
Scope CONFIG.TP Type INT.TP Default 256.UNINDENT This configuration specifies the number
of buckets to use with the Traffic Server SSL session cache implementation. The TS
implementation is a fixed size hash map where each bucket is protected by a mutex.
proxy.config.ssl.session_cache.skip_cache_on_bucket_contention
Scope CONFIG.TP Type INT.TP Default 0.UNINDENT This configuration specifies the behavior
of the Traffic Server SSL session cache implementation during lock contention on
each bucket:
┌──────┬──────────────────────────────────┐
│Value │ Description │
├──────┼──────────────────────────────────┤
│0 │ Default. Don't skip session │
│ │ caching when bucket lock is │
│ │ contented. │
├──────┼──────────────────────────────────┤
│1 │ Disable the SSL session cache │
│ │ for a connection during lock │
│ │ contention. │
└──────┴──────────────────────────────────┘
proxy.config.ssl.server.session_ticket.enable
Scope CONFIG.TP Type INT.TP Default 1.UNINDENT Set to 1 to enable Traffic Server to
process TLS tickets for TLS session resumption.
proxy.config.ssl.server.session_ticket.number
Scope CONFIG.TP Type INT.TP Default 2.UNINDENT This configuration control the number of
TLSv1.3 session tickets that are issued. Take into account that setting the value
to 0 will disable session caching for TLSv1.3 connections.
Lowering this setting to 1 can be interesting when proxy.config.ssl.session_cache
is enabled because otherwise for every new TLSv1.3 connection two session IDs will
be inserted in the session cache. On the other hand, if
proxy.config.ssl.session_cache is disabled, using the default value is
recommended. In those scenarios, 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
https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_set_num_tickets.html [Requires
OpenSSL v1.1.1 and higher]
proxy.config.ssl.hsts_max_age
Scope CONFIG.TP Type INT.TP Default -1.TP Overridable Yes.UNINDENT 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 0 will set
the max-age value to 0 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.TP Type INT.TP Default 0.TP Overridable Yes.UNINDENT Enables (1) or disables
(0) 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.TP Type INT.TP Default 0.UNINDENT This configuration specifies whether the
client is able to initiate renegotiation of the SSL connection. The default of 0,
means the client can't initiate renegotiation.
proxy.config.ssl.cert.load_elevated
Scope CONFIG.TP Type INT.TP Default 0.UNINDENT Enables (1) or disables (0) 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.TP Type INT.TP Default 30.UNINDENT 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.TP Type STRING.TP Default NULL.TP Reloadable Yes.UNINDENT 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.
Client-Related Configuration
proxy.config.ssl.client.verify.server.policy
Scope CONFIG.TP Type STRING.TP Default PERMISSIVE.TP Reloadable Yes.TP Overridable
Yes.UNINDENT 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.TP Type STRING.TP Default ALL.TP Reloadable Yes.TP Overridable Yes.UNINDENT
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 .:file: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.TP Type STRING.TP Default NULL.TP Reloadable Yes.TP Overridable Yes.UNINDENT
The filename of SSL client certificate installed on Traffic Server.
proxy.config.ssl.client.cert.path
Scope CONFIG.TP Type STRING.TP Default /config.TP Reloadable Yes.UNINDENT The location of
the SSL client certificate installed on Traffic Server.
proxy.config.ssl.client.private_key.filename
Scope CONFIG.TP Type STRING.TP Default NULL.TP Reloadable Yes.TP Overridable Yes.UNINDENT
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.TP Type STRING.TP Default NULL.TP Reloadable Yes.UNINDENT 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.TP Type STRING.TP Default NULL.TP Reloadable Yes.TP Overridable Yes.UNINDENT
The filename of the certificate authority against which the origin server will be
verified.
proxy.config.ssl.client.CA.cert.path
Scope CONFIG.TP Type STRING.TP Default NULL.TP Reloadable Yes.UNINDENT Specifies the
location of the certificate authority file against which the origin server will be
verified.
proxy.config.ssl.client.sni_policy
Scope CONFIG.TP Type STRING.TP Default NULL.TP Overridable Yes.UNINDENT 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.TP Type INT.TP Default 2.TP Overridable Yes.UNINDENT 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 2 and the client connection is a cleartext HTTP connection but the
scheme of the URL is https://, 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 2, meaning that Traffic Server will enforce that the protocol
matches the scheme.
┌──────┬──────────────────────────────────┐
│Value │ Description │
├──────┼──────────────────────────────────┤
│0 │ Disable verification that the │
│ │ protocol and scheme match. │
├──────┼──────────────────────────────────┤
│1 │ Check that the protocol and │
│ │ scheme match, but only emit a │
│ │ warning if they do not. │
├──────┼──────────────────────────────────┤
│2 │ 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.TLSv1
Scope CONFIG.TP Type INT.TP Default 0.UNINDENT Enables (1) or disables (0) TLSv1.0 in the
ATS client context. If not specified, enabled by default
proxy.config.ssl.client.TLSv1_1
Scope CONFIG.TP Type INT.TP Default 0.UNINDENT Enables (1) or disables (0) TLSv1_1 in the
ATS client context. If not specified, enabled by default
proxy.config.ssl.client.TLSv1_2
Scope CONFIG.TP Type INT.TP Default 1.UNINDENT Enables (1) or disables (0) TLSv1_2 in the
ATS client context. If not specified, enabled by default
proxy.config.ssl.client.TLSv1_3
Scope CONFIG.TP Type INT.TP Default 1.UNINDENT Enables (1) or disables (0) TLSv1_3 in the
ATS client context. If not specified, enabled by default
proxy.config.ssl.async.handshake.enabled
Scope CONFIG.TP Type INT.TP Default 0.UNINDENT 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.c.
proxy.config.ssl.engine.conf_file
Scope CONFIG.TP Type STRING.TP Default NULL.UNINDENT 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.TP Type INT.TP Default 0.UNINDENT 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 0 effectively disables 0-RTT.
proxy.config.ssl.server.allow_early_data_params
Scope CONFIG.TP Type INT.TP Default 0.UNINDENT Set to 1 to allow HTTP parameters on early
data requests.
SNI Routing
proxy.config.tunnel.activity_check_period
Scope CONFIG.TP Type INT.TP Default 0.TP Units seconds.UNINDENT Frequency of checking the
activity of SNI Routing Tunnel. Set to 0 to disable monitoring of the activity of
the SNI tunnels. The feature is disabled by default.
proxy.config.tunnel.prewarm
Scope CONFIG.TP Type INT.TP Default 0.UNINDENT Enable Pre-warming TLS Tunnel. The feature
is disabled by default.
proxy.config.tunnel.prewarm.max_stats_size
Scope CONFIG.TP Type INT.TP Default 100.UNINDENT Max size of dynamic stats for
Pre-warming TLS Tunnel.
proxy.config.tunnel.prewarm.algorithm
Scope CONFIG.TP Type INT.TP Default 2.UNINDENT Version of pre-warming algorithm.
┌──────┬──────────────────────────────────┐
│Value │ Description │
├──────┼──────────────────────────────────┤
│1 │ Periodical pre-warming only │
├──────┼──────────────────────────────────┤
│2 │ Event based pre-warming + │
│ │ Periodical pre-warming │
└──────┴──────────────────────────────────┘
proxy.config.tunnel.prewarm.event_period
Scope CONFIG.TP Type INT.TP Default 1000.TP Units milliseconds.UNINDENT Frequency of
periodical pre-warming in milli-seconds.
OCSP STAPLING CONFIGURATION
proxy.config.ssl.ocsp.enabled
Scope CONFIG.TP Type INT.TP Default 0.UNINDENT Enable OCSP stapling.
┌──────┬──────────────────────────────────┐
│Value │ Description │
├──────┼──────────────────────────────────┤
│0 │ Disables OCSP Stapling. │
├──────┼──────────────────────────────────┤
│1 │ Allows Traffic Server to request │
│ │ SSL certificate revocation │
│ │ status from an OCSP responder. │
└──────┴──────────────────────────────────┘
proxy.config.ssl.ocsp.cache_timeout
Scope CONFIG.TP Type INT.TP Default 3600.UNINDENT Number of seconds before an OCSP
response expires in the stapling cache.
proxy.config.ssl.ocsp.request_timeout
Scope CONFIG.TP Type INT.TP Default 10.TP Units seconds.UNINDENT Timeout (in seconds) for
queries to OCSP responders.
proxy.config.ssl.ocsp.update_period
Scope CONFIG.TP Type INT.TP Default 60.TP Units seconds.UNINDENT Update period (in
seconds) for stapling caches.
proxy.config.ssl.ocsp.response.path
Scope CONFIG.TP Type STRING.TP Default NULL.UNINDENT 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.config will be loaded relative to this path.
HTTP/2 CONFIGURATION
proxy.config.http2.max_concurrent_streams_in
Scope CONFIG.TP Type INT.TP Default 100.TP Reloadable Yes.UNINDENT 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.min_concurrent_streams_in
Scope CONFIG.TP Type INT.TP Default 10.TP Reloadable Yes.UNINDENT The minimum number of
concurrent streams per inbound connection. This is used when
proxy.config.http2.max_active_streams_in is set larger than 0.
proxy.config.http2.max_active_streams_in
Scope CONFIG.TP Type INT.TP Default 0.TP Reloadable Yes.UNINDENT 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 (0).
proxy.config.http2.initial_window_size_in
Scope CONFIG.TP Type INT.TP Default 65535.TP Units bytes.TP Reloadable Yes.UNINDENT The
initial window size for inbound connections.
proxy.config.http2.max_frame_size
Scope CONFIG.TP Type INT.TP Default 16384.TP Units bytes.TP Reloadable Yes.UNINDENT
Indicates the size of the largest frame payload that the sender is willing to
receive.
proxy.config.http2.header_table_size
Scope CONFIG.TP Type INT.TP Default 4096.TP Reloadable Yes.UNINDENT 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.TP Type INT.TP Default 65536.TP Reloadable Yes.UNINDENT 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.TP Type INT.TP Default 131072.TP Reloadable Yes.UNINDENT This advisory
setting informs a peer of the maximum size of header list that the sender is
prepared to accept blocks. The default value, which is the unsigned int maximum
value in Traffic Server, implies unlimited size.
proxy.config.http2.stream_priority_enabled
Scope CONFIG.TP Type INT.TP Default 0.TP Reloadable Yes.UNINDENT Enable the experimental
HTTP/2 Stream Priority feature.
proxy.config.http2.active_timeout_in
Scope CONFIG.TP Type INT.TP Default 0.TP Units seconds.TP Reloadable Yes.UNINDENT 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 0 specifies that there is no timeout.
proxy.config.http2.accept_no_activity_timeout
Scope CONFIG.TP Type INT.TP Default 120.TP Units seconds.TP Reloadable Yes.UNINDENT
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.TP Type INT.TP Default 120.TP Units seconds.TP Reloadable Yes.UNINDENT
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.zombie_debug_timeout_in
Scope CONFIG.TP Type INT.TP Default 0.TP Reloadable Yes.UNINDENT 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.TP Type INT.TP Default 256.TP Reloadable Yes.UNINDENT 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.TP Type FLOAT.TP Default 0.1.TP Reloadable Yes.UNINDENT 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.TP Type INT.TP Default 10.TP Reloadable Yes.UNINDENT This is the threshold
of sampling stream number to start checking the stream error rate.
proxy.config.http2.max_settings_per_frame
Scope CONFIG.TP Type INT.TP Default 7.TP Reloadable Yes.UNINDENT 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.
proxy.config.http2.max_settings_per_minute
Scope CONFIG.TP Type INT.TP Default 14.TP Reloadable Yes.UNINDENT 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.
proxy.config.http2.max_settings_frames_per_minute
Scope CONFIG.TP Type INT.TP Default 14.TP Reloadable Yes.UNINDENT 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.
proxy.config.http2.max_ping_frames_per_minute
Scope CONFIG.TP Type INT.TP Default 60.TP Reloadable Yes.UNINDENT 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.
proxy.config.http2.max_priority_frames_per_minute
Scope CONFIG.TP Type INT.TP Default 120.TP Reloadable Yes.UNINDENT 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.
proxy.config.http2.max_rst_stream_frames_per_minute
Scope CONFIG.TP Type INT.TP Default 14.TP Reloadable Yes.UNINDENT Specifies how many
RST_STREAM 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.
proxy.config.http2.min_avg_window_update
Scope CONFIG.TP Type FLOAT.TP Default 2560.0.TP Reloadable Yes.UNINDENT 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.TP Type INT.TP Default 262144.TP Units bytes.TP Reloadable Yes.UNINDENT
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.TP Type FLOAT.TP Default 0.5.TP Reloadable Yes.UNINDENT 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.TP Type INT.TP Default 100.TP Units milliseconds.TP Reloadable Yes.UNINDENT
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.TP Type INT.TP Default -1.TP Units bytes.TP Reloadable Yes.UNINDENT
Specifies the high water mark for all HTTP/2 frames on an outoging 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_dir
Scope CONFIG.TP Type STRING.TP Default NULL.TP Reloadable Yes.UNINDENT
The qlog is enabled when this configuration is not NULL. And will dump the qlog to this
dir.
proxy.config.quic.instance_id
Scope CONFIG.TP Type INT.TP Default 0.TP Reloadable Yes.UNINDENT 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.TP Type INT.TP Default 65521.UNINDENT A size of hash table that stores
connection information.
proxy.config.quic.proxy.config.quic.num_alt_connection_ids
Scope CONFIG.TP Type INT.TP Default 65521.TP Reloadable Yes.UNINDENT 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.TP Type INT.TP Default 0.TP Reloadable Yes.UNINDENT Enables Stateless Retry.
proxy.config.quic.client.vn_exercise_enabled
Scope CONFIG.TP Type INT.TP Default 0.TP Reloadable Yes.UNINDENT Enables version
negotiation exercise on origin server connections.
proxy.config.quic.client.cm_exercise_enabled
Scope CONFIG.TP Type INT.TP Default 0.TP Reloadable Yes.UNINDENT Enables connection
migration exercise on origin server connections.
proxy.config.quic.server.supported_groups
Scope CONFIG.TP Type STRING.TP Default "P-256:X25519:P-384:P-521".TP Reloadable
Yes.UNINDENT 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.TP Type STRING.TP Default "P-256:X25519:P-384:P-521".TP Reloadable
Yes.UNINDENT 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.TP Type STRING.TP Default "".TP Reloadable Yes.UNINDENT 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.TP Type INT.TP Default 30000.TP Reloadable Yes.UNINDENT This value will be
advertised as idle_timeout Transport Parameter.
proxy.config.quic.no_activity_timeout_out
Scope CONFIG.TP Type INT.TP Default 30000.TP Reloadable Yes.UNINDENT This value will be
advertised as idle_timeout Transport Parameter.
proxy.config.quic.preferred_address_ipv4
Scope CONFIG.TP Type STRING.TP Default "".TP Reloadable Yes.UNINDENT This value will be
advertised as a part of preferred_address Transport Parameter.
proxy.config.quic.preferred_address_ipv6
Scope CONFIG.TP Type STRING.TP Default "".TP Reloadable Yes.UNINDENT This value will be
advertised as a part of preferred_address Transport Parameter.
proxy.config.quic.initial_max_data_in
Scope CONFIG.TP Type INT.TP Default 65536.TP Reloadable Yes.UNINDENT This value will be
advertised as initial_max_data Transport Parameter.
proxy.config.quic.initial_max_data_out
Scope CONFIG.TP Type INT.TP Default 65536.TP Reloadable Yes.UNINDENT This value will be
advertised as initial_max_data Transport Parameter.
proxy.config.quic.max_stream_data_bidi_local_in
Scope CONFIG.TP Type INT.TP Default 0.TP Reloadable Yes.UNINDENT 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.TP Type INT.TP Default 4096.TP Reloadable Yes.UNINDENT 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.TP Type INT.TP Default 4096.TP Reloadable Yes.UNINDENT 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.TP Type INT.TP Default 0.TP Reloadable Yes.UNINDENT This value will be
advertised as initial_max_stream_data_bidi_remote Transport Parameter.
proxy.config.quic.max_stream_data_uni_in
Scope CONFIG.TP Type INT.TP Default 4096.TP Reloadable Yes.UNINDENT This value will be
advertised as initial_max_stream_data_uni Transport Parameter.
proxy.config.quic.max_stream_data_uni_out
Scope CONFIG.TP Type INT.TP Default 0.TP Reloadable Yes.UNINDENT This value will be
advertised as initial_max_stream_data_uni Transport Parameter.
proxy.config.quic.max_streams_bidi_in
Scope CONFIG.TP Type INT.TP Default 100.TP Reloadable Yes.UNINDENT This value will be
advertised as initial_max_streams_bidi Transport Parameter.
proxy.config.quic.max_streams_bidi_out
Scope CONFIG.TP Type INT.TP Default 100.TP Reloadable Yes.UNINDENT This value will be
advertised as initial_max_streams_bidi Transport Parameter.
proxy.config.quic.max_streams_uni_in
Scope CONFIG.TP Type INT.TP Default 100.TP Reloadable Yes.UNINDENT This value will be
advertised as initial_max_streams_uni Transport Parameter.
proxy.config.quic.max_streams_uni_out
Scope CONFIG.TP Type INT.TP Default 100.TP Reloadable Yes.UNINDENT This value will be
advertised as initial_max_streams_uni Transport Parameter.
proxy.config.quic.ack_delay_exponent_in
Scope CONFIG.TP Type INT.TP Default 3.TP Reloadable Yes.UNINDENT This value will be
advertised as ack_delay_exponent Transport Parameter.
proxy.config.quic.ack_delay_exponent_out
Scope CONFIG.TP Type INT.TP Default 3.TP Reloadable Yes.UNINDENT This value will be
advertised as ack_delay_exponent Transport Parameter.
proxy.config.quic.max_ack_delay_in
Scope CONFIG.TP Type INT.TP Default 25.TP Reloadable Yes.UNINDENT This value will be
advertised as max_ack_delay Transport Parameter.
proxy.config.quic.max_ack_delay_out
Scope CONFIG.TP Type INT.TP Default 25.TP Reloadable Yes.UNINDENT This value will be
advertised as max_ack_delay Transport Parameter.
proxy.config.quic.loss_detection.packet_threshold
Scope CONFIG.TP Type INT.TP Default 3.TP Reloadable Yes.UNINDENT This is just for
debugging. Do not change it from the default value unless you really understand
what this is.
proxy.config.quic.loss_detection.time_threshold
Scope CONFIG.TP Type FLOAT.TP Default 1.25.TP Reloadable Yes.UNINDENT This is just for
debugging. Do not change it from the default value unless you really understand
what this is.
proxy.config.quic.loss_detection.granularity
Scope CONFIG.TP Type INT.TP Default 1.TP Reloadable Yes.UNINDENT This is just for
debugging. Do not change it from the default value unless you really understand
what this is.
proxy.config.quic.loss_detection.initial_rtt
Scope CONFIG.TP Type INT.TP Default 1.TP Reloadable Yes.UNINDENT This is just for
debugging. Do not change it from the default value unless you really understand
what this is.
proxy.config.quic.congestion_control.max_datagram_size
Scope CONFIG.TP Type INT.TP Default 1200.TP Reloadable Yes.UNINDENT This is just for
debugging. Do not change it from the default value unless you really understand
what this is.
proxy.config.quic.congestion_control.initial_window
Scope CONFIG.TP Type INT.TP Default 12000.TP Reloadable Yes.UNINDENT This is just for
debugging. Do not change it from the default value unless you really understand
what this is.
proxy.config.quic.congestion_control.minimum_window
Scope CONFIG.TP Type INT.TP Default 2400.TP Reloadable Yes.UNINDENT This is just for
debugging. Do not change it from the default value unless you really understand
what this is.
proxy.config.quic.congestion_control.loss_reduction_factor
Scope CONFIG.TP Type FLOAT.TP Default 0.5.TP Reloadable Yes.UNINDENT This is just for
debugging. Do not change it from the default value unless you really understand
what this is.
proxy.config.quic.congestion_control.persistent_congestion_threshold
Scope CONFIG.TP Type INT.TP Default 2.TP Reloadable Yes.UNINDENT This is just for
debugging. Do not change it from the default value unless you really understand
what this is.
PLUG-IN CONFIGURATION
proxy.config.plugin.plugin_dir
Scope CONFIG.TP Type STRING.TP Default config/plugins.UNINDENT Specifies the location of
Traffic Server plugins.
proxy.config.plugin.dynamic_reload_mode
Scope CONFIG.TP Type INT.TP Default 1.UNINDENT Enables (1) or disables (0) the dynamic
reload feature for remap plugins (remap.config). Global plugins (plugin.config) do
not have dynamic reload feature yet.
proxy.config.plugin.vc.default_buffer_index
Scope CONFIG.TP Type INT.TP Default 8.TP Reloadable Yes.TP Overridable Yes.UNINDENT
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.TP Type INT.TP Default 0.TP Reloadable Yes.TP Overridable Yes.UNINDENT
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.TP Type INT.TP Default 0.UNINDENT Enables (1) or disables (0) the SOCKS
processor
proxy.config.socks.socks_version
Scope CONFIG.TP Type INT.TP Default 4.UNINDENT Specifies the SOCKS version (4) or (5)
proxy.config.socks.socks_config_file
Scope CONFIG.TP Type STRING.TP Default socks.config.TP Deprecated Yes.UNINDENT 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.TP Type INT.TP Default 100.UNINDENT 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.TP Type INT.TP Default 10.UNINDENT 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.TP Type INT.TP Default 1.UNINDENT The total number of connection attempts
allowed per SOCKS server, if multiple servers are used.
proxy.config.socks.connection_attempts
Scope CONFIG.TP Type INT.TP Default 4.UNINDENT 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.TP Type INT.TP Default 300.UNINDENT 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.TP Type STRING.TP Default *NONE*.UNINDENT Default list of SOCKS servers and
their ports.
proxy.config.socks.server_retry_time
Scope CONFIG.TP Type INT.TP Default 300.UNINDENT The amount of time allowed between
connection retries to a SOCKS server that is unavailable.
proxy.config.socks.server_fail_threshold
Scope CONFIG.TP Type INT.TP Default 2.UNINDENT 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.TP Type INT.TP Default 0.UNINDENT Enables (1) or disables (0) the SOCKS
proxy option. As a SOCKS proxy, Traffic Server receives SOCKS traffic (usually on
port 1080) and forwards all requests directly to the SOCKS server.
proxy.config.socks.accept_port
Scope CONFIG.TP Type INT.TP Default 1080.UNINDENT Specifies the port on which Traffic
Server accepts SOCKS traffic.
proxy.config.socks.http_port
Scope CONFIG.TP Type INT.TP Default 80.UNINDENT Specifies the port on which Traffic
Server accepts HTTP proxy requests over SOCKS connections..
SOCKETS
proxy.config.net.defer_accept
Scope CONFIG.TP Type INT.TP Default 1.UNINDENT default: 1 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. On FreeBSD, accf_data
module needs to be loaded.
proxy.config.net.listen_backlog
Scope CONFIG.TP Type INT.TP Default -1
:reloadable:.UNINDENT 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.TP Type STRING.TP Default "".UNINDENT 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.TP Type STRING.TP Default "".UNINDENT 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.TP Type INT.TP Default 0.UNINDENT Sets the send buffer size for connections
from the client to Traffic Server.
proxy.config.net.sock_recv_buffer_size_in
Scope CONFIG.TP Type INT.TP Default 0.UNINDENT Sets the receive buffer size for
connections from the client to Traffic Server.
proxy.config.net.sock_option_flag_in
Scope CONFIG.TP Type INT.TP Default 0x1.UNINDENT Turns different options "on" for the
socket handling client connections::
TCP_NODELAY (1)
SO_KEEPALIVE (2)
SO_LINGER (4) - with a timeout of 0 seconds
TCP_FASTOPEN (8)
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 3 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.
proxy.config.net.sock_send_buffer_size_out
Scope CONFIG.TP Type INT.TP Default 0.TP Overridable Yes.UNINDENT Sets the send buffer
size for connections from Traffic Server to the origin server.
proxy.config.net.sock_recv_buffer_size_out
Scope CONFIG.TP Type INT.TP Default 0.TP Overridable Yes.UNINDENT Sets the receive buffer
size for connections from Traffic Server to the origin server.
proxy.config.net.sock_option_flag_out
Scope CONFIG.TP Type INT.TP Default 0x1.TP Overridable Yes.UNINDENT Turns different
options "on" for the origin server socket::
TCP_NODELAY (1)
SO_KEEPALIVE (2)
SO_LINGER (4) - with a timeout of 0 seconds
TCP_FASTOPEN (8)
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 3 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.TP Type INT.TP Default 0.UNINDENT Same as the command line option
--accept_mss that sets the MSS for all incoming requests.
proxy.config.net.sock_packet_mark_in
Scope CONFIG.TP Type INT.TP Default 0x0.UNINDENT 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.TP Type INT.TP Default 0x0.TP Overridable Yes.UNINDENT 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.TP Type INT.TP Default 0x0.UNINDENT 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.TP Type INT.TP Default 0x0.TP Overridable Yes.UNINDENT 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.TP Type INT.TP Default 16384.TP Overridable Yes.UNINDENT Set socket option
TCP_NOTSENT_LOWAT to specified value for a connection
proxy.config.net.poll_timeout
Scope CONFIG.TP Type INT.TP Default 10 (or 30 on Solaris).UNINDENT 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:
CONFIG proxy.config.exec_thread.autoconfig INT 0
CONFIG proxy.config.exec_thread.limit INT 2
CONFIG proxy.config.accept_threads INT 1
CONFIG proxy.config.cache.threads_per_disk INT 8
See Timeout Settings for more discussion on Traffic Server timeouts.
proxy.config.task_threads
Scope CONFIG.TP Type INT.TP Default 2.UNINDENT 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.TP Type INT.TP Default 512.UNINDENT 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 0, there is no limit enforced.
proxy.config.allocator.thread_freelist_low_watermark
Scope CONFIG.TP Type INT.TP Default 32.UNINDENT 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.TP Type INT.TP Default 0.UNINDENT 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_overcommit_hugepages to a sufficiently large
value. It is reasonable to use (system memory/hugepage size) because these pages
are only created on demand.
For more information on the implications of enabling huge pages, see Wikipedia
<http://en.wikipedia.org/wiki/Page_%28computer_memory%29#Page_size_trade-off>_.
proxy.config.dump_mem_info_frequency
Scope CONFIG.TP Type INT.TP Default 0.TP Reloadable Yes.UNINDENT Enable <value>. When
enabled makes Traffic Server dump IO Buffer memory information to traffic.out at
<value> (intervals are in seconds). A zero value implies it is disabled
proxy.config.res_track_memory
Scope CONFIG.TP Type INT.TP Default 0.UNINDENT 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 │
├──────┼──────────────────────────────────┤
│0 │ Memory tracking Disabled │
└──────┴──────────────────────────────────┘
│1 │ Tracks IO Buffer Memory │
│ │ allocations and releases │
├──────┼──────────────────────────────────┤
│2 │ Tracks IO Buffer Memory and │
│ │ OpenSSL Memory allocations and │
│ │ releases │
└──────┴──────────────────────────────────┘
proxy.config.system_clock
Scope CONFIG.TP Type INT.TP Default 0.UNINDENT For advanced users only. This allows to
specify the underlying system clock used by ATS. The default is CLOCK_REALTIME (0),
but a higher performance option could be CLOCK_REALTIME_COARSE (5). See
clock_gettime(2) for more details. On Linux, these definitions can be found in
<linux/time.h>.
proxy.config.allocator.dontdump_iobuffers
Scope CONFIG.TP Type INT.TP Default 1.UNINDENT 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.ssl.misc.io.max_buffer_index
Scope CONFIG.TP Type INT.TP Default 8.UNINDENT 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.TP Type INT.TP Default 8.UNINDENT 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.TP Type INT.TP Default 8.UNINDENT 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.TP Type INT.TP Default 8.UNINDENT 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.TP Type INT.TP Default 8.UNINDENT 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.TP Type INT.TP Default 1.UNINDENT 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.TP Type INT.TP Default 1.TP Reloadable Yes.TP Overridable Yes.UNINDENT 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.TP Type INT.TP Default 0.UNINDENT 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 │
├──────┼──────────────────────────────────┤
│0 │ 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. │
├──────┼──────────────────────────────────┤
│1 │ Do not accept inbound │
│ │ connections until cache │
│ │ initialization has finished. │
│ │ Traffic Server will run │
│ │ regardless of the results of │
│ │ cache initialization. │
├──────┼──────────────────────────────────┤
│2 │ 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. │
└──────┴──────────────────────────────────┘
│3 │ 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. │
└──────┴──────────────────────────────────┘
COPYRIGHT
2024, dev@trafficserver.apache.org