DOKK / manpages / debian 10 / trafficserver / records.config.5.en
RECORDS.CONFIG(5) Apache Traffic Server RECORDS.CONFIG(5)

records.config - the records.config file (by default (proxy.config.config_dir), 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

Each variable has the following format:

CONFIG variable_name DATATYPE variable_value


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.

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)

IMPORTANT:

Unless proxy.config.disable_configuration_modification is enabled, Traffic Server writes configurations back to disk periodically. When doing so, the unit prefixes are not preserved.


Floating point variables (FLOAT) must be expressed as a regular decimal number. Unit prefixes are not supported, nor are alternate notations (scientific, exponent, etc.).

A variable marked as Deprecated is still functional but should be avoided as it may be removed in a future release without warning.

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.

A variable marked as Overridable can be changed on a per-remap basis using plugins (like the admin-plugins-conf-remap), affecting operations within the current transaction only.

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


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


The following list describes the configuration variables available in the records.config file.


CONFIG.TP Type STRING.TP Default Apache Software Foundation.UNINDENT The name of the organization developing Traffic Server.

CONFIG.TP Type STRING.TP Default Apache.UNINDENT The name of the vendor providing Traffic Server.

CONFIG.TP Type STRING.TP Default Traffic Server.UNINDENT The name of the product.

CONFIG.TP Type STRING.TP Default build_machine.TP Reloadable Yes.UNINDENT The name of the Traffic Server node.

CONFIG.TP Type STRING.TP Default bin.UNINDENT The location of the Traffic Server bin directory.

CONFIG.TP Type STRING.TP Default traffic_server.UNINDENT The name of the executable that runs the traffic_server process.

CONFIG.TP Type STRING.TP Default -M.UNINDENT The command-line options for starting Traffic Server.

CONFIG.TP Type STRING.TP Default traffic_manager.UNINDENT The name of the executable that runs the traffic_manager process.

CONFIG.TP Type STRING.TP Default *NONE*.UNINDENT The script executed before the traffic_manager process spawns the traffic_server process.

CONFIG.TP Type STRING.TP Default etc/trafficserver.UNINDENT The directory that contains Traffic Server configuration files. This is a read-only configuration option that contains the SYSCONFDIR value specified at build time relative to the installation prefix. 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.

CONFIG.TP Type STRING.TP Default LOG_DAEMON.UNINDENT The facility used to record system log files. Refer to admin-logging-understanding for more in-depth discussion of the contents and interpretations of log files.

CONFIG.TP Type STRING.TP Default traffic.out.UNINDENT The name and location of the file that contains warnings, status messages, and error messages produced by the Traffic Server processes. If no path is specified, then Traffic Server creates the file in its logging directory.

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.


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).

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 bootup.

CONFIG.TP Type INT.TP Default 100.TP Units megabytes.TP Reloadable Yes.UNINDENT Specifies at what size to roll the output log at.


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.

CONFIG.TP Type FLOAT.TP Default 1.5.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.5.

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.

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.

CONFIG.TP Type INT.TP Default 1048576.UNINDENT Default thread stack size, in bytes, for all threads (default is 1 MB).

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.



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 the fs.file-max proc value in Linux. The default is 90%.

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.


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.

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.

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. It only supports HTTP/2 graceful shutdown for now. Stopping Traffic Server here means sending traffic_server a signal either by bin/trafficserver stop or kill.

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.


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 ~9,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.

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 admin-performance-timeouts for more discussion on Traffic Server timeouts.


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.

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.


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


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]



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.


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


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]



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).

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).

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).

CONFIG.TP Type INT.TP Default 50.TP Reloadable Yes.UNINDENT When we trigger a throttling scenario, this how long our accept() are delayed.


CONFIG.TP Type INT.TP Default 3.UNINDENT The maximum number of copies of rolled configuration files to keep.

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.

As of version 2.1.1 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.




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 program:traffic_manager initializes.


CONFIG.TP Type INT.TP Default 0.TP Reloadable Yes.UNINDENT This setting prevents Traffic Server from rewriting the records.config configuration file. Dynamic configuration changes can still be made using traffic_ctl config set, but these changes will not be persisted on service restarts or when traffic_ctl config reload is run.


CONFIG.TP Type STRING.TP Default *NONE*.TP Reloadable Yes.UNINDENT The address to which the alarm script should send email.

CONFIG.TP Type STRING.TP Default example_alarm_bin.sh.TP Reloadable Yes.UNINDENT Name of the script file that can execute certain actions when an alarm is signaled. The script is invoked with up to 4 arguments:
  • The alarm message.
  • The value of proxy.config.product_name.
  • The value of proxy.config.admin.user_id.
  • The value of proxy.config.alarm_email.


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.

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.


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.
tr-full Fully transparent (inbound and outbound)
tr-in Inbound transparent.
tr-out Outbound transparent.
tr-pass Pass through enabled.
Local IP port to bind. This is the port to which ATS clients will connect.
Accept only the CONNECT method on this port.

Not compatible with: tr-in, ssl.

Compress the connection. Retained only by inertia, should be considered "not implemented".
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.
Use IPv6. This is forced if the ip-in option is used with an IPv6 address.
Require SSL termination for inbound connections. SSL must be configured for this option to provide a functional server port.

Not compatible with: blind.

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.
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.
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.

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

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

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.
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.

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.

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.


Listen on port 80 on any address for IPv4 and IPv6.:

80 80:ipv6


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


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


Listen on port 9090 for TSL enabled HTTP/2 or HTTP connections, accept no other session protocols.:

9090:proto=http2;http:ssl


Listen on port 9090 for TSL disabled HTTP/2 and enabled HTTP connections, accept no other session protocols.:

9090:proto=http:ssl



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.



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.

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.



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.

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 acode can be decoded with the Via Decoder Ring.



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.

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.

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.

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.

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.

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.

NOTE:

If HTTP/1.1 is used, then Traffic Server can use keep-alive connections with pipelining to origin servers.

If HTTP/1.0 is used, then Traffic Server can use keep-alive connections without pipelining to origin servers.

If HTTP/0.9 is used, then Traffic Server does not use keep-alive connections to origin servers.




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.

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.



CONFIG.TP Type INT.TP Default 0.TP Overridable Yes.UNINDENT Configures the size, in packets, of the initial TCP congestion window on sockets used by the HTTP engine. This option may only be used on operating systems which support the TCP_INIT_CWND option on TCP sockets.

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.

CONFIG.TP Type STRING.TP Default both.TP Overridable Yes.UNINDENT Enable and set the ability to re-use server connections across client connections. The valid values are:
Value Description
none Do not match and do not re-use server sessions. If using this in ts-overridable-config (like the admin-plugins-conf-remap), use the integer 0 instead.
both Re-use server sessions, if both the IP address and fully qualified domain name match. If using this in ts-overridable-config (like the admin-plugins-conf-remap), use the integer 1 instead.
ip Re-use server sessions, checking only that the IP address and port of the origin server matches. If using this in ts-overridable-config (like the admin-plugins-conf-remap), use the integer 2 instead.
host Re-use server sessions, checking only that the fully qualified domain name matches. If using this in ts-overridable-config (like the admin-plugins-conf-remap), use the integer 3 instead.

It is strongly recommended to use either none or both for this value unless you have a specific need for the other settings. The most common reason is virtual hosts that share an IP address in which case performance can be enhanced if those sessions can be re-used. However, not all web servers support requests for different virtual hosts on the same connection so use with caution.

NOTE:

Server sessions to different ports never match even if the FQDN and IP address match.



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.

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.

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.


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. 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.


CONFIG.TP Type INT.TP Default 1.TP Overridable Yes.UNINDENT Enables (1) or disables (0) incoming keep-alive connections.

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.



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).

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.


CONFIG.TP Type INT.TP Default 8.UNINDENT Configures the default buffer size, in bytes, to allocate for incoming request bodies which lack a Content-length header.

CONFIG.TP Type INT.TP Default 32768.UNINDENT

CONFIG.TP Type INT.TP Default 131072.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.

CONFIG.TP Type INT.TP Default 131072.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.

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.

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.

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.


CONFIG.TP Type INT.TP Default 0.TP Reloadable Yes.UNINDENT Enables (1) or disables (0) the parent caching option. Refer to admin-hierarchical-caching.

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.

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.

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

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.

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 admin-performance-timeouts for more discussion on Traffic Server timeouts.


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.

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.

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.

CONFIG.TP Type INT.TP Default 0.UNINDENT

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.


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 disable the no activity timeout.

See admin-performance-timeouts for more discussion on Traffic Server timeouts.


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 disable the no activity timeout.

See admin-performance-timeouts for more discussion on Traffic Server timeouts.


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 admin-performance-timeouts for more discussion on Traffic Server timeouts.


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 admin-performance-timeouts for more discussion on Traffic Server timeouts.


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 admin-performance-timeouts for more discussion on Traffic Server timeouts.


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 admin-performance-timeouts for more discussion on Traffic Server timeouts.


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 admin-performance-timeouts for more discussion on Traffic Server timeouts.


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 admin-performance-timeouts for more discussion on Traffic Server timeouts.


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 admin-performance-timeouts for more discussion on Traffic Server timeouts.


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 admin-performance-timeouts for more discussion on Traffic Server timeouts.


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).


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.

CONFIG.TP Type INT.TP Default 1.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.

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.


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. 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.

CONFIG.TP Type INT.TP Default 1.TP Reloadable Yes.TP Overridable Yes.UNINDENT Maximum number of connection retries Traffic Server can make while an origin is marked dead. 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.

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 ts:cv:proxy.config.net.connections_throttle connections, which in turn can starve incoming requests from available connections.


CONFIG.TP Type INT.TP Default 0.TP Reloadable Yes.TP Overridable Yes.UNINDENT Limits the number of socket connections per origin server to the value specified. To enable, set to one (1).

CONFIG.TP Type INT.TP Default -1.TP Reloadable Yes.TP Overridable Yes.UNINDENT Limits the number of requests to be queued when the proxy.config.http.origin_max_connections is reached. When disabled (-1) requests are will wait indefinitely for an available connection. When set to 0 all requests past the proxy.config.http.origin_max_connections will immediately fail. When set to >0 ATS will queue that many requests to go to the origin, any additional requests past the limit will immediately fail.

CONFIG.TP Type INT.TP Default 0.TP Reloadable Yes.UNINDENT As connection to an origin server are opened, keep at least 'n' number of connections open to that origin, even if the connection isn't used for a long time period. 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. To enable, set to one (1).

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.

CONFIG.TP Type INT.TP Default 30.TP Reloadable Yes.TP Overridable Yes.UNINDENT The timeout value (in seconds) for time to first byte for an origin server connection.

See admin-performance-timeouts for more discussion on Traffic Server timeouts.


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 admin-performance-timeouts for more discussion on Traffic Server timeouts.


CONFIG.TP Type INT.TP Default 1.UNINDENT Enables (1) or disables (0) checking the Content-Length: Header for a POST request.

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.

CONFIG.TP Type INT.TP Default 10.TP Reloadable Yes.TP Overridable Yes.UNINDENT The number of seconds before Traffic Server marks an origin server as unavailable after a client abandons a request because the origin server was too slow in sending the response header.

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.


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.

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.

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.

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.


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.


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.

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.

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.

A value of 0 disables serving stale content and a value of 1 enables keeping and serving stale content if revalidation fails.


CONFIG.TP Type INT.TP Default 1800.UNINDENT How long, in seconds, to consider a stale cached document valid if If proxy.config.http.negative_revalidating_enabled is enabled and Traffic Server receives a negative (5xx only) response from the origin server during revalidation.


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.

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.

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.

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.

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.

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

CONFIG.TP Type STRING.TP Default NULL.TP Reloadable Yes.UNINDENT Comma separated list of headers Traffic Server should remove from outgoing requests.

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.

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.


CONFIG.TP Type STRING.TP Default ```<ip list>```.UNINDENT This defines a whitelist 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.

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.

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

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).


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.config file to allow only certain machines to push content into the cache.



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.

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.


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 admin-configuration-reducing-origin-requests.


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

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.

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.


CONFIG.TP Type INT.TP Default 1.TP Reloadable Yes.TP Overridable Yes.UNINDENT Enables (1) or disables (0) caching of HTTP requests.

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 overrideable configuration, it can be used to purge the entire cache, or just a specific remap.config rule.

CONFIG.TP Type INT.TP Default 1.TP Reloadable Yes.TP Deprecated Yes.UNINDENT Enables (1) or disables (0) caching objects that have an empty response body. This is particularly useful for caching 301 or 302 responses with a Location header but no document body. This only works if the origin response also has a Content-Length header.

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 admin-plugins-conf-remap for more information.


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.

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.

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.

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.

CONFIG.TP Type INT.TP Default 0.TP Overridable Yes.UNINDENT When enabled (1), Traffic Server ignores WWW-Authentication headers in responses WWW-Authentication headers are removed and not cached.

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

CONFIG.TP Type INT.TP Default 0.TP Reloadable Yes.TP Overridable Yes.UNINDENT Enables (1) or disables (0) caching of alternate versions of HTTP objects that do not contain the Vary header.

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.


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.

CONFIG.TP Type INT.TP Default 604800.TP Reloadable Yes.TP Overridable Yes.UNINDENT The maximum age allowed for a stale response before it cannot be cached.

CONFIG.TP Type INT.TP Default 1.TP Overridable Yes.UNINDENT When enabled (1), Traffic Server looks up range requests in the cache.

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. This is rarely useful (at the moment), since it'll only be able to write to cache if the origin has ignored the Range: header. For a use case where you know the origin will respond with a full (200) response, you can turn this on to allow it to be cached.

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.



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.



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.



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.



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.

CONFIG.TP Type INT.TP Default 0.UNINDENT Specifies the maximum object size that will be cached. 0 is unlimited.

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.

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.

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 evacutating 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).


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.


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.

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.

CONFIG.TP Type INT.TP Default 4096.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.


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)

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)

CONFIG.TP Type INT.TP Default 1.UNINDENT Two distinct RAM caches are supported, the default (0) being the CLFUS (Clocked Least Frequently Used by Size). As an alternative, a simpler LRU (Least Recently Used) cache is also available, by changing this configuration to 1.

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.

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.


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.

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.

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.

CONFIG.TP Type INT.TP Default 0.TP Reloadable Yes.TP Overridable Yes.UNINDENT Establishes a guaranteed minimum lifetime boundary for freshness heuristics. When heuristics are used, and the proxy.config.http.cache.heuristic_lm_factor aging factor is applied, the final minimum age calculated will never be lower than the value in this variable.

CONFIG.TP Type INT.TP Default 31536000.TP Reloadable Yes.TP Overridable Yes.UNINDENT Establishes a guaranteed maximum lifetime boundary for freshness heuristics. When heuristics are used, and the proxy.config.http.cache.heuristic_lm_factor aging factor is applied, the final maximum age calculated will never be higher than the value in this variable.

CONFIG.TP Type INT.TP Default 0.TP Reloadable Yes.TP Overridable Yes.TP Deprecated Yes.UNINDENT How often Traffic Server checks for an early refresh, during the period before the document stale time. The interval specified must be in seconds.

NOTE:

Previous versions of Apache Traffic Server defaulted this to 240s. This feature is deprecated as of ATS v6.2.0.



CONFIG.TP Type FLOAT.TP Default 0.0.TP Reloadable Yes.TP Overridable Yes.TP Deprecated Yes.UNINDENT The probability that a refresh is made on a document during the fuzz time specified in proxy.config.http.cache.fuzz.time.

NOTE:

Previous versions of Apache Traffic Server defaulted this to 0.005 (0.5%). This feature is deprecated as of ATS v6.2.0



CONFIG.TP Type INT.TP Default 0.TP Reloadable Yes.TP Overridable Yes.TP Deprecated Yes.UNINDENT Handles requests with a TTL less than proxy.config.http.cache.fuzz.time. It allows for different times to evaluate the probability of revalidation for small TTLs and big TTLs. Objects with small TTLs will start "rolling the revalidation dice" near the fuzz.min_time, while objects with large TTLs would start at fuzz.time. A logarithmic-like function between determines the revalidation evaluation start time (which will be between fuzz.min_time and fuzz.time). As the object gets closer to expiring, the window start becomes more likely. By default this setting is not enabled, but should be enabled any time you have objects with small TTLs.

NOTE:

These fuzzing options are marked as deprecated as of v6.2.0, and will be removed for v7.0.0. Instead, we recommend looking at the new proxy.config.http.cache.open_write_fail_action configuration and the features around thundering heard avoidance (see http-proxy-caching for details).



CONFIG.TP Type STRING.TP Default NULL.TP Reloadable Yes.TP Overridable Yes.UNINDENT The header on which Traffic Server varies for text documents.

For example: if you specify User-agent, then Traffic Server caches all the different user-agent versions of documents it encounters.


CONFIG.TP Type STRING.TP Default NULL.TP Reloadable Yes.TP Overridable Yes.UNINDENT The header on which Traffic Server varies for images.

CONFIG.TP Type STRING.TP Default NULL.TP Reloadable Yes.TP Overridable Yes.UNINDENT The header on which Traffic Server varies for anything other than text and images.

CONFIG.TP Type INT.TP Default 10.TP Reloadable Yes.UNINDENT
The number of milliseconds a cacheable request will wait before requesting the object from cache if an equivalent request is in flight.



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.



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.



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.


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.

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.

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.

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 predended to the file name to find in the template sets directory. See body-factory.

CONFIG.TP Type INT.TP Default 8192.TP Reloadable Yes.UNINDENT Maximum size of the error template response page.

CONFIG.TP Type INT.TP Default 0.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 intercepted traffic.

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 enpoint 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.

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).


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.

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.

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.

CONFIG.TP Type INT.TP Default 1.TP Reloadable Yes.UNINDENT Enables (1) or disables (0) DNS server round-robin.

CONFIG.TP Type STRING.TP Default NULL.TP Reloadable Yes.UNINDENT The DNS servers.

CONFIG.TP Type INT.TP Default 0.TP Reloadable Yes.TP Overridable Yes.UNINDENT Indicates whether to use SRV records for origin server lookup.

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).

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.

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.


CONFIG.TP Type INT.TP Default 30.TP Units seconds.TP Reloadable Yes.UNINDENT Time to wait for a DNS response in seconds.

See admin-performance-timeouts for more discussion on Traffic Server timeouts.


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.


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.

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.TP Type 16.TP Default *NONE*.UNINDENT The maximum count of DNS answers per round robin hostdb record. The default variable is 16.

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.

CONFIG.TP Type INT.TP Default 1440.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 admin-performance-timeouts for more discussion on Traffic Server timeouts.


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



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.


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.


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.


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.


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

CONFIG.TP Type STRING.TP Default NULL.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.

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


Resolve only to IPv4.

ipv4;only


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".



CONFIG.TP Type INT.TP Default 720.UNINDENT Set the interval (in seconds) in which to re-query DNS regardless of TTL status.

CONFIG.TP Type STRING.TP Default "host.db".UNINDENT The filename to persist hostdb to on disk.

CONFIG.TP Type INT.TP Default 120.UNINDENT Set the frequency (in seconds) to sync hostdb to disk.

Note: hostdb is syncd 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


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 admin-logging for more information on event logging.


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.



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. In collation client mode, if there is no local disk logging, or proxy.config.log.max_space_mb_for_orphan_logs is set to a higher value than proxy.config.log.max_space_mb_for_logs, Traffic Server will take proxy.config.log.max_space_mb_for_orphan_logs for maximum allowed log space.



CONFIG.TP Type INT.TP Default 25.TP Units megabytes.TP Reloadable Yes.UNINDENT The amount of space allocated to the logging directory (in MB) if this node is acting as a collation client.

NOTE:

When max_space_mb_for_orphan_logs is take as the maximum allowed log space in the logging system, the same rule apply to proxy.config.log.max_space_mb_for_logs also apply to proxy.config.log.max_space_mb_for_orphan_logs, ie: All files in the logging directory contribute to the space used, even if they are not log files. you may need to consider this when you enable full remote logging, and bump to the same size as proxy.config.log.max_space_mb_for_logs.



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 autodeletion of log files is triggered when the amount of free space available in the logging directory is less than the value specified here.

CONFIG.TP Type STRING.TP Default localhost.TP Reloadable Yes.UNINDENT The hostname of the machine running Traffic Server.

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.



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.


LOCAL.TP Type INT.TP Default 0.TP Reloadable Yes.TP Deprecated Yes.UNINDENT Set the log collation mode.
Value Effect
0 Log collation is disabled.
1 This host is a log collation server.
2 This host is a collation client and sends entries using standard formats to the collation server.
3 This host is a collation client and sends entries using the traditional custom formats to the collation server.
4 This host is a collation client and sends entries that use both the standard and traditional custom formats to the collation server.

For information on sending custom formats to the collation server, refer to admin-logging-collating-custom-formats and logging.yaml.

NOTE:

Log collation is a deprecated feature as of ATS v8.0.0, and will be removed in ATS v9.0.0. Our recommendation is to use one of the many existing log collection tools, such as Kafka, LogStash, FileBeat, Fluentd or even syslog / syslog-ng.



CONFIG.TP Type STRING.TP Default NULL.TP Deprecated Yes.UNINDENT The hostname of the log collation server.

CONFIG.TP Type INT.TP Default 8085.TP Reloadable Yes.TP Deprecated Yes.UNINDENT The port used for communication between the collation server and client.

CONFIG.TP Type STRING.TP Default foobar.TP Reloadable Yes.TP Deprecated Yes.UNINDENT The password used to validate logging data and prevent the exchange of unauthorized information when a collation server is being used.

CONFIG.TP Type INT.TP Default 0.TP Reloadable Yes.TP Deprecated Yes.UNINDENT When enabled (1), configures Traffic Server to include the hostname of the collation client that generated the log entry in each entry.

CONFIG.TP Type INT.TP Default 5.TP Reloadable Yes.TP Deprecated Yes.UNINDENT The number of seconds between collation server connection retries.

CONFIG.TP Type INT.TP Default 86390.TP Deprecated Yes.UNINDENT The number of seconds before inactivity time-out events for the host side. This setting over-rides the default set with proxy.config.net.default_inactivity_timeout for log collation connections.

The default is set for 10s less on the host side to help prevent any possible race conditions. If the host disconnects first, the client will see the disconnect before its own time-out and re-connect automatically. If the client does not see the disconnect, i.e., connection is "locked-up" for some reason, it will disconnect when it reaches its own time-out and then re-connect automatically.


CONFIG.TP Type INT.TP Default 86400.TP Deprecated Yes.UNINDENT The number of seconds before inactivity time-out events for the client side. This setting over-rides the default set with proxy.config.net.default_inactivity_timeout for log collation connections.

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).

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.



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.

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.

CONFIG.TP Type INT.TP Default 1.TP Reloadable Yes.UNINDENT Enables (1) or disables (0) automatic deletion of rolled files.

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...

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

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.

CONFIG.TP Type STRING.TP Default logging.yaml.TP Reloadable 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.


CONFIG.TP Type STRING.TP Default E.UNINDENT

CONFIG.TP Type STRING.TP Default E.UNINDENT

CONFIG.TP Type STRING.TP Default L.UNINDENT

CONFIG.TP Type STRING.TP Default L.UNINDENT

CONFIG.TP Type STRING.TP Default L.UNINDENT

CONFIG.TP Type STRING.TP Default SL.UNINDENT

CONFIG.TP Type STRING.TP Default SL.UNINDENT

CONFIG.TP Type STRING.TP Default L.UNINDENT

CONFIG.TP Type STRING.TP Default SL.UNINDENT The diagnosic 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.

To log debug diagnostics to both syslog and diags.log:

CONFIG proxy.config.diags.output.debug STRING SL



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.

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.


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.

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.


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.


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).

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 bootup.

CONFIG.TP Type INT.TP Default 100.TP Units megabytes.TP Reloadable Yes.UNINDENT Specifies at what size to roll the diagnostics log at.


CONFIG.TP Type INT.TP Default 1.TP Reloadable Yes.UNINDENT Enables (1) or disables (0) HTTP reverse proxy.

CONFIG.TP Type STRING.TP Default NULL.TP Reloadable Yes.UNINDENT The URL to which to redirect requests with no host headers (reverse proxy).


CONFIG.TP Type STRING.TP Default remap.config.UNINDENT Sets the name of the remap.config file.

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.

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.


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, included in the records.config.default example configuration is:

ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:DHE-DSS-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-DSS-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA:ECDHE-RSA-AES256-SHA:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES128-SHA:DHE-RSA-AES256-SHA256:DHE-DSS-AES256-SHA256:DHE-RSA-AES128-SHA256:DHE-DSS-AES128-SHA256:DHE-RSA-AES256-SHA:DHE-DSS-AES256-SHA:DHE-RSA-AES128-SHA:DHE-DSS-AES128-SHA:AES256-GCM-SHA384:AES128-GCM-SHA256:AES256-SHA256:AES128-SHA256:AES256-SHA:AES128-SHA:DES-CBC3-SHA:!aNULL:!eNULL:!EXPORT:!DES:!RC4:!MD5:!PSK:!aECDH:!EDH-DSS-DES-CBC3-SHA:!EDH-RSA-DES-CBC3-SHA:!KRB5-DES-CBC3-SHA


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.

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 with OpenSSL is:

TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256

This configuration works with OpenSSL v1.1.1 and above.


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.

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.1.1 and above.


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.1.1 and above.


CONFIG.TP Type INT.TP Default 1.UNINDENT Enables (1) or disables (0) TLSv1.

CONFIG.TP Type INT.TP Default 1.UNINDENT Enables (1) or disables (0) TLS v1.1. If not specified, enabled by default. [Requires OpenSSL v1.0.1 and higher]

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]

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.

CONFIG.TP Type STRING.TP Default ssl_multicert.config.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



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.

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.

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.

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.

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.

CONFIG.TP Type STRING.TP Default NULL.UNINDENT The location of the certificate authority file that client certificates will be verified against.

CONFIG.TP Type STRING.TP Default NULL.UNINDENT The filename of the certificate authority that client certificates will be verified against.

CONFIG.TP Type STRING.TP Default ssl_ticket.key.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.

CONFIG.TP Type STRING.TP Default ssl_server_name.yaml.UNINDENT The filename of the ssl_server_name.yaml configuration file. If relative, it is relative to the configuration directory (ts:cv:proxy.config.config_dir).

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.


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.

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 admin-performance-timeouts for more discussion on Traffic Server timeouts.



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.

CONFIG.TP Type INT.TP Default 102400.UNINDENT This configuration specifies the maximum number of entries the SSL session cache may contain.

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.

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.

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.

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.

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.

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.


CONFIG.TP Type INT.TP Default 0.UNINDENT When enabled this limits the total duration for the server side SSL handshake.

See admin-performance-timeouts for more discussion on Traffic Server timeouts.


CONFIG.TP Type INT.TP Default 0.UNINDENT When enabled this turns on wire tracing of SSL connections that meet the conditions specified by wire_trace_percentage, wire_trace_addr and wire_trace_server_name.

CONFIG.TP Type INT.TP Default 0.UNINDENT This specifies the percentage of traffic meeting the other wire_trace conditions to be traced.

CONFIG.TP Type STRING.TP Default NULL.UNINDENT This specifies the client IP for which wire_traces should be printed.

CONFIG.TP Type STRING.TP Default NULL.UNINDENT This specifies the server name for which wire_traces should be printed.


CONFIG.TP Type INT.TP Default 0.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 between 0 to 2.
0
Server Certificate will not be verified
1
Certificate will be verified and the connection will not be established if verification fails.
2
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.


CONFIG.TP Type STRING.TP Default NULL.TP Overridable Yes.UNINDENT The filename of SSL client certificate installed on Traffic Server.

CONFIG.TP Type STRING.TP Default /config.UNINDENT The location of the SSL client certificate installed on Traffic Server.

CONFIG.TP Type STRING.TP Default NULL.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.

CONFIG.TP Type STRING.TP Default NULL.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.

CONFIG.TP Type STRING.TP Default NULL.UNINDENT The filename of the certificate authority against which the origin server will be verified.

CONFIG.TP Type STRING.TP Default NULL.UNINDENT Specifies the location of the certificate authority file against which the origin server will be verified.

CONFIG.TP Type INT.TP Default 0.UNINDENT Enables (1) or disables (0) SSLv3 in the ATS client context. Disabled by default

CONFIG.TP Type INT.TP Default 1.UNINDENT Enables (1) or disables (0) TLSv1 in the ATS client context. If not specified, enabled by default

CONFIG.TP Type INT.TP Default 1.UNINDENT Enables (1) or disables (0) TLSv1_1 in the ATS client context. If not specified, enabled by default

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

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.

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.


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.

CONFIG.TP Type INT.TP Default 3600.UNINDENT Number of seconds before an OCSP response expires in the stapling cache.

See admin-performance-timeouts for more discussion on Traffic Server timeouts.


CONFIG.TP Type INT.TP Default 10.UNINDENT Timeout (in seconds) for queries to OCSP responders.

See admin-performance-timeouts for more discussion on Traffic Server timeouts.


CONFIG.TP Type INT.TP Default 60.UNINDENT Update period (in seconds) for stapling caches.


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.



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.

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).

CONFIG.TP Type INT.TP Default 65535.TP Reloadable Yes.UNINDENT The initial window size for inbound connections.

CONFIG.TP Type INT.TP Default 16384.TP Reloadable Yes.UNINDENT Indicates the size of the largest frame payload that the sender is willing to receive.

CONFIG.TP Type INT.TP Default 4096.TP Reloadable Yes.UNINDENT The maximum size of the header compression table used to decode header blocks.

CONFIG.TP Type INT.TP Default 4294967295.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.

CONFIG.TP Type INT.TP Default 0.TP Reloadable Yes.UNINDENT Enable the experimental HTTP/2 Stream Priority feature.

CONFIG.TP Type INT.TP Default 0.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.


CONFIG.TP Type INT.TP Default 120.TP Reloadable Yes.TP Overridable 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.

CONFIG.TP Type INT.TP Default 120.TP Reloadable Yes.TP Overridable 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.

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.

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.

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.

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.

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.

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.


CONFIG.TP Type STRING.TP Default config/plugins.UNINDENT Specifies the location of Traffic Server plugins.

CONFIG.TP Type INT.TP Default 0.UNINDENT When this variable is set to 0, plugin remap callbacks are executed in line on network threads. If remap processing takes significant time, this can be cause additional request latency. Setting this variable to causes remap processing to take place on a dedicated thread pool, freeing the network threads to service additional requests.


CONFIG.TP Type INT.TP Default 0.UNINDENT Enables (1) or disables (0) the SOCKS processor

CONFIG.TP Type INT.TP Default 4.UNINDENT Specifies the SOCKS version (4) or (5)

CONFIG.TP Type STRING.TP Default socks.config.UNINDENT The socks_onfig 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.

CONFIG.TP Type INT.TP Default 100.UNINDENT The activity timeout value (in seconds) for SOCKS server connections.

See admin-performance-timeouts for more discussion on Traffic Server timeouts.


CONFIG.TP Type INT.TP Default 10.UNINDENT The timeout value (in seconds) for SOCKS server connection attempts.

See admin-performance-timeouts for more discussion on Traffic Server timeouts.


CONFIG.TP Type INT.TP Default 1.UNINDENT The total number of connection attempts allowed per SOCKS server, if multiple servers are used.

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

CONFIG.TP Type INT.TP Default 300.UNINDENT The timeout value (in seconds) for SOCKS server connection retry attempts.

See admin-performance-timeouts for more discussion on Traffic Server timeouts.


CONFIG.TP Type STRING.TP Default *NONE*.UNINDENT Default list of SOCKS servers and their ports.

CONFIG.TP Type INT.TP Default 300.UNINDENT The amount of time allowed between connection retries to a SOCKS server that is unavailable.

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.

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.

CONFIG.TP Type INT.TP Default 1080.UNINDENT Specifies the port on which Traffic Server accepts SOCKS traffic.

CONFIG.TP Type INT.TP Default 80.UNINDENT Specifies the port on which Traffic Server accepts HTTP proxy requests over SOCKS connections..


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.


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.

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

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

CONFIG.TP Type INT.TP Default 0.UNINDENT Sets the send buffer size for connections from the client to Traffic Server.

CONFIG.TP Type INT.TP Default 0.UNINDENT Sets the receive buffer size for connections from the client to Traffic Server.

CONFIG.TP Type INT.TP Default 0x5.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)


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.



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.

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.

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)


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.



CONFIG.TP Type INT.TP Default 0.UNINDENT Same as the command line option --accept_mss that sets the MSS for all incoming requests.

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



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



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



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



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 morefrequently. 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 admin-performance-timeouts for more discussion on Traffic Server timeouts.


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.

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

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.

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 a modern linux Kernel 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>_.


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.

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.

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.

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.

2022, dev@trafficserver.apache.org

May 21, 2022 8.0