1. Overview
This document describes how caching works in NGINX® with reverse proxy and provides troubleshooting guidance for common issues.
2. Caching in NGINX with Reverse Proxy
NGINX reverse proxies to Apache and caches all requests by default. Cache data is stored per user in the following directory, where type represents the cache type and username represents the account:
/var/cache/ea-nginx/proxy/username
NGINX uses the proxy cache type for the proxy_pass directive. Cache directories use 700 permissions and are restricted to nobody and root.
Your application must send proper cache-control headers for dynamic content. Without them, users may receive cached responses that do not apply to their session.
To fix this issue, you can:
- Disable caching for the user in WHM’s NGINX Manager.
- Modify your application to send correct cache-control headers.
3. Custom Cache Keys
You can configure NGINX to generate separate caches for different conditions (e.g., mobile vs. desktop users). To do this, set the $CACHE_KEY_PREFIX variable in:
/etc/nginx/conf.d/includes-optional/set-CACHE_KEY_PREFIX.conf
This file includes a commented example for mobile caching.
For more details, refer to the NGINX Proxy documentation.
4. Managing Caching with .htaccess
You can use .htaccess files to manage caching behavior. This is useful when your application does not set proper headers.
Example for disabling caching on sensitive paths:
# Application sends private data without proper headers.
Header set Pragma "no-cache"
Header set Cache-Control "max-age=0, no-cache, no-store, must-revalidate"
Header set Expires "Thu, 1 Jan 1970 00:00:00 GMT"
Important: If your application does not send proper headers for sensitive data, it is a security risk.
To enable caching for common static files:
Header set Cache-Control "max-age=3600, public"
5. Third‑Party Integration
Third‑party tools can detect NGINX caching status using the following logic:
- If
/etc/nginx/ea-nginx/cache.jsondoes not exist → NGINX is not installed. - If
enabledexists in:
User-level file:
/var/cpanel/userdata/user/nginx-cache.json
Global file:
/etc/nginx/ea-nginx/cache.json
If neither file contains enabled, caching is enabled by default.
6. Troubleshooting NGINX
6.1 “Could not build proxy_headers hash” Error
You may see an error like:
nginx: [emerg] could not build proxy_headers_hash, you should increase proxy_headers_hash_bucket_size
This occurs when a proxy_set_header directive uses a very long header name.
Fix: Add the following directive immediately before the long header:
proxy_headers_hash_bucket_size number;
6.2 NGINX Will Not Restart
If you manually started NGINX using the nginx command, normal restart commands will fail.
Fix:
- Stop the service:
/usr/sbin/nginx -s stop
- Restart using one of the following:
/usr/local/cpanel/scripts/restartsrv_nginx start
systemctl start nginx.service
/etc/init.d/nginx start
Conclusion
NGINX caching with reverse proxy provides powerful performance benefits, but it requires proper application headers and careful configuration. With custom cache keys, .htaccess overrides, and clear troubleshooting steps, administrators can maintain a secure and efficient caching environment.