Cache Storage¶

The Traffic Server cache consists of a high-speed object database called the object store that indexes cache objects according to URLs and their associated headers.

The Traffic Server Cache¶

The Traffic Server cache consists of a high-speed object database called the object store. The object store indexes cache objects according to URLs and associated headers. This enables Traffic Server to store, retrieve, and serve not only web pages, but also parts of web pages - which provides optimum bandwidth savings. Using sophisticated object management, the object store can cache alternate versions of the same object (versions may differ because of dissimilar language or encoding types). It can also efficiently store very small and very large documents, thereby minimizing wasted space. When the cache is full, Traffic Server removes stale data to ensure the most requested objects are kept readily available and fresh.

Traffic Server is designed to tolerate total disk failures on any of the cache disks. If the disk fails completely, then Traffic Server marks the entire disk as corrupt and continues using the remaining disks. An alarm is then created to indicate which disk failed. If all of the cache disks fail, then Traffic Server goes into proxy-only mode.

You can perform the following cache configuration tasks:

Change the total amount of disk space allocated to the cache; refer to Changing Cache Capacity.
Partition the cache by reserving cache disk space for specific protocols and origin servers/domains; refer to Partitioning the Cache.
Delete all data in the cache; refer to Clearing the Cache.
Override cache directives for a requested domain name, regex on a url, hostname or ip, with extra filters for time, port, method of the request, and more. ATS can be configured to never cache, always cache, ignore no-cache directives, etc. These are configured in cache.config.

The RAM Cache¶

Traffic Server maintains a small RAM cache of extremely popular objects. This RAM cache serves the most popular objects as quickly as possible and reduces load on disks, especially during temporary traffic peaks. You can configure the RAM cache size to suit your needs, as described in Changing the Size of the RAM Cache below.

The RAM cache supports two cache eviction algorithms, a regular LRU (Least Recently Used) and the more advanced CLFUS (Clocked Least Frequently Used by Size; which balances recentness, frequency, and size to maximize hit rate, similar to a most frequently used algorithm). The default is to use LRU, and this is controlled via proxy.config.cache.ram_cache.algorithm.

Both the LRU and CLFUS RAM caches support a configuration to increase scan resistance. In a typical LRU, if you request all possible objects in sequence, you will effectively churn the cache on every request. The option proxy.config.cache.ram_cache.use_seen_filter can be set to add some resistance against this problem.

In addition, CLFUS also supports compressing in the RAM cache itself. This can be useful for content which is not compressed by itself (e.g. images). This should not be confused with Content-Encoding: gzip, this feature is only present to save space internally in the RAM cache itself. As such, it is completely transparent to the User-Agent. The RAM cache compression is enabled with the option proxy.config.cache.ram_cache.compress.

Possible values are:

Value	Meaning
0	No compression (default)
1	fastlz compression
2	libz compression
3	liblzma compression

Changing the Size of the RAM Cache¶

Traffic Server provides a dedicated RAM cache for fast retrieval of popular small objects. The default RAM cache size is automatically calculated based on the number and size of the cache partitions you have configured. If you’ve partitioned your cache according to protocol and/or hosts, then the size of the RAM cache for each partition is proportional to the size of that partition.

You can increase the RAM cache size for better cache hit performance. However, if you increase the size of the RAM cache and observe a decrease in performance (such as increased latencies), then it’s possible that the operating system requires more memory for network resources. In such instances, you should return the RAM cache size to its previous value.

To change the RAM cache size:

Stop Traffic Server.
Set the variable proxy.config.cache.ram_cache.size to specify the size of the RAM cache. The default value of -1 means that the RAM cache is automatically sized at approximately 1MB per gigabyte of disk.
Restart Traffic Server. If you increase the RAM cache to a size of 1GB or more, then restart with the trafficserver command (refer to Start Traffic Server).

Changing Cache Capacity¶

You can increase or reduce the total amount of disk space allocated to the cache without clearing the content. To check the size of the cache (in bytes), enter the command traffic_ctl metric get proxy.process.cache.bytes_total.

Increasing Cache Capacity¶

To increase the total amount of disk space allocated to the cache on existing disks, or to add new disks to a Traffic Server node:

Stop Traffic Server.
Add hardware, if necessary.
Edit storage.config to increase the amount of disk space allocated to the cache on existing disks or describe the new hardware you are adding.
Restart Traffic Server.

Reducing Cache Capacity¶

To reduce the total amount of disk space allocated to the cache on an existing disk, or to remove disks from a Traffic Server node:

Stop Traffic Server.
Remove hardware, if necessary.
Edit storage.config to reduce the amount of disk space allocated to the cache on existing disks or delete the reference to the hardware you’re removing.
Restart Traffic Server.

Important

In storage.config, a formatted or raw disk must be at least 128 MB.

Partitioning the Cache¶

You can manage your cache space more efficiently and restrict disk usage by creating cache volumes with different sizes for specific protocols. You can further configure these volumes to store data from specific origin servers and/or domains.

Creating Cache Partitions for Specific Protocols¶

You can create separate volumes for your cache that vary in size to store content according to protocol. This ensures that a certain amount of disk space is always available for a particular protocol. Traffic Server currently supports only the http partition type.

To partition the cache according to protocol:

Enter a line in volume.config for each volume you want to create.

volume=1 scheme=http size=50%
volume=2 scheme=http size=50%

Restart Traffic Server.

Important

Volume definitions must be the same across all nodes in a cluster.

Making Changes to Partition Sizes and Protocols¶

After you’ve configured your cache volumes based on protocol, you can make changes to the configuration at any time. Before making changes, note the following:

You must stop Traffic Server before you change the cache volume size and protocol assignment.
When you increase the size of a volume, the contents of the volume are not deleted. However, when you reduce the size of a volume, the contents of the volume are deleted.
When you change the volume number, the volume is deleted and then recreated, even if the size and protocol type remain the same.
When you add new disks to your Traffic Server node, volume sizes specified in percentages will increase proportionately.
Substantial changes to volume sizes can result in disk fragmentation, which affects performance and cache hit rate. You should clear the cache before making many changes to cache volume sizes (refer to Clearing the Cache).

Partitioning the Cache According to Origin Server or Domain¶

After you have partitioned the cache according to size and protocol, you can assign the volumes you created to specific origin servers and/or domains. You can assign a volume to a single origin server or to multiple origin servers. However, if a volume is assigned to multiple origin servers, then there is no guarantee on the space available in the volumes for each origin server. Content is stored in the volumes according to popularity. In addition to assigning volumes to specific origin servers and domains, you must assign a generic volume to store content from all origin servers and domains that are not listed. This generic volume is also used if the partitions for a particular origin server or domain become corrupt. If you do not assign a generic volume, then Traffic Server will run in proxy-only mode.

Note

You do not need to stop Traffic Server before you assign volumes to particular hosts or domains. However, this type of configuration is time-consuming and can cause a spike in memory usage. Therefore, it’s best to configure partition assignment during periods of low traffic.

To partition the cache according to hostname and domain:

Configure the cache volumes according to size and protocol, as described in Creating Cache Partitions for Specific Protocols.
Create a separate volume based on protocol for each host and domain, as well as an additional generic partition to use for content that does not belong to these origin servers or domains. The volumes do not need to be the same size.
Enter a line in the hosting.config file to allocate the volume(s) used for each origin server and/or domain.
Assign a generic volume to use for content that does not belong to any of the origin servers or domains listed in the file. If all volumes for a particular origin server become corrupt, then Traffic Server will also use the generic volume to store content for that origin server as per hosting.config.
Run the command traffic_ctl config reload to apply the configuration changes.

Configuring the Cache Object Size Limit¶

By default, Traffic Server allows objects of any size to be cached. You can change the default behavior and specify a size limit for objects in the cache via the steps below:

Set proxy.config.cache.max_doc_size to specify the maximum size in bytes allowed for objects in the cache. A setting of 0 (zero) will permit cache objects to be unlimited in size.
Run the command traffic_ctl config reload to apply the configuration changes.

Clearing the Cache¶

When you clear the cache, you remove all data from the entire cache - including data in the host database. You should clear the cache before performing certain cache configuration tasks such as partitioning. You cannot clear the cache when Traffic Server is running.

To clear the cache:

Stop Traffic Server (see Stop Traffic Server)
Enter the following command to clear the cache:
```
traffic_server -Cclear
```
The clear command deletes all data in the object store and the host database. Traffic Server does not prompt you to confirm the deletion.
Restart Traffic Server (see Start Traffic Server).

Removing an Object From the Cache¶

Traffic Server accepts the custom HTTP request method PURGE when removing a specific object from cache. If the object is found in the cache and is successfully removed, then Traffic Server responds with a 200 OK HTTP message; otherwise, a 404 File Not Found message is returned.

Note

By default, the PURGE request method is only processed if received on the localhost interface.

In the following example, Traffic Server is running on the domain example.com and you want to remove the image remove_me.jpg from cache. Because by default we do not permit PURGE requests from any other IP, we connect to the daemon via localhost:

$ curl -vX PURGE --resolve example.com:80:127.0.0.1 http://example.com/remove_me.jpg
* About to connect() to example.com port 80 (#0)
* Trying 127.0.0.1... connected
* Connected to example.com (127.0.0.1) port 80 (#0)

> PURGE /remove_me.jpg HTTP/1.1
> User-Agent: curl/7.19.7
> Host: example.com
> Accept: */*
>
< HTTP/1.1 200 Ok
< Date: Thu, 08 Jan 2010 20:32:07 GMT
< Connection: keep-alive

The next time Traffic Server receives a request for the removed object, it will contact the origin server to retrieve a new copy, which will replace the previously cached version in Traffic Server.

This procedure only removes the index to the object from a specific Traffic Server cache. While the object remains on disk, Traffic Server will no longer able to find the object. The next request for that object will result in a fresh copy of the object fetched. Users may still see the old (removed) content if it was cached by intermediary caches or by the end-users’ web browser.

Pushing an Object into the Cache¶

Traffic Server accepts the custom HTTP request method PUSH to put an object into the the cache. If the object is successfully written to the cache, then Traffic Server responds with a 200 OK HTTP message; otherwise a 400 Malformed Pushed Response Header message is returned.

To push an object, first save the object headers and body into a file. For instance:

$ curl -s -i -o /path/to/file "http://example.com/push_me.html"
$ cat /path/to/file
HTTP/1.1 200 OK
Date: Wed, 31 May 2017 16:01:59 GMT
Access-Control-Allow-Origin: *
Cache-Control: max-age=10800, public
Last-Modified: Wed, 31 May 2017 16:01:59 GMT
Content-Type: text/html
Age: 0
Content-Length: 176970

<!DOCTYPE html><html id= ...

Then, to push the object, post the object using the PUSH method:

$ curl -x -s -o /dev/null -X PUSH --data-binary /path/to/file "http://example.com/push_me.html"

Inspecting the Cache¶

Traffic Server provides a Cache Inspector utility that enables you to view, delete, and invalidate URLs in the cache (HTTP only). The Cache Inspector utility is a powerful tool that’s capable of deleting all the objects in your cache. Therefore, make sure that only authorized administrators are allowed to access this utility through proper use of the @src_ip option in remap.config and the instructions detailed in Controlling Access.

Accessing the Cache Inspector Utility¶

To access the Cache Inspector utility:

Set proxy.config.http_ui_enabled to 1.
To access the cache inspector in reverse proxy mode, you must add a remap rule to remap.config to expose the URL. This should be restricted to a limited set of hosts using the @src_ip option. To restrict access to the network 172.28.56.0/24, use
```
map http://yourhost.com/myCI/ http://{cache} @action=allow @src_ip=172.28.56.1-172.28.56.254
```
Reload the Traffic Server configuration by running traffic_ctl config reload.
Open your web browser and go to the the following URL:
```
http://yourhost/myCI/
```
You will now be presented with the Cache Inspector interface.

Using the Cache Inspector Utility¶

The Cache Inspector Utility provides several options that enable you to view and delete the contents of your cache.

Lookup URL: Search for a particular URL in the cache. When Traffic Server finds the URL in the cache, it will display details of the object that corresponds to the URL (e.g. header length and number of alternates). The option to delete the URL from the cache will be presented.
Delete URL: Delete the object from the cache which corresponds to the given URL. Success or failure will be indicated after a delete has been attempted.
Regex Lookup: Search URLs within the cache using one or more regular expressions.
Regex Delete: Deletes all objects from the cache which match the provided regular expressions.
Regex Invalidate: Marks any objects in the cache which match the given regular expressions as stale. Traffic Server will contact the relevant origin server(s) to confirm the validity and freshness of the cached object, updating the cached object if necessary.

Note

Only one administrator should delete and invalidate cache entries from the Cache Inspector at any point in time. Changes made by multiple administrators at the same time can lead to unpredictable results.

If-Modified-Since/If-None-Match¶

Traffic Server will respond to matching If-Modified-Since/If-None-Match requests with a 304 Not Modified HTTP message.

This table describes how Traffic Server handles these types of requests:

OS = Origin Server's respose HTTP message
IMS = A GET request w/ an If-Modified-Since header
LMs = Last-Modified header date returned by server
INM = A GET request w/ an If-None-Match header
E   = Etag header present
D, D' are Last modified dates returned by the origin server and are later used for IMS
The D date is earlier than the D' date

Client’s Request	Cached State	Proxy’s Request	Response to client
Client’s Request	Cached State	Proxy’s Request	OS 200	OS 304
GET	Fresh	N/A	N/A	N/A
GET	Stale, D’	IMS D’	200, new	200, cached
GET	Stale, E	INM E	200, new	200, cached
INM E	Stale, E	INM E	304	304
INM E + IMS D’	Stale, E + D’	INM E IMS D’	200, new *	304
IMS D	None	GET	200, new *	N/A
INM E	None	GET	200, new *	N/A
IMS D	Stale, D’	IMS D’	200, new	Compare LMs & D’. If match, 304 If no match, 200, cached
IMS D’	Stale, D’	IMS D’	200, new
IMS D’	Stale D	IMS D	200, new *