diff --git a/docs/cloudlinuxos/shared-pro/README.md b/docs/cloudlinuxos/shared-pro/README.md index 750df9a98..a71cc7ac7 100644 --- a/docs/cloudlinuxos/shared-pro/README.md +++ b/docs/cloudlinuxos/shared-pro/README.md @@ -1291,7 +1291,9 @@ yum reinstall ea-php80-php-mbstring This design eliminates per-request regex compilation in `.htaccess`, resulting in significantly faster cache delivery. The module is fully compatible with AccelerateWP's cache directory layout and can be used by any caching plugin that follows similar conventions. -AccelerateWP uses this module to serve the correct static page without invoking PHP or writing complex RewriteRule-based configurations. This document summarizes the module's directives and describes how any page cache plugin can integrate with the same capabilities. +AccelerateWP uses this module to serve the correct static page without invoking PHP or writing complex RewriteRule-based configurations. This document summarizes the module's directives and describes how any page cache plugin can integrate with the same capabilities. + +The module includes two independent subsystems: **cache serving** (serves pre-generated static HTML files, bypassing PHP) and **HTCache** (caches parsed `.htaccess` files in shared memory, eliminating per-request disk I/O). Both are included in the same `ea-apache24-mod_maxcache` package and can be enabled independently. :::warning Note: MAx Cache is currently supported on cPanel control panels only. @@ -1302,12 +1304,20 @@ MAx Cache is currently supported on cPanel control panels only. To install MAx Cache, run the following commands: ``` -yum install accelerate-wp cloudlinux-site-optimization-module libmaxcache --enablerepo=cloudlinux-updates-testing +yum install accelerate-wp cloudlinux-site-optimization-module libmaxcache maxcache-htcache-watchd --enablerepo=cloudlinux-updates-testing ``` ``` -yum install ea-apache24-mod_maxcache --enablerepo-cl-ea4-testing +yum install ea-apache24-mod_maxcache --enablerepo=cl-ea4-testing ``` +| Package | Description | +| --- | --- | +| `ea-apache24-mod_maxcache` | Apache module with cache serving and HTCache subsystems | +| `maxcache-htcache-watchd` | Filesystem watcher daemon for real-time `.htaccess` change detection | +| `libmaxcache` | Shared C library for device detection, WebP, cookie/QS handling | + +After installation, the HTCache subsystem is enabled by default (`MaxCacheHTCache On`) and the `maxcache-htcache-watchd` daemon is automatically started and enabled on boot. + ### MAx Cache Activation Guide Use the following commands to manage MAx Cache on your server via the cloudlinux-awp-admin tool. @@ -1888,6 +1898,219 @@ MAx Cache will not work in AccelerateWP when: * Using the AccelerateWP PHP filter to replace dots with underscores. * Using the AccelerateWP PHP filter forces the full path to cache files instead of using DOCUMENT_ROOT. +### HTCache (.htaccess caching) + +HTCache is the second subsystem of `mod_maxcache`. It caches parsed `.htaccess` files in shared memory, so Apache does not re-read and re-parse them from disk on every request. On shared-hosting servers with thousands of sites, this eliminates thousands of `stat()` and `open()` syscalls per second. + +HTCache benefits **all** `.htaccess`-heavy sites regardless of whether MAx Cache page caching is enabled. + +#### How it works + +By default, Apache re-reads and re-parses `.htaccess` files from disk on every request. On shared-hosting servers with thousands of sites, this creates significant disk I/O overhead. HTCache parses each `.htaccess` once (on first request) and stores the result in shared memory so all Apache workers can reuse it without touching the disk again. The cache populates lazily as traffic arrives. + +#### Change detection + +HTCache detects `.htaccess` changes through two mechanisms: + +| Mode | Detection latency | When active | +| --- | --- | --- | +| **watchd (real-time)** | Sub-second | When `maxcache-htcache-watchd` service is running | +| **Polling (fallback)** | Up to `MaxCacheHTCacheRevalidateInterval` seconds (default 60) | Always active as a safety net | + +When the `maxcache-htcache-watchd` daemon is running, it monitors the filesystem and signals Apache through shared memory whenever a `.htaccess` file is created, modified, or deleted. + +:::warning CloudLinux 7/8 limitations +On CloudLinux 7 and 8, the kernel's `fanotify` interface only supports file write events. This means the watchd daemon detects `.htaccess` **modifications** instantly, but **deletes**, **renames**, and **moves** are not detected in real time — they rely on the polling fallback (`MaxCacheHTCacheRevalidateInterval`, default 60 seconds). If you need faster detection of these operations on CL7/CL8, lower the revalidation interval (e.g. `MaxCacheHTCacheRevalidateInterval 10`). + +On CloudLinux 9+ (kernel 5.14+), all change types — including deletes, renames, and moves — are detected in real time. +::: + +#### Configuration directives + +All HTCache directives go inside `` in the Apache configuration. HTCache is configured in `/etc/apache2/conf.d/maxcache_htcache.conf`. + +#### MaxCacheHTCache + +* **Syntax**: `MaxCacheHTCache On|Off` +* **Default**: On (in shipped config) +* **Context**: server config, virtual host +* **Description**: Master enable/disable switch for the HTCache subsystem. + +#### MaxCacheHTCacheRevalidateInterval + +* **Syntax**: `MaxCacheHTCacheRevalidateInterval ` +* **Default**: 60 +* **Range**: 1–3600 +* **Context**: server config, virtual host +* **Description**: Polling interval for `mtime` checks when the watchd daemon is not running or for event types not detected by `fanotify` on the current platform. Lower values mean faster detection of changes via polling; higher values reduce `stat()` syscalls. + +#### MaxCacheHTCacheEntries + +* **Syntax**: `MaxCacheHTCacheEntries ` +* **Default**: 50000 +* **Range**: 10–500000 +* **Context**: server config, virtual host +* **Description**: Maximum number of cached `.htaccess` entries in shared memory. When this limit is reached, new directories fall back to Apache's standard processing. + +#### MaxCacheHTCacheMemorySize + +* **Syntax**: `MaxCacheHTCacheMemorySize ` +* **Default**: auto (derived from `MaxCacheHTCacheEntries`) +* **Range**: 1–4096 +* **Context**: server config, virtual host +* **Description**: Shared memory arena size in megabytes. Normally sized automatically — only set this if you see `htcache: arena memory exhausted` in the error log. + +#### MaxCacheHTCacheExclude + +* **Syntax**: `MaxCacheHTCacheExclude [path2] ...` +* **Default**: none +* **Context**: server config, virtual host +* **Description**: Exclude directory trees from HTCache. The path is matched as a prefix. +* **Example**: +``` +MaxCacheHTCacheExclude /home/staging /tmp +``` + +#### MaxCacheHTCacheMaxFileSize + +* **Syntax**: `MaxCacheHTCacheMaxFileSize ` +* **Default**: 256 +* **Range**: 0–10240 +* **Context**: server config, virtual host +* **Description**: Maximum `.htaccess` file size (in KB) that HTCache will process. Files exceeding this limit are skipped and served via Apache's standard processing. Set to `0` for unlimited. + +#### MaxCacheHTCacheMaxEntriesPerDocroot + +* **Syntax**: `MaxCacheHTCacheMaxEntriesPerDocroot ` +* **Default**: 256 +* **Range**: 0–100000 +* **Context**: server config, virtual host +* **Description**: Maximum cached entries under a single document root. Prevents one user from monopolizing the shared cache on multi-tenant servers. Set to `0` for unlimited (the global `MaxCacheHTCacheEntries` limit still applies). + +#### Configuration examples + +##### Minimal setup + +``` +MaxCacheHTCache On +``` + +Enables HTCache globally with default settings (50,000 max entries, 60-second revalidation). + +##### Production shared hosting + +For a server with ~5,000 WordPress sites: + +``` + + MaxCacheHTCache On + MaxCacheHTCacheEntries 100000 + +``` + +##### Per-vhost with exclusions + +``` + + ServerName example.com + DocumentRoot /home/example/public_html + + MaxCacheHTCache On + MaxCacheHTCacheEntries 10000 + MaxCacheHTCacheExclude /home/example/public_html/tmp + +``` + +##### Disable HTCache for a specific vhost + +Enable globally but opt out specific vhosts: + +``` +# httpd.conf (global) +MaxCacheHTCache On + + + ServerName staging.example.com + DocumentRoot /home/staging/public_html + MaxCacheHTCache Off + +``` + +#### Status endpoint + +HTCache provides a status handler for monitoring. To enable it, add a `` block to your Apache configuration: + +``` + + SetHandler htcache-status + Require local + +``` + +Then query it: + +``` +curl -s http://localhost/htcache-status +``` + +Example output: + +``` +mod_maxcache HTCache Status +=========================== + +Mode: lazy on-demand +Enabled: yes +Ready: yes +Entries: 1234 / 50000 +Lazy compiles: 5678 +PCRE mode: shared (GOT patched) + +Arena Architecture: Base + Patch Pool + Shadow +Active Base: Arena A +Arena size: 50MB each (x 2) +Arena usage: 8192KB / 50MB (16%) +Patch Pool: 256KB / 12MB used (2%) +Compacting: no +Compaction threshold: 80% + +Invalidation SHM: connected +Revalidate interval: 60s + +Cache (global): + Hits: 45000 + Misses: 1234 +``` + +Key fields to check: + +| Field | Healthy value | Problem indicator | +| --- | --- | --- | +| Enabled | `yes` | `no` — HTCache is turned off in config | +| Ready | `yes` | `no` — engine failed to initialize | +| Entries | below max | at max — increase `MaxCacheHTCacheEntries` | +| Arena usage | below 90% | above 90% — increase `MaxCacheHTCacheMemorySize` | +| Invalidation SHM | `connected` | `not available` — watchd is not running or SHM file is missing | +| Hits | increasing | staying at 0 — HTCache is not serving cached results | + +:::warning +The status endpoint should be restricted to localhost or trusted IPs. Remove or restrict the `` block in production. +::: + +#### Troubleshooting + +| Check | Command | Expected | +| --- | --- | --- | +| watchd running? | `systemctl is-active maxcache-htcache-watchd` | `active` | +| SHM file exists? | `ls -la /dev/shm/htcache_invalidate` | File present | +| File too large? | `wc -c /path/to/.htaccess` | Under 256 KB (default `MaxCacheHTCacheMaxFileSize`) | +| Path excluded? | `grep MaxCacheHTCacheExclude /etc/apache2/conf.d/maxcache_htcache.conf` | Path not listed | +| Log: `htcache: entry limit reached (50000/50000), skipping /path` | Cache is full — increase `MaxCacheHTCacheEntries` | Remaining directories use standard Apache processing | +| Log: `htcache: per-docroot entry limit reached (256/256) for /home/user` | Single user filled their quota — increase `MaxCacheHTCacheMaxEntriesPerDocroot` | Other users are not affected | +| Log: `htcache: arena memory exhausted (400MB/400MB)` | Shared memory arena is full — increase `MaxCacheHTCacheMemorySize` | Restart Apache after changing | + +If changes must take effect immediately, restart Apache: `systemctl restart httpd`. + ## MAx Cache for NGINX ### Overview