Skip to content

MAXWS-1042: Update MaxCache docs — rename HTCache directives, remove … #320

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
Apr 28, 2026
Merged

MAXWS-1042: Update MaxCache docs — rename HTCache directives, remove … #320

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
113 changes: 52 additions & 61 deletions docs/cloudlinuxos/shared-pro/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1304,7 +1304,7 @@ 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 maxcache-htcache-watchd --enablerepo=cloudlinux-updates-testing
yum install accelerate-wp cloudlinux-site-optimization-module libmaxcache --enablerepo=cloudlinux-updates-testing
```
```
yum install ea-apache24-mod_maxcache --enablerepo=cl-ea4-testing
Expand All @@ -1313,10 +1313,9 @@ yum install ea-apache24-mod_maxcache --enablerepo=cl-ea4-testing
| Package | Description |
| --- | --- |
| `ea-apache24-mod_maxcache` | Apache module with cache serving and full .htaccess caching 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 full .htaccess caching subsystem is enabled by default (`MaxCacheHTCache On`) and the `maxcache-htcache-watchd` daemon is automatically started and enabled on boot.
After installation, the full .htaccess caching subsystem is enabled by default (`MaxCacheHtaccess On`). Change detection uses per-request `stat()` polling — no separate daemon is required.

### MAx Cache Activation Guide

Expand Down Expand Up @@ -1910,89 +1909,83 @@ By default, Apache re-reads and re-parses `.htaccess` files from disk on every r

#### Change detection

Full .htaccess caching detects `.htaccess` changes through two mechanisms:
Full .htaccess caching detects `.htaccess` changes through per-request `stat()` polling. Each cached entry on the current request path is checked against disk when its per-entry timer expires (controlled by `MaxCacheHtaccessRevalidateInterval`).

| Mode | Detection latency | When active |
| `MaxCacheHtaccessRevalidateInterval` | Detection latency | Trade-off |
| --- | --- | --- |
| **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 |
| `0` (default) | Immediate (next request) | Every request `stat()`s each cached directory on its path |
| `N` seconds | Up to `N` seconds | Fewer `stat()` syscalls on busy paths, slower change pick-up |

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.
:::
With the default value of `0`, any `.htaccess` create, modify, or delete is detected on the very next request through that directory — no separate daemon is required.

#### Configuration directives

All full .htaccess caching directives go inside `<IfModule mod_maxcache.c>` in the Apache configuration. Full .htaccess caching is configured in `/etc/apache2/conf.d/maxcache_htcache.conf`.
All full .htaccess caching directives go inside `<IfModule mod_maxcache.c>` in the Apache configuration. Full .htaccess caching is configured in `/etc/apache2/conf.d/maxcache_htaccess.conf`.

#### MaxCacheHTCache
#### MaxCacheHtaccess

* **Syntax**: `MaxCacheHTCache On|Off`
* **Syntax**: `MaxCacheHtaccess On|Off`
* **Default**: On (in shipped config)
* **Context**: server config, virtual host
* **Description**: Master enable/disable switch for the full .htaccess caching subsystem.

#### MaxCacheHTCacheRevalidateInterval
#### MaxCacheHtaccessRevalidateInterval

* **Syntax**: `MaxCacheHTCacheRevalidateInterval <seconds>`
* **Default**: 60
* **Range**: 1–3600
* **Syntax**: `MaxCacheHtaccessRevalidateInterval <seconds>`
* **Default**: 0
* **Range**: 0–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.
* **Description**: Minimum seconds between `mtime` revalidation checks per cached entry on the request path. With the default of `0`, each entry is `stat()`'d on every request through that path for immediate change detection. Larger values reduce `stat()` syscall traffic on busy paths at the cost of slower pick-up of `.htaccess` edits.

#### MaxCacheHTCacheEntries
#### MaxCacheHtaccessEntries

* **Syntax**: `MaxCacheHTCacheEntries <count>`
* **Syntax**: `MaxCacheHtaccessEntries <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
#### MaxCacheHtaccessMemorySize

* **Syntax**: `MaxCacheHTCacheMemorySize <MB>`
* **Default**: auto (derived from `MaxCacheHTCacheEntries`)
* **Syntax**: `MaxCacheHtaccessMemorySize <MB>`
* **Default**: auto (derived from `MaxCacheHtaccessEntries`)
* **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.
* **Description**: Shared memory arena size in megabytes. Normally sized automatically — only set this if you see `maxcache-htaccess: arena memory exhausted` in the error log.

#### MaxCacheHTCacheExclude
#### MaxCacheHtaccessExclude

* **Syntax**: `MaxCacheHTCacheExclude <path> [path2] ...`
* **Syntax**: `MaxCacheHtaccessExclude <path> [path2] ...`
* **Default**: none
* **Context**: server config, virtual host
* **Description**: Exclude directory trees from full .htaccess caching. The path is matched as a prefix.
* **Example**:
```
MaxCacheHTCacheExclude /home/staging /tmp
MaxCacheHtaccessExclude /home/staging /tmp
```

#### MaxCacheHTCacheMaxFileSize
#### MaxCacheHtaccessMaxFileSize

* **Syntax**: `MaxCacheHTCacheMaxFileSize <KB>`
* **Syntax**: `MaxCacheHtaccessMaxFileSize <KB>`
* **Default**: 256
* **Range**: 0–10240
* **Context**: server config, virtual host
* **Description**: Maximum `.htaccess` file size (in KB) that full .htaccess caching will process. Files exceeding this limit are skipped and served via Apache's standard processing. Set to `0` for unlimited.

#### MaxCacheHTCacheMaxEntriesPerDocroot
#### MaxCacheHtaccessMaxEntriesPerDocroot

* **Syntax**: `MaxCacheHTCacheMaxEntriesPerDocroot <count>`
* **Syntax**: `MaxCacheHtaccessMaxEntriesPerDocroot <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).
* **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 `MaxCacheHtaccessEntries` limit still applies).

#### Configuration examples

##### Minimal setup

```
MaxCacheHTCache On
MaxCacheHtaccess On
```

Enables full .htaccess caching globally with default settings (50,000 max entries, 60-second revalidation).
Expand All @@ -2003,8 +1996,8 @@ For a server with ~5,000 WordPress sites:

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

Expand All @@ -2015,9 +2008,9 @@ For a server with ~5,000 WordPress sites:
ServerName example.com
DocumentRoot /home/example/public_html

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

Expand All @@ -2027,12 +2020,12 @@ Enable globally but opt out specific vhosts:

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

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

Expand All @@ -2041,23 +2034,23 @@ MaxCacheHTCache On
Full .htaccess caching provides a status handler for monitoring. To enable it, add a `<Location>` block to your Apache configuration:

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

Then query it:

```
curl -s http://localhost/htcache-status
curl -s http://localhost/maxcache-htaccess-status
```

Example output:

```
mod_maxcache HTCache Status
===========================
MaxCache Htaccess Caching Status
================================

Mode: lazy on-demand
Enabled: yes
Expand All @@ -2074,8 +2067,7 @@ Patch Pool: 256KB / 12MB used (2%)
Compacting: no
Compaction threshold: 80%

Invalidation SHM: connected
Revalidate interval: 60s
Revalidate interval: 0s

Cache (global):
Hits: 45000
Expand All @@ -2088,9 +2080,8 @@ Key fields to check:
| --- | --- | --- |
| Enabled | `yes` | `no` — full .htaccess caching 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 |
| Entries | below max | at max — increase `MaxCacheHtaccessEntries` |
| Arena usage | below 90% | above 90% — increase `MaxCacheHtaccessMemorySize` |
| Hits | increasing | staying at 0 — full .htaccess caching is not serving cached results |

:::warning
Expand All @@ -2101,13 +2092,13 @@ The status endpoint should be restricted to localhost or trusted IPs. Remove or

| 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 |
| Module loaded? | `httpd -M 2>&1 \| grep maxcache` | `maxcache_module` listed |
| Config valid? | `httpd -t` | `Syntax OK` |
| File too large? | `wc -c /path/to/.htaccess` | Under 256 KB (default `MaxCacheHtaccessMaxFileSize`) |
| Path excluded? | `grep MaxCacheHtaccessExclude /etc/apache2/conf.d/maxcache_htaccess.conf` | Path not listed |
| Log: `maxcache-htaccess: entry limit reached (50000/50000), skipping /path` | Cache is full — increase `MaxCacheHtaccessEntries` | Remaining directories use standard Apache processing |
| Log: `maxcache-htaccess: per-docroot entry limit reached (256/256) for /home/user` | Single user filled their quota — increase `MaxCacheHtaccessMaxEntriesPerDocroot` | Other users are not affected |
| Log: `maxcache-htaccess: arena memory exhausted (400MB/400MB)` | Shared memory arena is full — increase `MaxCacheHtaccessMemorySize` | Restart Apache after changing |

If changes must take effect immediately, restart Apache: `systemctl restart httpd`.

Expand Down