Polipo cache management decides how useful the proxy is in daily use. A well-sized, regularly cleaned cache answers repeat requests quickly, while a neglected one fills the disk with stale files. This guide explains where cached objects live, how freshness is judged and how to keep the cache healthy.
Remember that caching applies to plain HTTP traffic. HTTPS connections are tunnelled without being stored, so the techniques below matter most for HTTP mirrors, package repositories and internal services.
Where Cached Objects Are Stored
The diskCacheRoot variable sets the cache directory, commonly /var/cache/polipo/ on packaged installs. Inside it, objects are stored as files organised by host. That layout makes it easy to see which sites take up space with ordinary tools such as du.
The directory must exist and be writable by the account that runs the proxy. If permissions are wrong, the proxy may keep working as a forwarder while never saving anything, which looks like a cache that is always empty.
sudo mkdir -p /var/cache/polipo
sudo chown proxyuser: /var/cache/polipo
du -sh /var/cache/polipoHow Freshness Is Decided
Servers describe how long a response may be reused through standard HTTP headers. The proxy respects those headers and, when an object is stale, it can revalidate it with the origin server. A successful revalidation returns a short "not modified" answer instead of the full body, saving bandwidth.
Some behaviour can be relaxed with variables such as relaxTransparency, which allows serving slightly stale data in some situations. Relaxing transparency trades accuracy for speed, so use it only when serving an outdated page briefly is acceptable.
Memory cache versus disk cache
Recently used objects are also held in memory. Memory is fast but small, while the disk cache is larger and survives restarts. Limits such as chunkHighMark control the memory side, and the disk side is managed with the expiry process described below.
Running the Expiry Process
The disk cache does not shrink by itself. Running the binary with the -x option performs a cache expiry pass, removing or trimming files according to the housekeeping variables. Many administrators schedule this with cron so the cache never grows without bound.
polipo -x
# example nightly cron entry
30 3 * * * /usr/local/bin/polipo -xUse the same configuration file for the expiry run as for the running proxy, or pass it with -c. Otherwise the expiry process may look in the wrong directory and appear to do nothing.
| Variable | What it influences |
|---|---|
diskCacheRoot | Location of the disk cache; empty string disables it |
diskCacheTruncateSize | Size to which older cached files may be truncated |
diskCacheUnlinkTime | Age after which unused files are removed |
chunkHighMark | Upper limit on memory used for cached data |
relaxTransparency | Whether stale data may be served in some cases |
Clearing Specific Sites or Everything
Because objects are grouped by host, you can delete one site's directory to purge it, ideally while the proxy is stopped. To clear the whole cache, stop the proxy, empty the cache directory and start it again. The built-in local interface also offers ways to inspect cached objects.
- Stop the proxy before deleting files to avoid partial writes.
- Delete a host's folder to purge only that site.
- Empty the whole directory for a full reset.
- Restart and confirm new objects appear after browsing.
Choosing a Sensible Size
There is no single right size. Consider how much free disk space you have, how many clients share the proxy and how repetitive the HTTP traffic is. A lab that downloads the same packages repeatedly benefits from a larger cache than a single user browsing varied sites.
Watch disk usage for a week after setup. If the cache grows quickly and hit rates stay low, shorten the unlink time; if repeated downloads still go to the network, check that responses are cacheable at all.
Offline Browsing
The proxyOffline variable tells the proxy to avoid contacting servers and serve what it has. This can help on unreliable links or when reviewing previously fetched documentation without a connection. Pages that were never cached will simply not be available.
Shared Caches and Privacy
If several people use the same proxy, they share one cache. Setting cacheIsShared appropriately tells the proxy to respect headers that forbid shared caching of private responses. Even so, avoid sharing a cache between people who should not see each other's browsing.
Monitoring Cache Effectiveness
A cache is only worthwhile if it serves repeat requests. Compare disk usage over time with how often clients fetch the same resources. Response headers seen by a client, together with the proxy's own logs, can reveal whether objects come from the cache or the origin server.
The built-in local interface also helps you inspect what is stored. Reviewing which hosts take most of the space shows whether the cache holds useful content or mostly one-off downloads that will never be requested again.
Filesystem Considerations
Cache files are many and often small. Placing the cache on a filesystem with plenty of inodes and reasonable performance avoids surprises. On systems with limited flash storage, such as small boards with memory cards, keep the cache modest to reduce wear and run expiry regularly.
Backups rarely need to include the cache, since every object can be fetched again. Excluding the cache directory from backup jobs saves time and storage while keeping the configuration file, which is the part worth preserving.
Polipo Cache FAQs
The cache directory may not exist or may not be writable by the proxy's user. HTTPS traffic is also never cached, so mostly encrypted browsing leaves little to store.
Schedule polipo -x with cron, using the same configuration file as the running proxy.
With proxyOffline enabled it serves previously cached objects only. Anything not cached will be unavailable.
Yes, ideally with the proxy stopped. Deleting a host's folder purges that site only.
Conclusion
Polipo cache management comes down to a writable cache directory, respect for HTTP freshness rules, a scheduled -x expiry run and sensible limits for memory and disk. With those in place, repeated plain HTTP requests are served quickly without filling the disk.
Check usage regularly and adjust the housekeeping variables as your traffic changes. For the full list of options, revisit the configuration guide.
