Skip to content

Add HTCache (.htaccess caching) documentation to MaxCache section #305

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
annkots merged 1 commit into from
Mar 19, 2026
Merged

Add HTCache (.htaccess caching) documentation to MaxCache section #305

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
229 changes: 226 additions & 3 deletions docs/cloudlinuxos/shared-pro/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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.
Expand Down Expand Up @@ -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 `<IfModule mod_maxcache.c>` 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 <seconds>`
* **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 <count>`
* **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 <MB>`
* **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 <path> [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 <KB>`
* **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 <count>`
* **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:

```
<IfModule mod_maxcache.c>
MaxCacheHTCache On
MaxCacheHTCacheEntries 100000
</IfModule>
```

##### Per-vhost with exclusions

```
<VirtualHost *:443>
ServerName example.com
DocumentRoot /home/example/public_html

MaxCacheHTCache On
MaxCacheHTCacheEntries 10000
MaxCacheHTCacheExclude /home/example/public_html/tmp
</VirtualHost>
```

##### Disable HTCache for a specific vhost

Enable globally but opt out specific vhosts:

```
# httpd.conf (global)
MaxCacheHTCache On

<VirtualHost *:443>
ServerName staging.example.com
DocumentRoot /home/staging/public_html
MaxCacheHTCache Off
</VirtualHost>
```

#### Status endpoint

HTCache provides a status handler for monitoring. To enable it, add a `<Location>` block to your Apache configuration:

```
<Location /htcache-status>
SetHandler htcache-status
Require local
</Location>
```

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 `<Location>` 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
Expand Down