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