What’s New in ATS v10.2

This version of Apache Traffic Server™ includes 1039 commits from 655 pull requests, with 44 contributors participating in this development cycle.

Security Fixes

This release also contains all of the security fixes described in the July 2026 security advisory. Those fixes were committed directly to the release branch rather than through public pull requests, so they do not carry PR numbers; they are listed by commit subject at the end of CHANGELOG-10.2.0. Refer to the advisory for the CVE identifiers, severities, and affected version ranges.

Most of that work tightens what Traffic Server accepts rather than adding anything, so the operator-visible effect – changed defaults, messages now refused, ACL conditions that now apply as written, and plugins that now require configuration – is described under Security Hardening in Upgrading to ATS v10.2. Read that section before upgrading.

Further security fixes have landed on this branch since the 10.2.0 tag and ship in this maintenance release. Refer to the security advisory for this release for their identifiers, severities and affected version ranges. Security Hardening covers both sets. The surface those later fixes add, which a 10.2.0 installation does not have, is:

• proxy.config.http.reject_head_with_content, controlling whether a HEAD request carrying Content-Length or Transfer-Encoding is refused. Enabled by default.

• proxy.config.regex.anchor_policy_rules, which can require a regex driving a security or routing decision to match the whole subject. Disabled by default.

• proxy.process.ssl.user_agent_resumed_cert_rejected, counting inbound connections rejected because the session they resumed carried no client certificate where the current SNI’s verify_client policy requires one. Sessions are bound to the policy that issued them, so an out-of-scope session completes a full handshake rather than reaching this counter, which is normally zero.

• tsmemcache binds to the loopback address by default, with an optional second plugin argument to set the bind address. Earlier builds bound the wildcard address.

• magick requires a signing key and will not load without one, and allowlists the ImageMagick convert operators it will run.

Changes in 10.2.1

The 10.2.1 maintenance release adds 95 commits from 19 contributors to 10.2.0. Besides the security fixes above, the changes an operator or plugin author is likely to notice are below. The sections that follow describe 10.2 as a whole, including these changes where they touch the same feature. Behavior changes that need action before upgrading from 10.2.0 are collected under Changes in 10.2.1 in Upgrading to ATS v10.2.

• Per upstream server connection metrics. Setting proxy.config.http.per_server.connection.metric_enabled publishes current_connection, total_connection and blocked_connection for each upstream server group, and the new proxy.config.http.per_server.connection.metric_aggregate can instead publish only per hostname sums and a current_connection.max gauge, which keeps the metric count proportional to hostnames rather than to addresses. The optional proxy.config.http.per_server.connection.metric_prefix distinguishes metrics of separate match configurations. See Per Server Connection Metrics.

• The metrics store supports hidden metrics, which are recorded but never published, and MAX, MIN and incremental derived metrics. See the ts::Metrics documentation in the developer guide.

• Configuration reload accepts reload directives: operational parameters, such as scoping a reload to one entry, passed to a single handler with traffic_ctl config reload -D config_key.directive=value or under a _reload key in the RPC payload. They are delivered to the handler separately from the configuration content.

• HTTP/2 to the origin is considerably more robust: 1xx interim responses are handled, header blocks split across CONTINUATION frames are accepted, responses to HEAD and 304 are validated correctly, a half-closed or GOAWAY-draining session is no longer reused, one request’s Connection: close no longer poisons a long-lived session, and a request the origin reports as unprocessed (GOAWAY or REFUSED_STREAM) is retried when its body can be replayed. New counters proxy.process.http.origin.reuse_fail, proxy.process.http.origin.retry_admitted and proxy.process.http.origin.retry_body_unavailable expose this.

• proxy.config.http.cache.try_compat_key_read is now usable end to end: revalidating a legacy object stores the full response under the current key and invalidations are sent to both keys.

• The compress plugin adds Vary to cached client responses and sends a weak ETag for compressed responses.

• ja4_fingerprint and jax_fingerprint now follow the JA4 specification.

• hrw4u exits non-zero on compile errors, has a --version option, and its sandbox policy covers value functions, string interpolation, implicit NOT and in spellings, and the SESSION_VARS section.

• TSStatIdIsValid() lets a plugin validate a statistic index received from an external source before using it.

• A new tool generates the changelog from a GitHub milestone.

• Builds were fixed for LLVM 23 and Clang 21 and 23 diagnostics, OpenSSL 4 handshake buffers and certificate accessors, and Python 3.15.

Configuration Reload

Configuration reload has been rebuilt around a token model that makes a reload an observable, trackable operation rather than a fire-and-forget signal. Each reload gets a token; handlers report progress and terminal state against that token, so a reload can be monitored to completion and its per-handler logs inspected. See Configuration Reload Framework.

• traffic_ctl config reload gained --monitor/-m to follow a reload to completion, --show-details/-s and --include-logs/-l for per-handler detail, --token/-t to target a specific token, --refresh-int/-r and --timeout/-T to control polling, and --force/-F.

• traffic_ctl config status reports reload records for a token, with --count/-c (numeric or all) and --min-level to filter log severity.

• Reload behavior is tunable with proxy.config.admin.reload.timeout and proxy.config.admin.reload.check_interval.

• Replaced configurations are now destroyed on an ET_TASK thread rather than on a network thread, so a large config teardown no longer blocks an event loop.

Shared-Memory Cache Directory (Fast Restart)

The cache directory — the memory-resident index mapping cached objects to their location on disk — is normally rebuilt from disk on every start, which takes minutes on a large cache. It can now be hosted in POSIX shared memory so the next process start attaches the existing segment in milliseconds instead of rebuilding it.

Recovery is fail-safe: anything untrustworthy (crash, reboot, ABI or schema mismatch, failed validation, bad disk) falls back to the existing disk-rebuild path, and cache reads still validate the Doc magic and key, so a stale entry is a miss rather than served corruption.

The feature is opt-in and defaults to off, making it a functional no-op unless enabled:

• proxy.config.cache.shm.enabled

• proxy.config.cache.shm.name_prefix

• proxy.config.cache.shm.use_hugepages

• proxy.config.cache.shm.purge_stale_on_start

traffic_ctl cache shm status and traffic_ctl cache shm clear inspect and drop the segment. See Shared-Memory Cache Directory (Fast Restart) for the design, recovery model and platform notes.

Features

• traffic_ctl cache clear performs a logical cache purge by advancing the global HTTP cache generation, so a cache reset no longer requires restarting Traffic Server or hand-editing the cache generation. It is backed by a restricted JSONRPC method. See traffic_ctl cache and admin_cache_clear.

• Implement RFC 9213 Targeted HTTP Cache Control. Cache directives can be targeted at specific caches via headers such as CDN-Cache-Control, configured through proxy.config.http.cache.targeted_cache_control_headers, which is overridable per remap rule. When a targeted header is present it takes precedence over the standard Cache-Control header, and the targeted header is passed downstream so cache hierarchies behave correctly.

• Connect retries to the origin can now back off exponentially, controlled by proxy.config.http.connect_attempts_retry_backoff_base, instead of retrying immediately and piling connections onto a struggling origin.

• Origin connect retry limits are now selected by HostDB state: proxy.config.http.connect_attempts_max_retries for UP servers, the new proxy.config.http.connect_attempts_max_retries_suspect_server for SUSPECT, and no retries for DOWN. The retry limits were not previously applied according to origin state, so this is a necessary incompatible change. See Upgrading to ATS v10.2 before deploying.

• proxy.config.http.connect.down.policy gained option 3, which counts inactive connections as failures.

• Snowflake IDs, 64-bit organizationally unique identifiers, are now used for connection IDs so they are unique across restarts and typically across instances in a CDN.

• TLS certificate compression is supported in both directions, configured with proxy.config.ssl.server.cert_compression.algorithms and proxy.config.ssl.client.cert_compression.algorithms.

• Certificate loading can now be parallelized with proxy.config.ssl.server.multicert.concurrency.

• sni.yaml supports session ticket overrides.

• QUIC token secrets are configurable via proxy.config.quic.server.token_key.filename.

• The PROXY protocol header size limit is configurable with proxy.config.proxy_protocol.max_header_size.

• A per-client connection limit exempt list is available through proxy.config.http.per_client.connection.exempt_list, the new connection_exempt_list plugin, and the TS API (see below).

• Parsed values for expensive STRING configurations (for example negative_caching_list, insert_forwarded, server_session_sharing.match) are now cached automatically, so repeated TSHttpTxnConfigStringSet() calls with the same value parse only once.

• The migration from PCRE to PCRE2 is complete; all remaining PCRE references have been removed from the core and plugins.

Configuration

New records.yaml settings in this release:

• proxy.config.admin.reload.timeout

• proxy.config.admin.reload.check_interval

• proxy.config.cache.default_volumes

• proxy.config.cache.dir.sync_parallel_tasks

• proxy.config.cache.ram_cache.s3fifo.ghost_mem_percent

• proxy.config.cache.ram_cache.s3fifo.ghost_size_percent

• proxy.config.cache.ram_cache.s3fifo.main_percent

• proxy.config.cache.ram_cache.s3fifo.promote_threshold

• proxy.config.cache.shm.enabled

• proxy.config.cache.shm.name_prefix

• proxy.config.cache.shm.purge_stale_on_start

• proxy.config.cache.shm.use_hugepages

• proxy.config.exec_thread.loop_time_update_probability

• proxy.config.exec_thread.watchdog.timeout_ms

• proxy.config.http.cache.targeted_cache_control_headers

• proxy.config.http.connect_attempts_max_retries_suspect_server

• proxy.config.http.connect_attempts_retry_backoff_base

• proxy.config.http.parent_proxy.consistent_hash_algorithm

• proxy.config.http.per_client.connection.exempt_list

• proxy.config.proxy_protocol.max_header_size

• proxy.config.quic.server.token_key.filename

• proxy.config.ssl.client.cert_compression.algorithms

• proxy.config.ssl.server.cert_compression.algorithms

• proxy.config.ssl.server.multicert.concurrency

Other configuration changes:

• proxy.config.http2.default_buffer_water_mark now defaults to 32768 and no longer accepts values below 1024.

• proxy.config.http.header_field_max_size and proxy.config.hostdb.round_robin_max_count are now range checked, at 0 to 65535 and 1 to 1024 respectively. Their defaults are unchanged, but a value outside the range is no longer accepted.

• ip_allow.yaml ships default outbound rules denying CONNECT tunnels to unspecified, loopback, private, link-local and IPv4-mapped IPv6 destinations.

• proxy.config.ssl.max_record_size now accepts the documented -1 value, making dynamic TLS record sizing reachable from records.yaml.

• proxy.config.ssl.client.CA.cert.filename is now overridable.

• negative_caching_list and negative_revalidating_list are overridable.

• traffic_ctl config reset resets configuration values matching a path pattern back to their defaults.

• traffic_ctl hostdb status is a new command for inspecting HostDB state.

• traffic_ctl gained a global --watch/-w option to re-run a command periodically.

• JSONRPC now refuses writes to records marked RECA_READ_ONLY or RECA_NO_ACCESS.

Metrics

• Added proxy.process.http.000_responses

• Added proxy.process.http.429_responses

• Added proxy.process.log.marshalled_bytes

• Added proxy.process.net.per_client.connections_exempt_in

• Added proxy.process.ssl.connections_closed

• Added proxy.process.ssl.total_handshake_bytes_read_in

• Added proxy.process.ssl.total_handshake_bytes_write_out

• Added proxy.process.ssl.ssl_session_cache_timeout

• Added proxy.process.ssl.ssl_origin_session_cache_timeout

• Added proxy.process.ssl.handshake_sign_rsa, proxy.process.ssl.handshake_sign_ecdsa and proxy.process.ssl.handshake_sign_other to count handshake signatures by key type

• Added TLS certificate compression counters proxy.process.ssl.cert_compress.{zlib,brotli,zstd} and proxy.process.ssl.cert_decompress.{zlib,brotli,zstd}, each with a matching _failure counter

• Added proxy.process.plugin.header_rewrite.conditions and proxy.process.plugin.header_rewrite.operators

• Added proxy.process.plugin.compress.bytes_in

• Added per-plugin workload counters under the proxy.process.plugin. prefix

• Added per-curve TLS handshake time metrics and a cache stripe lock contention metric

• proxy.process.http.incoming_requests is now counted at transaction start

Logging

New log fields in this release:

• chiv - verified client host IP

• ckh - cache key hash

• cqqtl - client request squid length including TLS overhead

• cqssrt - TLS session resumption type

• cthb, cthbr, cthbt - client TLS handshake bytes (total, received, transmitted)

• mstsms - server-side TLS handshake milestone

• pptc, pptg, pptv - PROXY protocol TLS cipher, group and version

• prscs - the component that set the proxy response status code

• psfid - process Snowflake ID

• psqtl - proxy response squid length including TLS overhead

Other logging changes:

• Plugins can register custom log fields at runtime with TSLogFieldRegister and the TSLog*Marshal functions.

• Added the ERR_TUN_ACTIVE_TIMEOUT squid code for tunnel timeouts.

Plugins

New plugins:

• connection_exempt_list - manage the per-client connection limit exempt list

• filter_body - filter request and response body content

• jax_fingerprint - consolidated JA3/JA4 fingerprinting

• realip - set the verified client address from a trusted source

redo_cache_lookup has been moved out of the experimental plugins and into the examples.

header_rewrite and hrw4u:

• hrw4u is a new DSL and compiler for header_rewrite configurations, with a companion u4wrh tool that converts existing header_rewrite configuration back into the DSL. See HRW4U DSL.

• header_rewrite can invoke the hrw4u compiler directly at config load.

• Added elif support in if/elif/else chains, nested if, SETS with partial string matching, session-scope state variables, SERVER-HEADER and SERVER-URL, indexed query parameters, set-effective-address, set-cc-alg, and POST_REMAP_HOOK support.

• Per-remap MaxMind geo database handles are supported.

• Bad run-plugin directives are now rejected at config load rather than at runtime.

Other plugin changes:

• compress: Zstandard support, content-type parameter handling, and an option to skip compressing partial objects.

• stats_over_http: a Prometheus v2 output format that groups samples by metric family and derives labels for methods, directions, status codes, cache results, time buckets and cache volumes; plus HINT and TYPE annotations.

• xdebug: a probe-full-json feature that emits the full probe output as JSON, including the encoded origin body.

• escalate: added the x-escalate-redirect header and --escalate-non-get-methods.

• esi: added --allowed-response-codes.

• maxmind_acl: added a bypass header configuration option.

• slice: prefetch deduplication and a freelist, and purge now covers every block of an object rather than stopping at the first gap.

• lua: support for Unix domain socket inbound connections, the verified address API, PROXY protocol info, certificate introspection, the connection exempt list, and a shutdown hook.

• Cripts: cache group concepts, geo APIs on cripts::IP, a refactored cache key / URL API, and a substantially smaller per-transaction Context.

TS API

• TSVConnClientHelloGet and TSClientHelloExtensionGet provide access to the TLS ClientHello and its extensions.

• TSHttpTxnVerifiedAddrSet / TSHttpTxnVerifiedAddrGet set and read a verified client address.

• TSHttpTxnCacheKeyDigestGet returns the cache key hash.

• TSLogFieldRegister, TSLogIntMarshal, TSLogStringMarshal and TSLogAddrMarshal allow plugins to define custom log fields.

• TSConnectionLimitExemptListAdd, TSConnectionLimitExemptListRemove and TSConnectionLimitExemptListClear manage the per-client connection limit exempt list.

• TSHttpTxnNextHopStrategySet, TSHttpTxnNextHopStrategyGet and TSHttpTxnParentStrategyGet expose next hop strategy selection.

• TSMutexLockGuard is an RAII guard for TSMutex.

What’s New in ATS v10.1

Metrics

• Added proxy.process.http.total_parent_marked_down_timeout

• Added proxy.process.http.total_client_connections_uds

• Added proxy.process.ssl.group.user_agent.P-256

• Added proxy.process.ssl.group.user_agent.P-384

• Added proxy.process.ssl.group.user_agent.P-521

• Added proxy.process.ssl.group.user_agent.X25519

• Added proxy.process.ssl.group.user_agent.P-224

• Added proxy.process.ssl.group.user_agent.X448

• Added proxy.process.ssl.group.user_agent.X25519MLKEM768

Plugins

• stats_over_http: Add prometheus metrics format option

• header_rewrite: Add set-plugin-cntl operator

• header_rewrite: Add LAST-CAPTURE condition to access the last capture group of a regex

• header_rewrite: Add support for state variables that can be used in conditions and operators.

• header_rewrite: Add support for an else clause in conditions

• header_rewrite: Add a GROUP condition

• header_rewrite: Add a HTTP-CNTL condition to control if expensive rules are run.

• header_rewrite: Add the set-body-from operator to set the response body from a URL

• header_rewrite: The set-body-from operator now defers renabling the transaction until after the fetch of the URL providing the response body

• slice: Support unix domain socket paths

• slice: Add configuration to limit slicing of some objects.

• access_control: Generate a session cookie when exp=0 appears in a TokenRespHdr origin response header.

• compress: Add range request control options to adjust behavior based on the Accept-Encoding or Range headers

• lua: Add support for millisecond sleep

• escalate: Now handles dispatching to the failover server if the original server is down

• ja3_fingerprint: Add the --preserve option to avoid modifing some existing ja* fields.

• ja4_fingerprint: Added this new plugin

• rate_limit: Add a --rate option to limit by RPS

TS API

• Add TSVConnPPInfoGet to get Proxy Protocol information.

• Add TSContScheduleOnEntirePool and TSContScheduleEveryOnEntirePool to schedule continuations on every thread in a pool.

Features

• Add the cqssg log field for TLS group name logging

• traffic_ctl: Add a new server command to show some basic internal information

• traffic_ctl: Now displays YAML format output when the --records option is set.

• traffic_ctl: Added the server debug command to enable/disable diagnostics and debug tags at runtime with a single command.

• cripts: Add some new high level convenience APIs

• cripts: Add optional reason parameter to Error::Status

• sni.yaml: Add server_cipher_suite and server_TLSv1_3_cipher_suites to allow overriding the setting from records.yaml

• Add support for getting authority information from Proxy Protocol V2. with new ppa log formatter.

• Add support for getting UDP address info from Proxy Protocol.

• Added support for listening on a Unix Domain Socket. See proxy.config.http.server_ports

• Added option for proxy.config.http.auth_server_session_private to only mark the connection private if Proxy-Authorization or Www-Authenticate headers are present

• It is now an ERROR if a remap ACL has more than one @action parameter. This was an error in ATS 10.0.x

• Add a fragment-size option in volume.config to control the fragment size of the volume.

• Add an optional avg_obj_size to volume.config to control the directory entry sizing.

• The proxy.config.http.cache.post_method is now an overridable config.

• Defer deleting the copied plugin shared object file to startup to make it easier to debug crashes in plugins.

Configuration

• Added proxy.config.http.negative_revalidating_list to configure the list of status codes that apply to the negative revalidating feature

• Added proxy.config.ssl.session_cache.mode to control TLS session caching. This is intended to replace the legacy proxy.config.ssl.session_cache.enabled and proxy.config.ssl.session_cache.value configurations. The proxy.config.ssl.session_cache.enabled setting was documented but never implemented, while proxy.config.ssl.session_cache.value was implemented but not documented. The new proxy.config.ssl.session_cache.mode functions just like the legacy proxy.config.ssl.session_cache.value did in the ealier 10.0 release. The proxy.config.ssl.session_cache.mode setting provides a clear and consistent interface going forward. For backward compatibility, .enabled is now implemented, but both .enabled and .value will be removed in ATS 11.x.

What’s New in ATS v10.0

This version of Apache Traffic Server™ includes over <x> commits, from <y> pull requests. A total of <z> contributors have participated in this development cycle.

New Features

• JSON-RPC based interface for administrative API

  Traffic Server now exposes a JSON-RPC node to interact with external tools. Check JSONRPC for more details.

• traffic_ctl has a new command monitor to show a continuously updating list of metrics

• ip_allow.yaml and remap.config now support named IP ranges via IP Categories. See the ip_categories key definition in ip_allow.yaml for information about their use and definitions.

• sni.yaml fqdn:tunnel_route, beside the already supported match group number, configuration now also supports the destination port using a variable specification either for the incoming connection port or the port that was specified by the incoming Proxy Protocol payload. Check sni.yaml for more information.

• The records.yaml entry proxy.config.system_clock was added to control the underlying system clock that ATS uses for internal timing

• OCSP requests is now be able to use GET method. See proxy.config.ssl.ocsp.request_mode for more information.

• TSHttpSsnInfoIntGet has been added.

New or modified Configurations

ip_allow.yaml and remap.config ACL actions

There are two new sets of actions for HTTP request method filtering introduced in Traffic Server 10.x:

• Both ip_allow.yaml and remap.config now support the set_allow and set_deny actions. These actions both behave like allow and deny did for ip_allow.yaml pre Traffic Server 10.x.

• In addition, remap.config now supports add_allow and add_deny actions. These behave like allow and deny actions did for remap.config ACLs pre Traffic Server 10.x.

The details about the motivation and behavior of these actions are documented in ACL Filters.

Logging and Metrics

The numbers of HTTP/2 frames received have been added as metrics.

Plugins

• authproxy - --forward-header-prefix parameter has been added

• prefetch - Cmcd-Request header support has been added

• xdebug - --enable option to selectively enable features has been added

• system_stats - Stats about memory have been added

• slice plugin - This plugin was promoted to stable.

• compress plugin - Added support for Zstandard (zstd) compression algorithm.

JSON-RPC

Remote clients, like traffic_ctl have now bi-directional access to the plugin space. For more details check Handler implementation.

Replaced autotools build system with cmake

See Installing Traffic Server for more information

Switch to C++20

Plugins are now required to be compiled as C++ code, rather than straight C. The API is tested with C++20, so code compatible with this version is preferred. TSDebug and related functions are removed. Debug tracing should now be done using cpp:func:Dbg and related functions, as in Traffic Server core code.

C++ Plugin API Deprecated

It is deprecated in this release. It will be deleted in ATS 11.

Symbols With INKUDP Prefix

In the plugin API, all types and functions starting with the prefix INKUDP are removed.

New plugin hook for request sink transformation

A new hook, TS_HTTP_REQUEST_CLIENT_HOOK, has been added. This provides the analoguas functionality of TS_HTTP_RESPONSE_CLIENT_HOOK, for request bodies.

HTTP/2

• Support for HTTP/2 on origin server connections has been added. This is disabled by default. For more details check proxy.config.ssl.client.alpn_protocols

• Support for CONNECT method has been added.

• Window size control has been improved. For more details check proxy.config.http2.flow_control.policy_in

HTTP UI Removed

The stats and cache inspector pages were unmaintained and removed in this release.