RECORDS.CONFIG(5)

📦

version 9.2.5 · 5 versions

💖 records.config(5) 💖 — Apache Traffic Server, but make it cute 💅

✨ NAME ✨

okay so records.config is the config file, by default located in /usr/local/etc/trafficserver/. It's literally 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. periodt.

Note: The configuration directory, containing the SYSCONFDIR value specified at build time relative to the installation prefix, contains Traffic Server configuration files. The $TS_ROOT environment variable can be used alter the installation prefix at run time. The directory must allow read/write access for configuration reloads.

📝 FORMAT 📝

Each variable has the following format:

CONFIG variable_name DATATYPE variable_value

Data Type

A variable's type is defined by the DATATYPE and must be one of:

FLOAT — Floating point, expressed as a decimal number without units or exponents.
INT — Integers, expressed with or without unit prefixes (as described below).
STRING — String of characters up to the first newline. No quoting necessary.

Values

The variable_value must conform to the variable's type. For STRING, this is simply any character data until the first newline.

For integer (INT) variables, values are expressed as any normal integer, e.g. 32768. They can also be expressed using more human readable values using standard unit prefixes, e.g. 32K. The following prefixes are supported for all INT type configurations:

K — Kilobytes — equivalent to 1,024 bytes
M — Megabytes — equivalent to 1,048,576 bytes (10242)
G — Gigabytes — equivalent to 1,073,741,824 bytes (10243)
T — Terabytes — equivalent to 1,099,511,627,776 bytes (10244)

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

Additional Attributes

Deprecated

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

Reloadable

A variable marked as Reloadable can be updated via the command:

traffic_ctl config reload

This updates configuration parameters without restarting Traffic Server or interrupting the processing of requests.

Overridable

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

🎀 EXAMPLES 🎀

In the following example, the variable proxy.config.proxy_name is a STRING datatype with the value my_server. This means that the name of the Traffic Server proxy is my_server.

CONFIG proxy.config.proxy_name STRING my_server

If the server name should be that_server the line would be

CONFIG proxy.config.proxy_name STRING that_server

In the following example, the variable proxy.config.arm.enabled is a yes/no flag. A value of 0 (zero) disables the option; a value of 1 enables the option.

CONFIG proxy.config.arm.enabled INT 0

In the following example, the variable sets the time to wait for a DNS response to 10 seconds.

CONFIG proxy.config.hostdb.lookup_timeout INT 10

The last examples configures a 64GB RAM cache, using a human readable prefix.

CONFIG proxy.config.cache.ram_cache.size INT 64G

🌈 ENVIRONMENT OVERRIDES 🌈

Every records.config configuration variable can be overridden by a corresponding environment variable. This can be useful in situations where you need a static records.config but still want to tweak one or two settings. The override variable is formed by converting the records.config variable name to upper case, and replacing any dot separators with an underscore.

Overriding a variable from the environment is permanent and will not be affected by future configuration changes made in records.config or applied with traffic_ctl.

For example, we could override the proxy.config.product_company variable like this:

$ PROXY_CONFIG_PRODUCT_COMPANY=example traffic_manager &
$ traffic_ctl config get proxy.config.product_company

👑 CONFIGURATION VARIABLES 👑

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

System Variables

proxy.config.product_company
- Scope: CONFIG
- Type: STRING
- Default: Apache Software Foundation
- The name of the organization developing Traffic Server.
proxy.config.product_vendor
- Scope: CONFIG
- Type: STRING
- Default: Apache
- The name of the vendor providing Traffic Server.
proxy.config.product_name
- Scope: CONFIG
- Type: STRING
- Default: |TS|
- The name of the product.
proxy.config.proxy_name
- Scope: CONFIG
- Type: STRING
- Default: build_machine
- Reloadable: Yes
- The name of the Traffic Server node.
proxy.config.bin_path
- Scope: CONFIG
- Type: STRING
- Default: bin
- The location of the Traffic Server bin directory.
proxy.config.proxy_binary
- Scope: CONFIG
- Type: STRING
- Default: traffic_server
- The name of the executable that runs the traffic_server process.

If you want to set Environment Variables for traffic_server process, use a wrapper script like below.

CONFIG proxy.config.proxy_binary STRING start_traffic_server.sh

#!/bin/sh
export ASAN_OPTIONS=detect_leaks=1
/opt/ats/bin/traffic_server "$@"

proxy.config.proxy_binary_opts
- Scope: CONFIG
- Type: STRING
- Default: -M
- The command-line options for starting Traffic Server.
proxy.config.manager_binary
- Scope: CONFIG
- Type: STRING
- Default: traffic_manager
- The name of the executable that runs the traffic_manager process.
proxy.config.memory.max_usage
- Scope: CONFIG
- Type: INT
- Default: 0
- Units: bytes
- Throttle incoming connections if resident memory usage exceeds this value. Setting the option to 0 disables the feature.
proxy.config.env_prep
- Scope: CONFIG
- Type: STRING
- Default: *NONE*
- The script executed before the traffic_manager process spawns the traffic_server process.
proxy.config.syslog_facility
- Scope: CONFIG
- Type: STRING
- Default: LOG_DAEMON
- The facility used to record system log files. Refer to Understanding Traffic Server Logs for more in-depth discussion of the contents and interpretations of log files.
proxy.config.output.logfile
- Scope: CONFIG
- Type: STRING
- Default: traffic.out
- This is used for log rolling configuration so Traffic Server knows the path of the output file that should be rolled. This configuration takes the name of the file receiving traffic_server and traffic_manager process output that is set via the --bind_stdout and --bind_stderr command-line options. proxy.config.output.logfile is used only to identify the name of the output file for log rolling purposes and does not override the values set via --bind_stdout and --bind_stderr.

If a filename is passed to this option, then it will be interpreted relative to proxy.config.log.logfile_dir. If a different location is desired, then pass an absolute path to this configuration.

proxy.config.output.logfile_perm

Okay bestie, next up on the config tour: the log file permission joint. 💅

Scope CONFIG. Type STRING. Default rw-r--r--.

This one is the log file permissions for the file that's catching Traffic Server output — and the path of that file is set with the --bind_stdout and --bind_stderr command-line options. It uses the standard UNIX file permissions (owner, group, other). Here's what you're allowed to put in:

- — no permissions, nada, zero, nothing.
r — read permission.
w — write permission.
x — execute permission.

Heads up: permissions are subject to the umask settings for the Traffic Server process. So like, a umask setting of 002 will not allow write permission for others, even if you specified it in the configuration file. And permissions for existing log files are not changed when the config is modified. So don't come crying to me, it literally says so. 😭

proxy.config.output.logfile.rolling_enabled — Scope CONFIG. Type INT. Default 0. Reloadable Yes.

Specifies how the output log is rolled. The values you can give it:

0 — Disables output log rolling. Nope, not today.
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. Iconic overachiever behaviour, honestly. 👑
proxy.config.output.logfile.rolling_interval_sec — Scope CONFIG. Type INT. Default 3600. Units seconds. Reloadable Yes.

Specifies how often the output log is rolled, in seconds. The timer starts on Traffic Server startup.

proxy.config.output.logfile.rolling_size_mb — Scope CONFIG. Type INT. Default 100. Units megabytes. Reloadable Yes.

Specifies at what size to roll the output log at.

proxy.config.output.logfile.rolling_min_count — Scope CONFIG. Type INT. Default 0. Reloadable Yes.

Specifies the minimum count of rolled output logs to keep. This value gets used to decide the order of auto-deletion (if it's enabled). A default value of 0 means auto-deletion will try to keep output logs as much as possible. See Log Rotation and Retention for guidance, bestie. 📚

🧵 Thread Variables 🧵

proxy.config.exec_thread.autoconfig — Scope CONFIG. Type INT. Default 1.

When it's enabled (and yes, the default is 1), Traffic Server scales threads according to the available CPU cores. See the config option below. 👇

proxy.config.exec_thread.autoconfig.scale — Scope CONFIG. Type FLOAT. Default 1.0.

Factor by which Traffic Server scales the number of threads. The multiplier is usually the number of available CPU cores. By default this scaling factor is 1.0. (Yes, the original says "this is scaling factor" — the vibes are chaotic but the number is real. 🙈)

proxy.config.exec_thread.limit — Scope CONFIG. Type INT. Default 2.

The number of threads Traffic Server will create if proxy.config.exec_thread.autoconfig is set to 0. Otherwise? This option is just ignored. Ghosted. 💀

proxy.config.exec_thread.listen — Scope CONFIG. Type INT. Default 0.

If enabled (1), all the exec_threads listen for incoming connections. And psst — proxy.config.accept_threads should be disabled to enable this variable. They're a package deal, iykyk.

proxy.config.accept_threads — Scope CONFIG. Type INT. Default 1.

The number of accept threads. If disabled (0), then accepts will be done in each of the worker threads. Here's the whole crossover episode:

accept_threads 0, exec_thread.listen 0 — All worker threads accept new connections and share listen fd.
accept_threads 1, exec_thread.listen 0 — New connections are accepted on a dedicated accept thread and distributed to worker threads in round robin fashion. 🔄
accept_threads 0, exec_thread.listen 1 — All worker threads listen on the same port using SO_REUSEPORT. Each thread has its own listen fd and new connections are accepted on all the threads.

By default, proxy.config.accept_threads is set to 1 and proxy.config.exec_thread.listen is set to 0. Periodt.

proxy.config.thread.default.stacksize — Scope CONFIG. Type INT. Default 1048576.

Default thread stack size, in bytes, for all threads (that default is 1 MB, bestie). 🌸

proxy.config.exec_thread.affinity — Scope CONFIG. Type INT. Default 1.

Bind threads to specific processing units. The menu:

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. (Yes, "affect". We are nothing if not faithful to the source. 💖)

proxy.config.system.file_max_pct — and this one is about to get its whole moment, so stay tuned… 🦋

Set the maximum number of file handles for the traffic_server process as a percentage of the fs.file-max proc value in Linux. The default is 90%. So like, ninety percent of whatever Linux says you're allowed, bestie. 🎀

`proxy.config.crash_log_helper`

Scope: CONFIG
Type: STRING
Default: traffic_crashlog

This one tells traffic_server to spawn a crash log helper at startup. The value should be the path to an executable program. If that path is not absolute, it gets located relative to the configured bin directory. Any user-provided program you put here has to behave in a fashion compatible with traffic_crashlog — specifically, it must implement the traffic_crashlog --wait behavior. No cap. 👑

This setting is not reloadable, because the helper must be spawned before traffic_server drops privilege. If this variable is set to NULL, no helper will be spawned. 💀

`proxy.config.restart.active_client_threshold`

Scope: CONFIG
Type: INT
Default: 0
Reloadable: Yes

Specifies the number of active client connections for use by traffic_ctl server restart --drain. That's the whole vibe. ✨

`proxy.config.restart.stop_listening`

Scope: CONFIG
Type: INT
Default: 0
Reloadable: Yes

This option says whether Traffic Server should close listening sockets while shutting down gracefully. The tea:

0 — Listening sockets will be kept open.
1 — Listening sockets will be closed when Traffic Server starts shutting down.

`proxy.config.stop.shutdown_timeout`

Scope: CONFIG
Type: INT
Default: 0
Reloadable: Yes

The shutdown timeout (in seconds) to apply when stopping Traffic Server, in which ATS can initiate graceful shutdowns. To actually effect graceful shutdown, the value you specify should be greater than 0. A value of 0 will not effect an abrupt shutdown. Abrupt shutdowns can be achieved without specifying --drain — that's traffic_ctl server stop / restart. "Stopping Traffic Server" here means sending traffic_server a signal, either via bin/trafficserver stop or kill. 💅

`proxy.config.thread.max_heartbeat_mseconds`

Scope: CONFIG
Type: INT
Default: 60
Units: milliseconds

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 you're 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. Like, do not just poke it for fun, bestie. 🙈

NETWORK 🌐

`proxy.config.net.additional_accepts`

Scope: CONFIG
Type: INT
Default: -1
Reloadable: Yes

This config addresses an issue that can sometimes happen if threads are caught in a net accept while loop, become busy exclusively accepting connections, and are prevented from doing other work. That causes an increase in latency and average event loop time. 😭

Here's the breakdown:

When set to 0, a thread accepts only 1 connection per event loop.
When set to any other positive integer x, a thread will accept up to x+1 connections per event loop.
When set to -1 (the default), a thread will accept connections as long as there are connections waiting in its listening queue — that's equivalent to "accept all", and setting to 0 is equivalent to "accept one".

`proxy.config.net.connections_throttle`

Scope: CONFIG
Type: INT
Default: 30000

The total number of client and origin server connections that the server can handle simultaneously. Fr fr, this is 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 — so from the default, only ~27,000 client connections can be handled. Tune this according to your memory size and expected work load.

If this is set to 0, the throttling logic is disabled. 💀

`proxy.config.net.max_connections_in`

Scope: CONFIG
Type: INT
Default: 30000

The total number of client requests that Traffic Server can handle simultaneously. Tune it according to your memory size and expected work load (network, cpu etc). This limit includes both idle (keep alive) connections and active requests that Traffic Server can handle at any given instant. The delta between proxy.config.net.max_connections_in and proxy.config.net.max_requests_in is the amount of maximum idle (keepalive) connections Traffic Server will maintain. Math is math. 🧚

`proxy.config.net.max_requests_in`

Scope: CONFIG
Type: INT
Default: 0

The total number of concurrent requests or active client connections that the Traffic Server can handle simultaneously. Tune according to your memory size, and expected work load (network, cpu etc).

When set to 0, active request tracking is disabled and max requests has no separate limit — the total connections follow proxy.config.net.connections_throttle. 👑

`proxy.config.net.default_inactivity_timeout`

Scope: CONFIG
Type: INT
Default: 86400
Reloadable: Yes

The connection inactivity timeout (in seconds) to apply when Traffic Server detects that no inactivity timeout has been applied by the HTTP state machine. When this timeout is applied, the proxy.process.net.default_inactivity_timeout_applied metric is incremented. ✨

See Timeout Settings for more discussion on Traffic Server timeouts.

`proxy.config.net.inactivity_check_frequency`

Scope: CONFIG
Type: INT
Default: 1

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. Lowkey a lifesaver. 💖

`proxy.local.incoming_ip_to_bind`

Scope: LOCAL
Type: STRING
Default: 0.0.0.0 [::]

Controls the global default IP addresses to which to bind proxy server ports. The value is a space separated list of IP addresses, one per supported IP address family (currently IPv4 and IPv6). 🌈

Unless explicitly specified in proxy.config.http.server_ports, the server port will be bound to one of these addresses, selected by IP address family. The built in default is any address. This is used if no address for a family is specified. This setting is useful if most or all server ports should be bound to the same address.

NOTE: This is ignored for inbound transparent server ports because they must be able to accept connections on arbitrary IP addresses. No exceptions, bestie. 🙈

Example

Set the global default for IPv4 to 192.168.101.18 and leave the global default for IPv6 as any address:

LOCAL proxy.local.incoming_ip_to_bind STRING 192.168.101.18

Example

Set the global default for IPv4 to 191.68.101.18 and the global default for IPv6 to fc07:192:168:101::17:

LOCAL proxy.local.incoming_ip_to_bind STRING 192.168.101.18 [fc07:192:168:101::17]

`proxy.local.outgoing_ip_to_bind`

Scope: LOCAL
Type: STRING
Default: 0.0.0.0 [::]

This controls the global default for the local IP address for outbound connections to origin servers. The value is a list of space separated IP addresses, one per supported IP address family (currently IPv4 and IPv6). 🦋

Unless explicitly specified in proxy.config.http.server_ports, one of these addresses — selected by IP address family — will be used as the local address for outbound connections. This setting is useful if most or all of the server ports should use the same outbound IP addresses.

NOTE: This is ignored for outbound transparent ports, as the local outbound address will be the same as the client local address. Periodt. 💅

Example

Set the default local outbound IP address for IPv4 connections to 192.168.101.18.:

LOCAL proxy.local.outgoing_ip_to_bind STRING 192.168.101.18

Example

Set the default local outbound IP address to 192.168.101.17 for IPv4 and fc07:192:168:101::17 for IPv6.:

LOCAL proxy.local.outgoing_ip_to_bind STRING 192.168.101.17 [fc07:192:168:101::17]

`proxy.config.net.event_period`

Scope: CONFIG
Type: INT
Default: 10

How often, in milli-seconds, to schedule IO event processing. This is unlikely to be necessary to tune, and we discourage setting it to a value smaller than 10ms (on Linux). Like, just leave it alone. 🙏

`proxy.config.net.accept_period`

Scope: CONFIG
Type: INT
Default: 10

How often, in milli-seconds, to schedule accept() processing. This is unlikely to be necessary to tune, and we discourage setting it to a value smaller than 10ms (on Linux). 🎀

`proxy.config.net.retry_delay`

Scope: CONFIG
Type: INT
Default: 10
Reloadable: Yes

How long to wait until we retry various events that would otherwise block the network processing threads (e.g. locks). We discourage setting this to a value smaller than 10ms (on Linux). ⭐

`proxy.config.net.throttle_delay`

Scope: CONFIG
Type: INT
Default: 50
Reloadable: Yes

When we trigger a throttling scenario, this is how long our accept() are delayed. That's it, that's the whole thing. 💖

👑 LOCAL MANAGER 👑

proxy.node.config.manager_log_filename — scope CONFIG, type STRING, default manager.log.

This is the name of the file where all the traffic_manager logs get dropped. 📝

And if you set it to stdout or stderr? Then literally all traffic_manager logging goes to that stream instead. iykyk. ✨

proxy.config.admin.user_id — scope CONFIG, type STRING, default nobody.

This picks the non-privileged account that the traffic_server process runs as, which also lowkey sets the ownership of your config files and log files. two birds, one stone, iconic. 🫶

If the user_id starts with a pound character (#), then everything after it is treated as a numeric user identifier. And if the value is #-1, Traffic Server will not change the user during startup at all.

IMPORTANT: Trying to set this option to root or #0 is now forbidden, bestie — it's a whole security measure. Doing it causes a fatal failure upon startup in traffic_server. But 😭 there are two ways to bypass this restriction: - Specify -DBIG_SECURITY_HOLE in CXXFLAGS during compilation. - Set the user_id=#-1 and start trafficserver as root.

proxy.config.admin.api.restricted — scope CONFIG, type INT, default 0.

This one says whether the management API should be restricted to root processes only. Set it to 0 and, on platforms that support passing process credentials, non-root processes get to make read-only management API calls. Any management API call that actually modifies server state (like setting a configuration variable, bestie) is still restricted to root processes. no exceptions. 💅

This setting is not reloadable, since it must be applied when traffic_manager initializes.

proxy.config.track_config_files — scope CONFIG, type INT, default 1.

Enables (1) or disables (0) tracking of configuration file updates. It's enabled by default, meaning your config files get monitored for changes. Having tracking on is a dependency for traffic_ctl config status to function, so like… that's the tradeoff. 🎀

BUT. The tracking is implemented via a frequent call to stat(), which may be problematic in some deployments. If that stat() call on configuration files is causing you problems, you can avoid it by setting this value to 0 — at the cost of disabling the config status feature for traffic_ctl.

This setting is not reloadable, since it must be applied when traffic_manager initializes.

proxy.node.config.manager_exponential_sleep_ceiling — scope CONFIG, type INT, default 60.

So if traffic_manager can't start traffic_server, this sets the maximum number of seconds the traffic_manager process should wait before it tries again to restart traffic_server. When it fails to start traffic_server, it retries exponentially until it hits the ceiling time. 📈

proxy.node.config.manager_retry_cap — scope CONFIG, type INT, default 5.

This is how many times traffic_manager will retry restarting traffic_server once that maximum ceiling time is reached. 🔁

NOTE: If set to 0, no cap will take place.

🚨 ALARM CONFIGURATION 🚨

proxy.config.alarm.abs_path — scope CONFIG, type STRING, default NULL, reloadable Yes.

The absolute path to the directory holding the alarm script. If you don't set it, the script gets located relative to proxy.config.bin_path. 📂

proxy.config.alarm.script_runtime — scope CONFIG, type INT, default 5, reloadable Yes.

How many seconds Traffic Server lets the alarm script run before it just aborts it. ⏰ bye.

🌐 HTTP ENGINE 🌐

proxy.config.http.server_ports — scope CONFIG, type STRING, default 8080 8080:ipv6.

These are the ports used for proxying HTTP traffic. 🛰️

It's 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, and the ones that do are specifically noted. Keywords with values can have an optional = character separating the keyword and the 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, but make it a list because we're cute like that: ✨

number — Required — The local port.
blind — Blind (CONNECT) port.
compress — Not Implemented — Compressed.
ipv4 — Default — Bind to IPv4 address family.
ipv6 — Bind to IPv6 address family.
ip-in — Value — Local inbound IP address.
ip-out — Value — Local outbound IP address.
ip-resolve — Value — IP address resolution style.
proto — Value — List of supported session protocols.
pp — Enable Proxy Protocol.
ssl — SSL terminated.
quic — QUIC terminated.
tr-full — Fully transparent (inbound and outbound)
tr-in — Inbound transparent.
tr-out — Outbound transparent.
tr-pass — Pass through enabled.
mptcp — Multipath TCP.

Now the receipts on each one: 🧾

number — the local IP port to bind. This is the port your ATS clients are gonna connect to. 📍
blind — accept only the CONNECT method on this port.

Not compatible with: tr-in, ssl and quic. 🚫

compress — compress the connection. Retained only by inertia, so it should be considered "not implemented". 💀
ipv4 — use IPv4. This is the default and it's included primarily for completeness. It's forced if the ip-in option is used with an IPv4 address.
ipv6 — use IPv6. It's forced if the ip-in option is used with an IPv6 address. 🦋
ssl — require SSL termination for inbound connections, periodt. SSL has to be configured for this option to give you a functional server port, no cap.

Not compatible with: blind and quic. 🙅‍♀️

quic — require QUIC termination for inbound connections. Again, SSL must be configured or the port won't actually work. THIS IS EXPERIMENTAL SUPPORT AND NOT READY FOR PRODUCTION USE. bestie I am BEGGING you, not in prod. 😭

Not compatible with: blind and ssl.

proto — specify the session level protocols supported. Separate them with semi-colons. For TLS proxy ports the default value is all available protocols. For non-TLS proxy ports the default is HTTP only. HTTP/3 is only available on QUIC ports. 💅
pp — enables Proxy Protocol on the port. If Proxy Protocol is enabled on the port, all incoming requests must be prefaced with the PROXY header. See Proxy Protocol for more details on how to configure this option properly. ✨
tr-full — fully transparent. This is a convenience option and is identical to specifying both tr-in and tr-out. 🪄

Not compatible with: any option not compatible with tr-in or tr-out.

tr-in — inbound transparent. The proxy port will accept connections to any IP address on the port. To have IPv6 inbound transparent you must use this and the ipv6 option. This overrides proxy.local.incoming_ip_to_bind for this port.

Not compatible with: ip-in, blind.

tr-out — outbound transparent. If ATS connects to an origin server for a transaction on this port, it will use the client's address as its local address. This overrides proxy.local.outgoing_ip_to_bind for this port.

Not compatible with: ip-out, ip-resolve.

tr-pass — transparent pass through. This option is useful only for inbound transparent proxy ports. If the parsing of the expected HTTP header fails, then the transaction is switched to a blind tunnel instead of generating an error response to the client. It effectively enables proxy.config.http.use_client_target_addr for the transaction as there is no other place to obtain the origin server address. 🫶
ip-in — set the local IP address for the port. This is the address to which clients will connect. This forces the IP address family for the port. The ipv4 or ipv6 can be used but it is optional and it is an error for it to disagree with the IP address family of this value. An IPv6 address must be enclosed in square brackets. If this option is omitted proxy.local.incoming_ip_to_bind is used.

Not compatible with: tr-in.

ip-out — set the local IP address for outbound connections. This is the address used by ATS locally when it connects to an origin server for transactions on this port. If this is omitted proxy.local.outgoing_ip_to_bind is used.

This option can be used multiple times, once for each IP address family. The address used is selected by the IP address family of the origin server address. 🦋

Not compatible with: tr-out.

ip-resolve — set the host resolution style for transactions on this proxy port.

Not compatible with: tr-out — this option requires a value of client;none which is forced and should not be explicitly specified.

mptcp — enable Multipath TCP on this proxy port. 🧚

Requires custom Linux kernel available at – https://multipath-tcp.org.

Example 🌸

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

80 80:ipv6

Example 🌸

Listen transparently on any IPv4 address on port 8080, and transparently on port 8080 on local address fc01:10:10:1::1 (which implies ipv6).:

IPv4:tr-FULL:8080 TR-full:IP-in=[fc02:10:10:1::1]:8080

Example 🌸

Listen on port 8080 for IPv6, fully transparent. Set up an SSL port on 443. These ports will use the IP address from proxy.local.incoming_ip_to_bind. Listen on IP address 192.168.17.1, port 80, IPv4, and connect to origin servers using the local address 10.10.10.1 for IPv4 and fc01:10:10:1::1 for IPv6.:

8080:ipv6:tr-full 443:ssl ip-in=192.168.17.1:80:ip-out=[fc01:10:10:1::1]:ip-out=10.10.10.1

Example 🌸

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

9090:proto=http2;http:ssl

Example 🌸

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

9090:proto=http:ssl

Example 🌸

Listen on port 4433 for QUIC connections.:

4433:quic

proxy.config.http.connect_ports

Scope: CONFIG · Type: STRING · Default: 443

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. Don't get it twisted. 💅

proxy.config.http.forward_connect_method

Scope: CONFIG · Type: INT · Default: 0 · Reloadable: Yes · Overridable: Yes

The default, Traffic Server behavior for handling a CONNECT method request is to establish a tunnel to the requested destination. This configuration alters the behavior so that Traffic Server forwards the CONNECT method to the next hop, and establishes the tunnel after receiving a positive response. This behavior is useful in a proxy hierarchy, and is equivalent to setting proxy.local.http.parent_proxy.disable_connect_tunneling to 0 when parent proxying is enabled. ✨

proxy.config.http.insert_request_via_str

Scope: CONFIG · Type: INT · Default: 1 · Reloadable: Yes · Overridable: Yes

Set how the Via field is handled on a request to the origin server. 🎀

Value 0 — do not modify or set this Via header.
Value 1 — add the basic protocol and proxy identifier.
Value 2 — add basic transaction codes.
Value 3 — add detailed transaction codes.
Value 4 — add full user agent connection protocol tags.

NOTE: the Via transaction codes can be decoded with the Via Decoder Ring.

proxy.config.http.request_via_str

Scope: CONFIG · Type: STRING · Default: ApacheTrafficServer/${PACKAGE_VERSION} · Reloadable: Yes · Overridable: Yes

Set the server and version string in the Via request header to the origin server which is inserted when the value of proxy.config.http.insert_request_via_str is not 0. 📝

Note that the actual default value is defined with "ApacheTrafficServer/" PACKAGE_VERSION in a C++ source code, and you must write such as ApacheTrafficServer/6.0.0 if you really set a value with the version in records.config file. If you want to hide the version, you can set this value to ApacheTrafficServer. 🕵️‍♀️

proxy.config.http.insert_response_via_str

Scope: CONFIG · Type: INT · Default: 0 · Reloadable: Yes · Overridable: Yes

Set how the Via field is handled on the response to the client. 🌈

Value 0 — do not modify or set this Via header.
Value 1 — add the basic protocol and proxy identifier.
Value 2 — add basic transaction codes.
Value 3 — add detailed transaction codes.
Value 4 — add full upstream connection protocol tags.

NOTE: the Via transaction code can be decoded with the Via Decoder Ring.

proxy.config.http.response_via_str

Okay so this next one is the Via header string bestie, and the way it's set up is:

Scope: CONFIG
Type: STRING
Default: ApacheTrafficServer/${PACKAGE_VERSION}
Reloadable: Yes
Overridable: Yes

It sets the server-and-version string that goes in the Via response header sent to the client — the one that gets slipped in when proxy.config.http.insert_response_via_str is not 0. 💅

Heads up: the actual default value is defined as "ApacheTrafficServer/" PACKAGE_VERSION in a C++ source file, so if you actually want to set a value that includes the version in records.config, you have to literally write something like ApacheTrafficServer/6.0.0 yourself. And if you're in your hide-the-version era, just set this to ApacheTrafficServer. 🫣

`proxy.config.http.send_100_continue_response`

Scope: CONFIG
Type: INT
Default: 0
Reloadable: Yes

You can specify one of these, bestie:

0 — Traffic Server will buffer the request until the post body has been received and then send the request to the origin server.
1 — Immediately return a 100 Continue from Traffic Server without waiting for the post body.

`proxy.config.http.response_server_enabled`

Scope: CONFIG
Type: INT
Default: 1
Reloadable: Yes
Overridable: Yes

You can specify one of these:

0 — No Server header is added to the response.
1 — The Server header is added according to proxy.config.http.response_server_str.
2 — The Server header is added only if the response from origin does not have one already.

`proxy.config.http.response_server_str`

Scope: CONFIG
Type: STRING
Default: ATS/${PACKAGE_VERSION}
Reloadable: Yes
Overridable: Yes

This is the Server string Traffic Server will insert in a response header (if requested, see above 👆). And fr fr, same lil caveat as before: the actual default value is defined as "ATS/" PACKAGE_VERSION in the C++ source, so you must write something like ATS/6.0.0 if you really want to set a value with the version in records.config. Want to hide the version? Set it to ATS. 🎀

`proxy.config.http.insert_age_in_response`

Scope: CONFIG
Type: INT
Default: 1
Reloadable: Yes
Overridable: Yes

This option says 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. ⏰

0 — No Age header is added.
1 — Age header is added.

`proxy.config.http.chunking_enabled`

Scope: CONFIG
Type: INT
Default: 1
Reloadable: Yes
Overridable: Yes

Specifies whether Traffic Server can generate a chunked response:

0 — Never respond with chunked encoding.
1 — Always respond with chunked encoding.
2 — Generate a chunked response if the origin server has previously returned HTTP/1.1.
3 — Generate a chunked response if the client request is HTTP/1.1 and the origin server has previously returned HTTP/1.1.

`proxy.config.http.chunking.size`

Scope: CONFIG
Type: INT
Default: 4096
Overridable: Yes

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 decides the size of the chunks, in bytes, to use when sending content to an HTTP/1.1 client. 📦

`proxy.config.http.drop_chunked_trailers`

Scope: CONFIG
Type: INT
Default: 0
Reloadable: Yes
Overridable: Yes

Specifies whether Traffic Server should drop chunked trailers. If enabled (1), Traffic Server will drop any chunked trailers in a Transfer-Encoded: chunked request or response body. If disabled (0), Traffic Server will pass the chunked trailers unmodified to the receiving peer. See RFC 9112, section 7.1.2 for the details about chunked trailers. By default, this option is disabled, so Traffic Server will not drop chunked trailers. 🦋

`proxy.config.http.send_http11_requests`

Scope: CONFIG
Type: INT
Default: 1
Reloadable: Yes
Overridable: Yes

Specifies when and how Traffic Server uses HTTP/1.1 to talk to the origin server:

0 — Never use HTTP/1.1.
1 — Always use HTTP/1.1.
2 — Use HTTP/1.1 with origin connections only if the server has previously returned HTTP/1.1.
3 — If the client request is HTTP/1.1 and the origin server has previously returned HTTP/1.1, then use HTTP/1.1 for origin server connections.

NOTE: If proxy.config.http.use_client_target_addr is set to 1, then options 2 and 3 for this configuration variable cause the proxy to use the client HTTP version for upstream requests. 👀

`proxy.config.http.auth_server_session_private`

Scope: CONFIG
Type: INT
Default: 1
Overridable: Yes

If enabled (1), anytime a request contains a Authorization, Proxy-Authorization, or Www-Authenticate header, the connection will be closed and not reused. This marks the connection as private. 🔒 When disabled (0), the connection will be available for reuse.

`proxy.config.http.server_session_sharing.match`

proxy.config.http.server_session_sharing.match

Scope: CONFIG · Type: STRING · Default: both · Overridable: Yes

okay so this one is the vibe check for re-using server connections across client connections 💅 you can pass more than one value if you separate them with commas and no white spaces (fr fr, the spaces will ruin it). Here's the whole menu of valid values:

none — do not match and do not re-use server sessions. Just... no. Nothing. Zero.
ip — re-use server sessions, checking only that the IP address and port of the origin server matches.
host — re-use server sessions, checking that the fully qualified domain name matches. Plus, if the session uses TLS, it also checks that the current transaction's host header value matches the session's SNI. multitasking queen ✨
both — equivalent to host,ip.
hostonly — check that the fully qualified domain name matches. That's it, that's the whole job.
sni — check that the SNI of the session matches the SNI that would be used to create a new session. Only applicable for TLS sessions, bestie.
cert — check that the certificate file name used for the server session matches the certificate file name that would be used for the new server session. Also only applicable for TLS sessions.

Your setting has to contain at least one of ip, host, hostonly or both for session reuse to actually operate. The other values are there so you can get extra fine-grained control with TLS session reuse. 🎀

NOTE: server sessions to different upstream ports never match even if the FQDN and IP address match. like, never ever.

NOTE: upstream session tracking uses a similar set of options for matching sessions, but it's set independently from session sharing. two separate sliders, two separate vibes.

proxy.config.http.server_session_sharing.pool

Scope: CONFIG · Type: STRING · Default: thread

This controls the scope of server session re-use, but only if it's already enabled by proxy.config.http.server_session_sharing.match. Valid values:

global — re-use sessions from a global pool of all server sessions.
thread — re-use sessions from a per-thread pool.
hybrid — try to work as a global pool, but release server sessions to the per-thread pool if there is lock contention on the global pool. the "why not both" option 🌈

Setting proxy.config.http.server_session_sharing.pool to global can reduce the number of connections to origin for some traffic loads. However — and this is the part where you go "oh" — if many execute threads are active, the thread contention on the global pool can reduce the lifetime of connections to origin and reduce effective origin connection reuse. sad but true 😭

For a hybrid pool, the operation starts as the global pool, but sessions are returned to the local thread pool if the global pool lock is not acquired, rather than just closing the origin connection like it does in standard global mode. it's giving "best of both worlds" 🦋

proxy.config.http.attach_server_session_to_client

Scope: CONFIG · Type: INT · Default: 0 · Overridable: Yes

This one controls the re-use of a server session by a user agent (client) session. Currently it only applies to user agents using HTTP/1.0 or HTTP/1.1. For other HTTP versions, the origin connection is always returned to the session sharing pool or closed — no exceptions, no negotiating.

So 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 just like for the first. This setting decides how that server session gets picked. 👑

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. very chill, very detached.

If this setting is not 0, then the current server session for the user agent session is "sticky". It will be preferred over any other server session (either from the pool or newly created). The server session only gets detached from the user agent session if it cannot be used for the transaction. And how do we know if it can be used? That's determined by the proxy.config.http.server_session_sharing.match value. If the server session matches the next transaction according to that setting, it gets used; otherwise it's released to the pool and a different session is selected or created. main character session energy, honestly 💅

proxy.config.http.max_proxy_cycles

Scope: CONFIG · Type: INT · Default: 0 · Overridable: Yes

Controls the proxy cycle detection function, and it does it like this:

If this setting is 0, then next hop is self IP address and port detection is active.

In addition, the proxy cycle detection using the Via string will declare a cycle if the current cache appears one or more times in the Via string, i.e, > 0.

If this setting is 1 or more (N), then next hop is self IP address and port detection is inactive.

In addition, the proxy cycle detection using the Via string will declare a cycle if the current cache appears more than N times in the Via string, i.e., > N.

Examples, because this is the part where everyone squints:

If the setting is 0, then the second time a request enters a cache it will have its own machine identifier in the Via string once, so a cycle will be detected. So no cycles are allowed.

If the setting is 1, then the third time a request enters a cache it will have its own machine identifier in the Via string twice, so a cycle will be detected. So one cycle is allowed. The first cycle with two visits to the cache and one instance in the Via string is allowed. The second cycle with three visits to the cache and two instances in the Via string is not allowed. ✨ math! ✨

This setting allows an edge cache peering arrangement where an edge cache may forward a request to a peer edge cache (possibly itself) a limited number of times (usually once). Infinite loops are still detected when the cycle allowance is exceeded. so you can loop a little, as a treat, but not forever 🌀

proxy.config.http.use_client_target_addr

Scope: CONFIG · Type: INT · Default: 0

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. But it only works if all three of these 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. no shortcuts, no skipping, just DNS doing its thing 🫶

So bestie, there are literally three valid values here, and you gotta pick one 💅

0 — Disables the feature. Bye. ✨
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).

🚨 ok this is the scary one: option 2 is vulnerable to cache poisoning if an incorrect Host header is specified, so this option should be used with extreme caution if HTTP caching is enabled. See bug TS-2954 for details. Not me being dramatic, that's literally in the docs 😭

If all of these conditions are met, then the origin server IP address is retrieved from the original client connection, rather than through HostDB or DNS lookup. In effect, client DNS resolution is used instead of Traffic Server DNS. 🦋

This can be used to be a little more efficient (looking up the target once by the client rather than by both the client and Traffic Server) but the primary use is when client DNS resolution can differ from that of Traffic Server. Two known uses cases are:

Embedded IP addresses in a protocol with DNS load sharing. In this case, even though Traffic Server and the client both make the same request to the same DNS resolver chain, they may get different origin server addresses. If the address is embedded in the protocol then the overall exchange will fail. One current example is Microsoft Windows update, which presumably embeds the address as a security measure. 🔍
The client has access to local DNS zone information which is not available to Traffic Server. There are corporate nets with local DNS information for internal servers which, by design, is not propagated outside the core corporate network. Depending a network topology it can be the case that Traffic Server can access the servers by IP address but cannot resolve such addresses by name. In such as case the client supplied target address must be used. 🏢

This solution must be considered interim. In the longer term, it should be possible to arrange for much finer grained control of DNS lookup so that wildcard domain can be set to use Traffic Server or client resolution. In both known use cases, marking specific domains as client determined (rather than a single global switch) would suffice. It is possible to do this crudely with this flag by enabling it and then use identity URL mappings to re-disable it for specific domains. 🧚

`proxy.config.http.keep_alive_enabled_in`

Scope: CONFIG
Type: INT
Default: 1
Overridable: Yes

Enables (1) or disables (0) incoming keep-alive connections. 🫶

`proxy.config.http.keep_alive_enabled_out`

Scope: CONFIG
Type: INT
Default: 1
Overridable: Yes

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. 💀 like, two separate things, don't get it twisted

`proxy.config.http.keep_alive_post_out`

Scope: CONFIG
Type: INT
Default: 1
Overridable: Yes

Controls whether new POST requests re-use keep-alive sessions (1) or create new connections per request (0). 🔥

`proxy.config.http.disallow_post_100_continue`

Scope: CONFIG
Type: INT
Default: 0

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. Counters go brrr 📈

`proxy.config.http.default_buffer_size`

Scope: CONFIG
Type: INT
Default: 8
Reloadable: Yes
Overridable: Yes

Configures the default buffer size, in bytes, to allocate for incoming request bodies which lack a Content-length header. 🌸

`proxy.config.http.default_buffer_water_mark`

Scope: CONFIG
Type: INT
Default: 32768
Reloadable: Yes
Overridable: Yes

Number of bytes Traffic Server is allowed to read ahead of the client from the origin. Note that when Read While Write settings are in place, this setting will apply to the first client to request the object, regardless if subsequent, simultaneous clients of that object can read faster. The buffered bytes will consume memory while waiting for the client to consume them. 🧠

While this setting is reloadable, dramatic changes can cause bigger memory usage than expected and is thus not recommended. Lowkey leave it alone bestie 💅

`proxy.config.http.request_buffer_enabled`

Scope: CONFIG
Type: INT
Default: 0
Overridable: Yes

This enables buffering the content for incoming POST requests. If enabled no outbound connection is made until the entire POST request has been buffered. If enabled, proxy.config.http.post_copy_size needs to be set to the maximum of the post body size allowed, otherwise, the post would fail. 😭 set both or it's giving broken

`proxy.config.http.request_line_max_size`

Scope: CONFIG
Type: INT
Default: 65535
Reloadable: Yes

Controls the maximum size, in bytes, of an HTTP Request Line in requests. Requests with a request line exceeding this size will be treated as invalid and rejected by the proxy. 🚫 Note that the HTTP request line typically includes HTTP method, request target and HTTP version string except when the request is made using absolute URI in which case the request line may also include the request scheme and domain name.

`proxy.config.http.header_field_max_size`

Scope: CONFIG
Type: INT
Default: 131070
Reloadable: Yes

Controls the maximum size, in bytes, of an HTTP header field in requests. Headers in a request with the sum of their name and value that exceed this size will cause the entire request to be treated as invalid and rejected by the proxy. 📏

`proxy.config.http.request_header_max_size`

Scope: CONFIG
Type: INT
Default: 131072
Reloadable: Yes
Overridable: Yes

Controls the maximum size, in bytes, of an HTTP header in requests. Headers in a request which exceed this size will cause the entire request to be treated as invalid and rejected by the proxy. 🛑

`proxy.config.http.response_header_max_size`

Scope: CONFIG
Type: INT
Default: 131072
Reloadable: Yes
Overridable: Yes

Controls the maximum size, in bytes, of headers in HTTP responses from the proxy. Any responses with a header exceeding this limit will be treated as invalid and a client error will be returned instead. 😵‍💫

`proxy.config.http.global_user_agent_header`

Scope: CONFIG
Type: STRING
Default: null
Overridable: Yes

An arbitrary string value that, if set, will be used to replace any request User-Agent header. ✨ main character energy, every request gets the same fit

`proxy.config.http.strict_uri_parsing`

Scope: CONFIG
Type: INT
Default: 2

Takes a value between 0 and 2. 🎀

0 — disables strict_uri_parsing. Any character can appears in the URI. (fr, anything goes)
1 — causes Traffic Server to return 400 Bad Request if client's request URI includes character which is not RFC 3986 compliant. 📜
2 — directs Traffic Server to reject the clients request if it contains whitespace or non-printable characters. 🧼

`proxy.config.http.errors.log_error_pages`

Scope: CONFIG
Type: INT
Default: 1
Reloadable: Yes

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