Remap Purge Plugin

This remap plugin allows the administrator to easily setup remotely controlled PURGE for the content of an entire remap rule. The actual purging is instant, and has no cost on the ATS server side. The plugin makes it easy to accomplish this, since it’s a simple REST API to trigger the PURGE event.

Purpose

Oftentimes, it’s important, or even mission critical, to be able to purge a large portion of an Apache Traffic Server. For example, imagine that you’ve pushed a new version of the site’s HTML files, and you know it’s going to be hours, or even days, before the content expires in the cache.

Using this plugin, you can now easily set the Cache-Control very long, yet expire a large portion of the cache instantly. This is building upon the proxy.config.http.cache.generation configuration. What the plugin does is to provide a REST API that makes it easy to manage this generation ID for one or many ATS servers.

Installation

This plugin is still experimental, but is included with Traffic Server when you build with the experimental plugins enabled via configure.

Configuration

This plugin only functions as a remap plugin, and is therefore configured in remap.config. Be aware that the PURGE requests are typically restricted to localhost, but see ip_allow.yaml and remap.config how to configure these access controls.

If PURGE does not work for your setup, you can enable a relaxed configuration which allows GET requests to also perform the purge. This is not a recommended configuration, since there are likely no ACLs for this now, only the secret protects the content from being maliciously purged.

Plugin Options

There are three configuration options for this plugin:

--secret      The secret the client sends to authorize the purge
--header      The header the client sends the secret in (optional)
--state-file  Name of the state file where we store the GenID
--allow-get   This also allows a simple GET to perform the purge

Examples

map https://www.example.com http://origin.example.com

@plugin=purge_remap.so @pparam=–state-file=example

@pparam=–header=ATS-Purger @pparam=–secret=8BFE-656DC3564C05

This setups the server to PURGE using a special header for authentication:

curl -X PURGE -H "ATS-Purger: 8BFE-656DC3564C05" https://www.example.com

The passing of the secret as a header is option, if not specified, the last component of the path is used instead. Example:

map https://www.example.com/docs http://docs.example.com \
   @plugin=purge_remap.so @pparam=--state-file=example_docs \
                          @pparam=--secret=8BFE-656DC3564C05

This can now be purged with an even simpler request, but be aware that the secret is now likely stored in access logs as well:

curl -X PURGE https://www.example.com/docs/8BFE-656DC3564C05