Nginx Cache Purge Preload

Yes. NPP is engineered with a highly defensive, multi-layered "Narrow Gate" architecture using a lazy bootstrap mechanism to minimize your server's attack surface. To minimize performance overhead and vulnerability surfaces, NPP stays dormant on anonymous public traffic, verifying entry paths before heavy core files ever load into memory. For hardened environment security, it also ships with its own secure privilege-dropping wrapper, safexec—a custom C-binary utility designed to isolate system commands and execute them under a low-privilege runtime user.

Yes. Nginx must be part of your web server stack. It does not matter if Nginx is configured as a frontend reverse proxy or as the direct backend server—as long as Nginx is handling the caching layer on a Linux environment, the plugin works perfectly. It does not work on standalone Apache setups, restricted shared hosting, or environments where shell_exec and exec are disabled.

Yes. NPP shows your Fail2Ban bans and unbans in a live dashboard with jail activity, repeat offenders, a Top Attack Countries map and network details per IP. It is read-only: Fail2Ban keeps blocking as before, and NPP never bans, unbans or edits your jails. The feature is optional and separate from cache management.

Open the Fail2Ban tab, copy the generated nppp-webhook action file to /etc/fail2ban/action.d/, add the generated line under each jail in jail.local, run sudo systemctl reload fail2ban, then press Test Connection. The Fail2Ban host needs curl and flock and must be able to reach your site. Several servers or jails can report to one dashboard.

Yes. It requires a secret token you can regenerate at any time, validates every field, ignores replayed events and rate-limits requests. The tab also provides an optional Nginx rate-limit snippet, and rejected requests are listed in the Endpoint Attacks card.

No. A report is sent only when an administrator clicks Send in the Fail2Ban tab or runs the WP-CLI command. You can preview each report, send a test email, use dry-run mode, and set a minimum ban count and a per-IP cooldown.

The banned IP, jail, event type, timestamp and looked-up network details, in a dedicated database table. Events are deleted after 90 days by default, can be cleared from the Fail2Ban tab, and are removed on uninstall. See the Privacy Policy and External services sections.

No. The ngx_cache_purge module is optional. When available, NPP uses it as the first purge path (HTTP Purge). If it is not present, NPP automatically falls back to a URL index lookup and then a full filesystem scan. Nothing breaks either way. Currently relying on ngx_cache_purge module today introduces unnecessary security and stability risks to your server and not recommended.

• Unproven Security (Lack of updates): The original module project has not been actively maintained for several years. It receives no routine security reviews, vulnerability patches, or bug fixes.
• Unreliable Codebase (Fragmented availability): Because the original project stalled-abandoned, the community has created multiple independent "forks" just to keep it working. This fragmentation makes it nearly impossible to guarantee which version is actually secure or fully compatible with your nginx config and version.
• Vulnerable Defaults (Outdated system packages): Due to the lack of an proven, and trusted release, most Linux distributions default to shipping outdated, decade-old versions of this module. These legacy builds lack modern security standards and frequently experience compatibility issues in real-world production scenarios.

Mostly basic, built-in shell tools are required. wget is required for cache preloading. For hardened shell execution, safexec is highly recommended — see the Help tab for installation instructions. For large cache-heavy websites, especially when Nginx cache paths are located on FUSE-based mounts (such as bindfs to solve permission issues), ripgrep (rg) is strongly recommended for significantly faster cache purge performance.

Hard Dependencies

• shell_exec – The primary dependency used for core plugin functionality.
• exec – Required for executing ripgrep RG Purge.

• proc_open, proc_close, proc_get_status – Required for the health check of background preload process.
• putenv, getenv – Required to pass critical runtime flags to the safexec and drive the URL Normalization feature.

The most common reasons are: shell_exec and exec is disabled, open_basedir restrictions prevent required filesystem access, the PHP-FPM user lacks write permission to the Nginx cache directory, or Nginx detection fails (nginx.conf cannot be located). See the Help tab for a full environment checklist and solutions.

This is the most common issue in environments where the WEBSERVER-USER (nginx/www-data) and PHP-FPM-USER are different. NPP provides a one-liner bash script to automate the fix using bindfs on monolithic servers. For containerized environments, users can review the full configuration setup via NPP Containerized See the Help tab → Permission Issues section or the GitHub repository for details.

Yes. NPP has built-in Cloudflare APO Sync that mirrors every purge to Cloudflare’s edge cache automatically. Requires the official Cloudflare WordPress plugin. Enable it under Settings.

Yes. NPP supports Redis Object Cache Sync, which keeps Redis and the Nginx cache aligned during purge and preload operations. When enabled, NPP flushes the Redis object cache at the correct point in the Nginx Purge + Preload chain to ensure fresh content is used when rebuilding cache. Enable it under Settings.

Yes. NPP includes built-in WooCommerce Auto-Purge for stock changes and order events, and supports purging the Shop page as a related URL when a product is updated.

Yes, but disable page caching in other plugins to avoid conflicts. You can keep their frontend optimization features (minification, lazy loading) active. For the best results, NPP pairs best with lightweight, minification-only trusted plugins. Because Nginx already handles your page caching instantly at the server level, using heavy, code-bloated page caching plugins only introduces unnecessary overhead even you disable page caching features. Keeping your frontend optimization layer as lean as possible is the ideal match for high-speed Nginx caching.

NPP restricts cache paths by default to prevent accidental deletion of system files. Allowed roots are /dev/shm/, /tmp/, /var/, and /cache/. The path must be at least one level deep (e.g. /var/cache/nginx). These restrictions can be completely disabled using the Bypass Path Restriction feature, which removes all path safety guardrails and allows any directory to be used as the Nginx cache path. Full details in the Help tab.

Yes. NPP includes full WP-CLI integration. You can purge, preload, check status, view logs, update settings, flush transients, and manage scheduled events directly from the terminal — no admin dashboard access required. Run wp help npp and wp help npp <subcommand> to see all available commands.

NPP supports FastCGI, Proxy, SCGI, and uWSGI cache methods. The plugin automatically applies the appropriate purge strategy (HTTP Purge, INDEX Purge, or RG Purge).

HTTP Purge is an optional fast‑path that uses Nginx's ngx_cache_purge module to delete cache entries via a simple HTTP request. It is the fastest possible single‑URL purge method because it avoids any filesystem scan.

RG Purge is a much faster alternative to the traditional PHP filesystem scan. It uses ripgrep (rg) — line-oriented search tool written in Rust — to locate nginx cache files in a fraction of the time. On a typical website with thousands of cached URLs, the built‑in PHP recursive iterator can take anywhere from 10 to 60 seconds to scan the disk and locate cache files for a single purge event. RG Purge reduces this cleanup time to 1–2 seconds regardless of cache size by using parallel directory traversal and memory‑mapped I/O.

• When to enable: Strongly recommended for large or high-traffic sites with over 10,000 URLs, or any environment where Nginx cache paths are stored on slower disk arrays or FUSE-based mounts (like bindfs).

During every cache preload, NPP quietly builds a persistent URL‑to‑filepath index. When you later purge a specific page (manually, or via auto‑purge), the plugin first checks this index. If the URL is found, NPP instantly knows the exact cache file location and deletes it immediately — with zero disk scanning. This is the second‑fastest purge path (FP2) and works even on sites with hundreds of thousands of cached files. The index is automatically updated after each purge and can be cleared manually from the Status tab if your cache structure changes.

safexec is a small, privilege‑dropping wrapper (written in C) created specifically for NPP. It is used to safely execute system commands like wget, and rg while enforcing strict security controls. What it does?

• Drops privileges to a low‑privilege user (nobody) before running the shell command.
• Scrubs the environment to prevent information leaks.
• Optionally normalizes percent‑encoded characters in URLs during cache preloading — solving a common cause of duplicate cache entries (e.g., %2F vs /).

• In environments where you want to mitigate the risk and impact of potential command injections.
• In FUSE environments where the PHP user lacks access to the underlying cache directory — safexec can temporarily assume the Nginx user's identity to read directly from the real path for faster Purge operations.

• OFF – No normalization (default).
• UPPER – Convert all percent‑encoded sequences to uppercase (e.g., %2f → %2F).
• LOWER – Convert to lowercase.
• PRESERVE – Keep original casing but still normalize unreserved characters.

Yes. NPP's preload engine no longer blindly ignores all query‑string URLs. It uses a smart list of unsafe parameters (cart, checkout, admin, preview, etc.) and allows everything else — sorting options, product filters, language switches, UTM marketing tags — to be preloaded and served from cache. This dramatically increases cache coverage for WooCommerce stores and busy content sites.

Yes. When Auto Purge is enabled and Auto Preload is switched on (globally or per‑page), NPP will immediately begin preloading the affected pages after a purge — no manual steps required. This keeps the cache warm even after content updates, stock changes, or theme/plugin upgrades.

Yes. NPP includes a "Preload Feeds" option that warms your main RSS2, Atom, per‑post comment feeds, and taxonomy‑specific feeds (categories, tags, custom taxonomies). This ensures feed readers, RSS‑to‑email services, and search engine crawlers always receive a fast, cached response — without waking up PHP on every refresh.

Most Nginx cache plugins rely on a single purge method — usually a slow, recursive PHP scan of every file in the cache directory, or they require a special Nginx cache module. NPP uses a layered fast‑path chain that automatically picks the fastest available method for every single‑URL purge, without you needing to configure anything.

• FP1 – HTTP Purge – If the ngx_cache_purge module is present, NPP instructs Nginx to delete the cache entry via a simple HTTP request. Near‑instant.
• FP2 – Index Purge – If the URL is already indexed from a previous preload, NPP finds the cache file path in memory — zero disk scanning.
• FP3 – RG Purge – If ripgrep is installed, a single, highly optimized system command locates all matching cache files in 1–2 seconds, even on directories with 50,000+ files.
• FP4 – PHP recursive scan – The traditional method; used only as a silent fallback when nothing faster is available.

• No single point of failure — if one method isn’t available, the next one takes over automatically.
• Your purges are always as fast as your server environment allows, without changing any settings.
• You can improve purge speed later simply by installing ripgrep or enabling the Nginx cache module (not currently recommended) — the plugin adapts instantly.