Upgrading to ATS v9.x

Remapping

One of the biggest changes in ATS v9.0.0 is that URL rewrites, as specified in a remap.config rule, now always happens before all plugins are executed. This can have significant impact on behavior, since plugins might now see a different URL than they did in prior versions. In particular, plugins modifying the cache key could have serious problems (see the section below for details).

YAML

We are moving configurations over to YAML, and thus far, the following configurations are now fully migrated over to YAML:

In addition, a new file for TLS handshake negotiation configuration is added:

  • sni.yaml (this was for a while named ssl_server_name.yaml in Github)

Configuration Settings: records.config

These are the changes that are most likely to cause problems during an upgrade. Take special care making sure you have updated your configurations accordingly.

Connection Management

The old settings for origin connection management included the following settings:

  • proxy.config.http.origin_max_connections

  • proxy.config.http.origin_max_connections_queue

  • proxy.config.http.origin_min_keep_alive_connections

These are all gone, and replaced with the following set of configurations:

Renamed records.config Settings

Removed records.config Settings

The following settings are simply gone, and have no purpose:

  • proxy.config.config_dir (see PROXY_CONFIG_CONFIG_DIR environment variable)

  • proxy.config.cache.storage_filename (see next section as well)

  • proxy.config.http.server_tcp_init_cwnd (see Solaris section below)

  • proxy.config.http.parent_proxy_routing_enable (implicit by use of parent.config)

All the Vary related configuration overrides were eliminated, prefer to set this via the origin server, or modify the Vary header on server responses instead.

  • proxy.config.http.cache.vary_default_text

  • proxy.config.http.cache.vary_default_images

  • proxy.config.http.cache.vary_default_other

SSLv3 support has been removed

  • proxy.config.ssl.client.SSLv3

The option to disable the caching of an empty response (zero length body response) has been removed. Zero length body responses are no longer a special case and are handled the same as a response with a non-zero length body.

  • proxy.config.http.cache.allow_empty_doc

  • proxy.config.ssl.client.verify.server was deprecated for ATS 8.x and has been removed. Use

proxy.config.ssl.client.verify.server.properties instead.

Deprecated records.config Settings

The following configurations still exist, and functions, but are considered deprecated and will be removed in a future release. We strongly encourage you to avoid using any of these:

Settings With New Defaults

The following settings have changed from being on by default, to being off:

The default cipher list has changed: * proxy.config.ssl.server.cipher_suite

the ratio is now worker thread 1 to 1 processing thread on the CPU or CPUs.

Settings with new behavior

retried for each new request. Before ATS tried 1 time more than this setting making it impossible to set the retry value to 0.

Metrics

Renamed or Modified Metrics

proxy.process.http2.current_client_sessions is renamed to be proxy.process.http2.current_client_connections

proxy.process.http.current_client_transactions used to record both the number current of HTTP/1.1 and HTTP/2 requests. Now it only records the number current of HTTP/1.1 client requests. Please use proxy.process.http2.current_client_streams to get the number of current HTTP/2 client requests.

Removed Metrics

The following metrics have been removed.

  • proxy.process.ssl.ssl_error_want_read

  • proxy.process.ssl.ssl_error_want_write

  • proxy.process.ssl.ssl_error_want_x509_lookup

  • proxy.process.ssl.ssl_error_zero_return

Command Line Options

The following command line options were either renamed or removed.

  • –with-max-api-stats was replace with –maxRecords to specify the total number of metric instead of just the total API metrics

to use when running ATS. * –read_core was removed and gdb should be used instead.

Deprecated or Removed 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 the log collation feature along with its configuration settings (proxy.local.log.collation*).

Rollback Configuration

The rollback configuration code was removed in for ATS v9.0.0. This featured copied the configuration files to have version numbers if the end user wanted to rollback to a previous version of the configuration.

records.config.shadow and records.config.snap support has also been removed in order to clean up and simply loading of configuration files.

API Changes

Our APIs are guaranteed to be compatible within major versions, but we do make changes for each new major release.

Removed APIs

  • TSHttpTxnRedirectRequest()

Renamed or Modified APIs

  • TSVConnSSLConnectionGet() is renamed to be TSVConnSslConnectionGet()

  • TSHttpTxnServerPush() now returns a TSReturnCode

  • TSContSchedule() and TSContScheduleAPI() by default will run on the same thread from which they are called.

  • TSFetchUrl() and TSFetchCreate() now return a TSFetchSM

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.

However, due to changes in how remap plugins are processed, your cache key might change. In versions to v9.0.0, the first plugin in a remap rule would get the pristine URL, and subsequent plugins would get the remapped URL. As of v9.0.0, all plugins now receive the remapped URL. If you are using a plugin that modifies the cache key, e.g. Cache Key and Parent Selection URL Manipulation Plugin, if it was evaluated first in a remap rule, the behavior (input) changes, and therefore, cache keys can change!

Caches created with ATS v2.x are incompatible and can’t be loading into ATS v9.0.0 or later. We feel that this is an unlikely scenario, but if you do run into this, clearing the cache is required.

Plugins

Promoted Plugins

The following plugins have been promoted from experimental to stable plugins: * cache_range_requests * certifier * multiplexer * prefetch * remap_purge

Removed Plugins

The following plugins have been removed because they are no longer used or maintained: * balancer * buffer_uplaod * header_normalize * hipes * memcached_remap * stale_while_revalidate * mysql_remap

The following plugins have changes that might require you to change configurations.

Header Rewrite

  • The %{PATH} directive is now removed, and instead you want to use %{CLIENT-URL:PATH}. This was done to unify the behavior of these operators, rather than having this one-off directive.

  • header-rewrite-expansion was removed and replaced with header-rewrite-concatenations

Cache Key

  • –ua-blacklist was renamed to –ua-blocklist and –ua-whitelist was renamed to –ua-allowlist

Logging

  • cqhv has been deprecated and cqpv should be used instead.

Library Dependencies and Builds

  • TCL is no longer required to build ATS.

  • The minium OpenSSL version to build ATS is now 1.0.2.

  • To build the documentation we now require Sphinx 2.0.1

  • CentOS 6 support has been removed.

  • Ubuntu 14.04 support has been removed.

Platform Specific

Solaris is no longer a supported platform, but the code is still there. However, it’s unlikely to work, and unless someone takes on ownership of this Platform, it will be removed from the source in ATS v10.0.0. For more details, see issue #5553. With Solaris no longer supported, we also eliminated proxy.config.http.server_tcp_init_cwnd, which has no purpose on all other platforms.