Upgrading to ATS v10.2

This section covers changes when upgrading from Traffic Server v10.1 to v10.2. If you are upgrading from v9.x, read Upgrading to ATS v10.x below as well, since all of those changes apply too.

Incompatible Changes

The following change alters existing behavior. It is included deliberately, as a bug fix: the previous behavior did not match the documented intent of the settings involved.

• Origin connect retries now honor HostDB state

  Traffic Server has three settings that bound how many times a failed origin connection is retried. Prior to this release none of them were applied according to the actual state of the origin, so the configured limits did not take effect as documented. The retry limit is now selected by the HostDBInfo state of the server being contacted:

  • UP uses proxy.config.http.connect_attempts_max_retries

  • SUSPECT uses proxy.config.http.connect_attempts_max_retries_suspect_server

  • DOWN gets no retries

  This is an intentional incompatibility. Deployments that relied on the previous behavior will see a different number of origin connect attempts after upgrading, most visibly toward origins HostDB considers DOWN, which are no longer retried at all. Review these three settings before upgrading.

Changes to Features

• proxy.config.http.cache.ignore_accept_encoding_mismatch now honors Vary: Accept-Encoding at its documented default of 2. Previously any non-zero value was treated as “ignore the mismatch”, so the default did not behave as documented. Deployments that depended on the old behavior should set the value to 1 explicitly.

• Replaced configurations are now destroyed on an ET_TASK thread instead of a network thread. This is transparent, but it moves config teardown work off the event loop.

Removed Features

• The -k / --clear_hostdb command line flag and the PROXY_CLEAR_HOSTDB environment variable have been removed from traffic_server. The clear_hostdb command is still available via traffic_server -C clear_hostdb.

• OpenSSL ENGINE support has been removed. It was unintentionally disabled in v10.0 and the API is gone in recent OpenSSL releases. The proxy.config.ssl.engine.conf_file record still exists but has no effect.

Configuration Changes

The following records.yaml changes have been made in v10.2:

• proxy.config.http.connect_attempts_max_retries_down_server is deprecated in favor of proxy.config.http.connect_attempts_max_retries_suspect_server. When only the deprecated record is set its value is mirrored forward and a warning is logged; when both are set, the new record wins.

• proxy.config.http.connect.down.policy accepts a new value 3, which counts inactive connections as failures.

• proxy.config.ssl.max_record_size now accepts the documented value -1 to enable dynamic TLS record sizing. This was previously rejected by records validation.

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

• negative_caching_list and negative_revalidating_list are now overridable.

• proxy.config.http.cache.targeted_cache_control_headers has been added to support RFC 9213 targeted cache control. It defaults to an empty string, so the feature is off unless configured.

See What’s New in ATS v10.2 for the full list of settings added in this release.

JSONRPC now refuses writes to records marked RECA_READ_ONLY or RECA_NO_ACCESS. Tooling that previously attempted such writes will now receive an error rather than silently having no effect.

Plugins

• redo_cache_lookup has been moved out of the experimental plugins and into the examples. It is no longer built or installed.

• header_rewrite now rejects an invalid run-plugin directive at configuration load time rather than at runtime. A configuration that was previously accepted and failed later will now fail to load.

Build

The Python tooling used by the test suite has migrated from Pipenv to uv. Developers running autests will need uv available; this does not affect runtime deployments.

Upgrading to ATS v10.x

Feature Changes

Removed and Deprecated Features

The following features, configurations and plugins are either removed or deprecated in this version of ATS. Deprecated features should be avoided, with the expectation that they will be removed in the next major release of ATS.

• Removed Features * HostDB no longer supports persistent storage for DNS resolution * Removed support for the MMH crypto hash function * Removed the built-in stats and cache inspector pages that were previously accessible via the Traffic Server HTTP interface

  • Traffic Manager is no longer part of Traffic Server. Administrative tools now interact with Traffic Server directly by using the JSONRPC Endpoint.

    • traffic_ctl server

      As a part of the above feature removal the backtrace, restart, start, status options are no longer available in this Traffic Server version.

• Deprecated Features

  • Next Protocol Negotiation (NPN) support has been deprecated from ATS and will be removed in the next major release.

• Removed Libraries

  • mgmt_c - Client library for traffic_manager

Changes to Features

The following features have been changed in this version of ATS.

• Remap ACLs

  Changed in-line ACLs to match before activated ACL rules. For details refer to: https://github.com/apache/trafficserver/pull/11033 and ACL Filters.

• Administrative API (RPC)

  Moved away from the binary serialization mechanism used to comunicate between Traffic Server and the tools to a JSON-RPC text based protocol. Underlying Unix Domain Socket protocol remains the same. Check JSONRPC 2.0 Protocol for more details.

• Other changes

  • It is now a fatal error when ATS cannot bind or listen to a configured port

  • Propagate socket options specified in proxy.config.net.sock_option_flag_in to newly accepted connections

  • HostDB internals were restructured, this should (externally) be backwards compatible. In any case you can check HostDB for more details.

API Changes

The following APIs have changed, either in semantics, interfaces, or both.

• Changed TS API

  • TSHttpTxnAborted

  • TSMimeHdrPrint

  • Enum values for hooks and events have been changed (ABI incompatible change)

  • TSSslSecretGet

• New TS API

  • TSContScheduleOnEntirePool

  • TSContScheduleEveryOnEntirePool

• Removed TS API

  • TSContSchedule

  • TSHttpSsnArgSet

  • TSHttpSsnArgGet

  • TSHttpSsnArgIndexReserve

  • TSHttpSsnArgIndexNameLookup

  • TSHttpSsnArgIndexLookup

  • TSHttpTxnArgSet

  • TSHttpTxnArgGet

  • TSHttpTxnArgIndexReserve

  • TSHttpTxnArgIndexNameLookup

  • TSHttpTxnArgIndexLookup

  • TSHttpTxnClientPacketTosSet

  • TSHttpTxnServerPacketTosSet

  • TSMgmtConfigIntSet

  • TSUrlHttpParamsGet

  • TSUrlHttpParamsSet

  • TSVConnArgSet

  • TSVConnArgGet

  • TSVConnArgIndexReserve

  • TSVConnArgIndexNameLookup

  • TSVConnArgIndexLookup

  • TSRecordType::TS_RECORDTYPE_CLUSTER

  • TSRecordType::TS_RECORDTYPE_LOCAL

• Removed INK UDP API

  • INKUDPBind

  • INKUDPSendTo

  • INKUDPRecvFrom

  • INKUDPConnFdGet

  • INKUDPPacketCreate

  • INKUDPPacketBufferBlockGet

  • INKUDPPacketFromAddressGet

  • INKUDPPacketFromPortGet

  • INKUDPPacketConnGet

  • INKUDPPacketDestroy

  • INKUDPPacketGet

Cache

The cache in this releases of ATS is compatible with previous versions of ATS. You would not expect to lose your cache, or have to reinitialize the cache when upgrading.

Configuration Changes

The following incompatible changes to the configurations have been made in this version of ATS.

The records.config file has been renamed to records.yaml and now it is structured in YAML format. Check Converting records.config to records.yaml and records.yaml for more details.

The following records.yaml changes have been made:

• The records.yaml entry proxy.config.http.down_server.abort_threshold has been removed.

• The records.yaml entry proxy.config.http.connect_attempts_max_retries_dead_server has been renamed to proxy.config.http.connect_attempts_max_retries_down_server.

• The records.yaml entry proxy.config.http.connect_attempts_max_retries_down_server is now deprecated in favor of proxy.config.http.connect_attempts_max_retries_suspect_server. The new name aligns with the HostDBInfo::State::SUSPECT state it actually applies to (a recovering origin allowed a limited probe budget after proxy.config.http.down_server.cache_time elapses). When only the deprecated record is set, its value is mirrored forward to the new record and a warning is logged. When both are set, the new record wins.

• The entry proxy.config.http.connect.dead.policy has been renamed to proxy.config.http.connect.down.policy.

• The records.yaml entry proxy.config.http.parent_proxy.connect_attempts_timeout and proxy.config.http.post_connect_attempts_timeout have been removed. Instead use proxy.config.http.connect_attempts_timeout to control all connection to origin timeouts.

• The per server origin connection feature had a few configurations that were not used removed. proxy.config.http.per_server.connection.queue_size and proxy.config.http.per_server.connection.queue_delay have been removed.

• The default value for records.yaml entry proxy.config.ssl.client.verify.server.policy has been changed from PERMISSIVE to STRICT.

• All proxy.config.ssl.TLSv* and proxy.config.ssl.client.TLSv* have been deprecated. Use proxy.config.ssl.server.version.min/max and proxy.config.ssl.client.version.min/max instead.

• The records.yaml entry proxy.config.http.keepalive_internal_vc has been removed. This entry was previously undocumented.

• The default values for proxy.config.http.request_header_max_size, proxy.config.http.response_header_max_size, and proxy.config.http.header_field_max_size have been changed to 32KB.

• The records.yaml entry proxy.config.http.server_ports now also accepts the allow-plain option

• The records.yaml entry proxy.config.http.cache.max_open_write_retry_timeout has been added to specify a timeout for starting a write to cache

• The records.yaml entry proxy.config.net.per_client.max_connections_in has been added to limit the number of connections from a client IP. This works the same as proxy.config.http.per_server.connection.max

• The records.yaml entry proxy.config.http.no_dns_just_forward_to_parent is not overridable

• The records.yaml entry proxy.config.output.logfile has been renamed to proxy.config.output.logfile.name.

• The records.yaml entry proxy.config.exec_thread.autoconfig has been renamed to proxy.config.exec_thread.autoconfig.enabled.

• The records.yaml entry proxy.config.tunnel.prewarm has been renamed to proxy.config.tunnel.prewarm.enabled.

• The records.yaml entry proxy.config.ssl.origin_session_cache has been renamed to proxy.config.ssl.origin_session_cache.enabled.

• The records.yaml entry proxy.config.ssl.session_cache has been renamed to proxy.config.ssl.session_cache.mode.

• The records.yaml entry proxy.config.ssl.TLSv1_3 has been renamed to proxy.config.ssl.TLSv1_3.enabled.

• The records.yaml entry proxy.config.ssl.client.TLSv1_3 has been renamed to proxy.config.ssl.client.TLSv1_3.enabled.

• The records.yaml entry proxy.config.allocator.iobuf_chunk_sizes has been added to enable more control of iobuffer allocation.

• The records.yaml entry proxy.config.allocator.hugepages will enable allocating iobuffers and cache volumes from hugepages if configured in the system.

• The records.yaml entry proxy.config.plugin.compiler_path has been added to specify an optional compiler tool path for compiling plugins.

The following changes have been made to the sni.yaml file:

• disable_h2 has been removed. Use http2 with off instead.

• The ip_allow key can now take a reference to a file containing the ip allow rules

• valid_tls_versions_in has been deprecated. Use valid_tls_version_min_in and valid_tls_version_max_in instead.

• Simplify wildcard support and matching order of the fqdn field

  • Allow single left-most *

  • Do NOT support regex

  • Allow $1 (capturing) support in the tunnel_route field

  • Matching depends on the order of entries (like remap.config)

Plugins

Deprecated Plugins

The following plugins have been deprecated.

• healthchecks - please use the statichit plugin instead

• icap

Removed Plugins

The following plugins have been removed from the ATS source code in this version of ATS:

• mysql_remap - Dynamic remapping of URLs using data from a MySQL database.

• acme

• cache_key_genid

• fast_cgi

Changes to Features

The following plugins have been changed in this version of ATS.

• regex_remap - matrix-parameters parameter has been removed. The string that follows a semicolon is now included in path.

• header_rewrite - MATRIX part specifier has been removed. The string that follows a semicolon is now included in PATH part.

• maxmind_acl - The regex part in its configuration takes the entire URL of a request, not just the path.

• rate_limit - Few changes were made on this plugin:

  • A YAML based configuration, reloadable even as global plugin.

  • SNI aliases

  • The IP reputation objects are now shareable for many SNIs.

  for more details, please check Rate Limit Plugin.

Lua Plugin

• The following Http config constants have been renamed:

TS_LUA_CONFIG_HTTP_CONNECT_ATTEMPTS_MAX_RETRIES_DEAD_SERVER has been renamed to TS_LUA_CONFIG_HTTP_CONNECT_ATTEMPTS_MAX_RETRIES_DOWN_SERVER.

TS_LUA_CONFIG_HTTP_CONNECT_DEAD_POLICY has been renamed to TS_LUA_CONFIG_HTTP_CONNECT_DOWN_POLICY.

• The following functions have been removed:

  • ts.http.client_packet_tos_set

  • ts.http.server_packet_tos_set

  • ts.client_request.get_uri_params

  • ts.client_request.set_uri_params

  • ts.server_request.get_uri_params

  • ts.server_request.set_uri_params

Metrics

• The HTTP connection metric proxy.process.http.dead_server.no_requests has been renamed to proxy.process.http.down_server.no_requests.

• The network metric proxy.process.net.calls_to_readfromnet_afterpoll has been removed

• The network metric proxy.process.net.calls_to_writetonet_afterpoll has been removed

• New cache metrics proxy.process.cache.stripes and proxy.process.cache.volume_X.stripes that counts cache stripes

• All metric names that ended in _stat have had that suffix dropped and no longer end with _stat

• The metric proxy.node.cache.contents.num_doc was removed

• The metric proxy.node.config.reconfigure_required was renamed to proxy.process.proxy.reconfigure_required

• The metric proxy.node.config.reconfigure_time was renamed to proxy.process.proxy.reconfigure_time

• The metric proxy.node.config.restart_required.proxy was renamed to proxy.process.proxy.restart_required

• The metric proxy.node.restarts.proxy.cache_ready_time was renamed to proxy.process.proxy.cache_ready_time

• The metric proxy.node.restarts.proxy.stop_time was renamed to proxy.process.proxy.start_time

• The following traffic_manager metrics have been removed: - proxy.node.hostname_FQ - proxy.node.hostname - proxy.node.proxy_running - proxy.node.restarts.proxy.restart_count - proxy.node.restarts.proxy.start_time - proxy.node.http.parent_proxy_total_response_bytes

Logging

The cqtx log field has been removed, but can be replaced by cqhm pqu cqpv.

The cqhv log field has been removed.

The cpu, cquc, cqup, and cqus log fields have new names, pqu, pquc, pqup, and pqus. The old names have been deprecated.

The chi log field now represents the IP address of the previous hop if Proxy Protocol is used.