en
Nginx Caching Configuration for Onion Services
Serving content efficiently over Tor requires optimizing every component of the stack because circuit latency is inherent and irreducible. Nginx's proxy cache and FastCGI cache layers can dramatically reduce backend load and improve response consistency for onion services by serving frequently accessed content directly from disk or memory. This guide covers practical Nginx caching configuration for hidden services, including cache zone sizing, cache key design, cache control header handling, and cache invalidation strategies appropriate for privacy-focused deployments.
Need this done for your project?
We implement, you ship. Async, documented, done in days.
Nginx Proxy Cache Zone Configuration
Configure a shared memory cache zone in the http block of nginx.conf: proxy_cache_path /var/cache/nginx/onion levels=1:2 keys_zone=onion_cache:100m max_size=10g inactive=60m use_temp_path=off. The keys_zone parameter allocates 100 MB of shared memory for cache metadata. Enable the cache in your server block with proxy_cache onion_cache and proxy_cache_valid 200 302 60m to cache successful responses for 1 hour. Set proxy_cache_use_stale error timeout http_500 http_502 http_503 http_504 to serve cached content when the backend is temporarily unavailable.
Cache Key Design for Onion Services
The default Nginx cache key includes the scheme, host, and URI but not query parameters unless you specify $args. For onion services, the scheme is always http (Tor handles encryption end-to-end within circuits), and the host is the .onion address. Set proxy_cache_key $scheme$host$request_uri to include query parameters in the cache key, which prevents serving the same cached page for different query strings. If your application serves user-specific content based on cookies or session headers, exclude those pages from caching with proxy_cache_bypass $cookie_session $http_authorization.
FastCGI Cache for PHP Applications
PHP applications served via FastCGI can use Nginx's fastcgi_cache instead of proxy_cache. Configure the cache zone: fastcgi_cache_path /var/cache/nginx/fcgi levels=1:2 keys_zone=fcgi_cache:50m max_size=5g inactive=30m. In the PHP location block, enable with fastcgi_cache fcgi_cache and set fastcgi_cache_valid 200 30m for short-lived cache entries appropriate for dynamic content. Implement a cache bypass mechanism by checking for a cookie: fastcgi_cache_bypass $cookie_nocache $arg_nocache. Use fastcgi_cache_lock on to prevent cache stampedes when a cache entry expires.
Cache-Control Header Handling
Nginx respects Cache-Control headers from upstream applications by default. If your application sends Cache-Control: no-store or no-cache, Nginx will not cache the response even if proxy_cache_valid is set. Override this behavior with proxy_ignore_headers Cache-Control Expires when you want Nginx's configuration to take precedence. For content that changes infrequently (images, CSS, JavaScript), configure application-level Cache-Control: public, max-age=3600 to allow both Nginx and any intermediate caches to serve content.
Cache Warming and Invalidation
Cold caches serve no benefit - warm caches before high-traffic events by pre-fetching commonly accessed pages using curl through the SOCKS proxy: curl --socks5-hostname 127.0.0.1:9050 http://yoursite.onion/path. Automate warming with a script that iterates your sitemap.xml URLs. For cache invalidation without the ngx_cache_purge module, use proxy_cache_bypass logic with a secure token to trigger re-fetch of specific URLs. For complete cache clearing, delete the cache zone directory contents and reload Nginx: find /var/cache/nginx/onion -type f -delete and nginx -s reload.
Related Services
Why Anubiz Host
100% async — no calls, no meetings
Delivered in days, not weeks
Full documentation included
Production-grade from day one
Security-first approach
Post-delivery support included
Ready to get started?
Skip the research. Tell us what you need, and we'll scope it, implement it, and hand it back — fully documented and production-ready.