Skip to content

Commit 4082fed

Browse files
annkotsannkots
authored
Merge branch 'cloudlinux:master' into master
2 parents 52ebedf + 61749a6 commit 4082fed

3 files changed

Lines changed: 314 additions & 36 deletions

File tree

‎docs/cloudlinuxos/cloudlinux_os_components/README.md‎

Lines changed: 56 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3651,15 +3651,70 @@ MySQL Governor allows setting the burstable limits for accounts. To provide that
36513651
* `long` on the contrary, should not be more than the LVE limit
36523652
* setting the `middle` and `long` limits less than the LVE limit prevents abuse of other processes in the account (Apache, PHP) by MySQL
36533653
3654+
**Coefficients for calculating limits**
3655+
3656+
MySQL Governor limits should be calculated based on the corresponding LVE limits using the following coefficients:
3657+
3658+
*CPU limits:*
3659+
3660+
| Limit level | Formula | Description |
3661+
|---|---|---|
3662+
| `current` | `LVE_CPUSPEED × 1` | Slightly above the LVE CPU limit to avoid bottlenecks |
3663+
| `short` | `LVE_CPUSPEED × 0.95` | Short-term burst allowance |
3664+
| `middle` | `LVE_CPUSPEED × 0.87` | Medium-term average |
3665+
| `long` | `LVE_CPUSPEED × 0.75` | Long-term sustained maximum |
3666+
3667+
*IO limits:*
3668+
3669+
| Limit level | Formula | Description |
3670+
|---|---|---|
3671+
| `current` | `LVE_IO × 1` | Slightly above the LVE IO limit |
3672+
| `short` | `LVE_IO × 0.83` | Short-term burst allowance |
3673+
| `middle` | `LVE_IO × 0.76` | Medium-term average |
3674+
| `long` | `LVE_IO × 0.59` | Long-term sustained maximum |
3675+
3676+
**How IO limits are calculated**
3677+
3678+
:::warning Important
3679+
The MySQL IO value tracked by MySQL Governor is the **combined total of read and write operations**. For example, if a user's LVE IO limit is 100 MB/s, the corresponding MySQL IO total is 200 MB/s (100 MB/s read + 100 MB/s write).
3680+
:::
3681+
3682+
In the MySQL Governor configuration (`/etc/container/mysql-governor.xml`), the `read` and `write` limits are specified separately. The coefficients above are applied to each limit individually.
36543683
36553684
**Example of choosing MySQL Governor limits**
36563685
3657-
* With the default LVE SPEED limit of `100`, the corresponding MySQL Governor CPU limits are `101/95/87/75` (applying the coefficients above). We admit the short-term exceeding of the limits for processing SQL requests.
3686+
* With the default LVE SPEED limit of `100`, the corresponding MySQL Governor CPU limits are `100/95/87/75` (applying the coefficients above). We admit the short-term exceeding of the limits for processing SQL requests.
36583687
* If you face spike CPU consumption with these limits, it is recommended to reduce the excess of the `current` and `short` limits over the LVE limit. For example, to the values 150/110/100/90.
36593688
* If the average level of CPU consumption is too high, then it is recommended to reduce the `middle` and `long` limits, too. For example, to the values 150/100/80/50.
36603689
* Then MySQL processes will fall into LVE and be limited by LVE limits more often.
36613690
* The same clues are applicable to the IO limits – the `current` and `short` IO limits for MySQL Governor can exceed IO LVE limits, but the `middle` and `long` cannot.
36623691
3692+
**Configuration example**
3693+
3694+
For a user with a 400% (CPU) SPEED MySQL limit and a 200 MB/s MySQL IO limit, the MySQL Governor limits would be configured as follows:
3695+
3696+
<div class="notranslate">
3697+
3698+
```
3699+
<user name="USERNAME" mode="restrict">
3700+
<limit name="cpu" current="400" short="380" mid="348" long="300"/>
3701+
<limit name="read" current="104857600" short="87031808" mid="79691776" long="61865984"/>
3702+
<limit name="write" current="104857600" short="87031808" mid="79691776" long="61865984"/>
3703+
</user>
3704+
```
3705+
</div>
3706+
3707+
You can verify the applied limits using `dbctl list`:
3708+
3709+
<div class="notranslate">
3710+
3711+
```
3712+
[root@server ~]# dbctl list
3713+
user cpu(%) read(MB/s) write(MB/s)
3714+
USERNAME 400/380/348/300 100/83/76/59 100/83/76/59
3715+
```
3716+
</div>
3717+
36633718
#### Starting and stopping
36643719
36653720
To start:

‎docs/cloudlinuxos/shared-pro/README.md‎

Lines changed: 226 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1291,7 +1291,9 @@ yum reinstall ea-php80-php-mbstring
12911291
12921292
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.
12931293
1294-
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.
1294+
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.
1295+
1296+
The module includes two independent subsystems: **cache serving** (serves pre-generated static HTML files, bypassing PHP) and **full .htaccess caching** (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.
12951297
12961298
:::warning Note:
12971299
MAx Cache is currently supported on cPanel control panels only.
@@ -1302,12 +1304,20 @@ MAx Cache is currently supported on cPanel control panels only.
13021304
To install MAx Cache, run the following commands:
13031305
13041306
```
1305-
yum install accelerate-wp cloudlinux-site-optimization-module libmaxcache --enablerepo=cloudlinux-updates-testing
1307+
yum install accelerate-wp cloudlinux-site-optimization-module libmaxcache maxcache-htcache-watchd --enablerepo=cloudlinux-updates-testing
13061308
```
13071309
```
1308-
yum install ea-apache24-mod_maxcache --enablerepo-cl-ea4-testing
1310+
yum install ea-apache24-mod_maxcache --enablerepo=cl-ea4-testing
13091311
```
13101312
1313+
| Package | Description |
1314+
| --- | --- |
1315+
| `ea-apache24-mod_maxcache` | Apache module with cache serving and full .htaccess caching subsystems |
1316+
| `maxcache-htcache-watchd` | Filesystem watcher daemon for real-time `.htaccess` change detection |
1317+
| `libmaxcache` | Shared C library for device detection, WebP, cookie/QS handling |
1318+
1319+
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.
1320+
13111321
### MAx Cache Activation Guide
13121322
13131323
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:
18881898
* Using the AccelerateWP PHP filter to replace dots with underscores.
18891899
* Using the AccelerateWP PHP filter forces the full path to cache files instead of using DOCUMENT_ROOT.
18901900
1901+
### Full .htaccess caching
1902+
1903+
Full .htaccess caching 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.
1904+
1905+
Full .htaccess caching benefits **all** `.htaccess`-heavy sites regardless of whether MAx Cache page caching is enabled.
1906+
1907+
#### How it works
1908+
1909+
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. Full .htaccess caching 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.
1910+
1911+
#### Change detection
1912+
1913+
Full .htaccess caching detects `.htaccess` changes through two mechanisms:
1914+
1915+
| Mode | Detection latency | When active |
1916+
| --- | --- | --- |
1917+
| **watchd (real-time)** | Sub-second | When `maxcache-htcache-watchd` service is running |
1918+
| **Polling (fallback)** | Up to `MaxCacheHTCacheRevalidateInterval` seconds (default 60) | Always active as a safety net |
1919+
1920+
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.
1921+
1922+
:::warning CloudLinux 7/8 limitations
1923+
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`).
1924+
1925+
On CloudLinux 9+ (kernel 5.14+), all change types — including deletes, renames, and moves — are detected in real time.
1926+
:::
1927+
1928+
#### Configuration directives
1929+
1930+
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`.
1931+
1932+
#### MaxCacheHTCache
1933+
1934+
* **Syntax**: `MaxCacheHTCache On|Off`
1935+
* **Default**: On (in shipped config)
1936+
* **Context**: server config, virtual host
1937+
* **Description**: Master enable/disable switch for the full .htaccess caching subsystem.
1938+
1939+
#### MaxCacheHTCacheRevalidateInterval
1940+
1941+
* **Syntax**: `MaxCacheHTCacheRevalidateInterval <seconds>`
1942+
* **Default**: 60
1943+
* **Range**: 1–3600
1944+
* **Context**: server config, virtual host
1945+
* **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.
1946+
1947+
#### MaxCacheHTCacheEntries
1948+
1949+
* **Syntax**: `MaxCacheHTCacheEntries <count>`
1950+
* **Default**: 50000
1951+
* **Range**: 10–500000
1952+
* **Context**: server config, virtual host
1953+
* **Description**: Maximum number of cached `.htaccess` entries in shared memory. When this limit is reached, new directories fall back to Apache's standard processing.
1954+
1955+
#### MaxCacheHTCacheMemorySize
1956+
1957+
* **Syntax**: `MaxCacheHTCacheMemorySize <MB>`
1958+
* **Default**: auto (derived from `MaxCacheHTCacheEntries`)
1959+
* **Range**: 1–4096
1960+
* **Context**: server config, virtual host
1961+
* **Description**: Shared memory arena size in megabytes. Normally sized automatically — only set this if you see `htcache: arena memory exhausted` in the error log.
1962+
1963+
#### MaxCacheHTCacheExclude
1964+
1965+
* **Syntax**: `MaxCacheHTCacheExclude <path> [path2] ...`
1966+
* **Default**: none
1967+
* **Context**: server config, virtual host
1968+
* **Description**: Exclude directory trees from full .htaccess caching. The path is matched as a prefix.
1969+
* **Example**:
1970+
```
1971+
MaxCacheHTCacheExclude /home/staging /tmp
1972+
```
1973+
1974+
#### MaxCacheHTCacheMaxFileSize
1975+
1976+
* **Syntax**: `MaxCacheHTCacheMaxFileSize <KB>`
1977+
* **Default**: 256
1978+
* **Range**: 0–10240
1979+
* **Context**: server config, virtual host
1980+
* **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.
1981+
1982+
#### MaxCacheHTCacheMaxEntriesPerDocroot
1983+
1984+
* **Syntax**: `MaxCacheHTCacheMaxEntriesPerDocroot <count>`
1985+
* **Default**: 256
1986+
* **Range**: 0–100000
1987+
* **Context**: server config, virtual host
1988+
* **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).
1989+
1990+
#### Configuration examples
1991+
1992+
##### Minimal setup
1993+
1994+
```
1995+
MaxCacheHTCache On
1996+
```
1997+
1998+
Enables full .htaccess caching globally with default settings (50,000 max entries, 60-second revalidation).
1999+
2000+
##### Production shared hosting
2001+
2002+
For a server with ~5,000 WordPress sites:
2003+
2004+
```
2005+
<IfModule mod_maxcache.c>
2006+
MaxCacheHTCache On
2007+
MaxCacheHTCacheEntries 100000
2008+
</IfModule>
2009+
```
2010+
2011+
##### Per-vhost with exclusions
2012+
2013+
```
2014+
<VirtualHost *:443>
2015+
ServerName example.com
2016+
DocumentRoot /home/example/public_html
2017+
2018+
MaxCacheHTCache On
2019+
MaxCacheHTCacheEntries 10000
2020+
MaxCacheHTCacheExclude /home/example/public_html/tmp
2021+
</VirtualHost>
2022+
```
2023+
2024+
##### Disable full .htaccess caching for a specific vhost
2025+
2026+
Enable globally but opt out specific vhosts:
2027+
2028+
```
2029+
# httpd.conf (global)
2030+
MaxCacheHTCache On
2031+
2032+
<VirtualHost *:443>
2033+
ServerName staging.example.com
2034+
DocumentRoot /home/staging/public_html
2035+
MaxCacheHTCache Off
2036+
</VirtualHost>
2037+
```
2038+
2039+
#### Status endpoint
2040+
2041+
Full .htaccess caching provides a status handler for monitoring. To enable it, add a `<Location>` block to your Apache configuration:
2042+
2043+
```
2044+
<Location /htcache-status>
2045+
SetHandler htcache-status
2046+
Require local
2047+
</Location>
2048+
```
2049+
2050+
Then query it:
2051+
2052+
```
2053+
curl -s http://localhost/htcache-status
2054+
```
2055+
2056+
Example output:
2057+
2058+
```
2059+
mod_maxcache HTCache Status
2060+
===========================
2061+
2062+
Mode: lazy on-demand
2063+
Enabled: yes
2064+
Ready: yes
2065+
Entries: 1234 / 50000
2066+
Lazy compiles: 5678
2067+
PCRE mode: shared (GOT patched)
2068+
2069+
Arena Architecture: Base + Patch Pool + Shadow
2070+
Active Base: Arena A
2071+
Arena size: 50MB each (x 2)
2072+
Arena usage: 8192KB / 50MB (16%)
2073+
Patch Pool: 256KB / 12MB used (2%)
2074+
Compacting: no
2075+
Compaction threshold: 80%
2076+
2077+
Invalidation SHM: connected
2078+
Revalidate interval: 60s
2079+
2080+
Cache (global):
2081+
Hits: 45000
2082+
Misses: 1234
2083+
```
2084+
2085+
Key fields to check:
2086+
2087+
| Field | Healthy value | Problem indicator |
2088+
| --- | --- | --- |
2089+
| Enabled | `yes` | `no` — full .htaccess caching is turned off in config |
2090+
| Ready | `yes` | `no` — engine failed to initialize |
2091+
| Entries | below max | at max — increase `MaxCacheHTCacheEntries` |
2092+
| Arena usage | below 90% | above 90% — increase `MaxCacheHTCacheMemorySize` |
2093+
| Invalidation SHM | `connected` | `not available` — watchd is not running or SHM file is missing |
2094+
| Hits | increasing | staying at 0 — full .htaccess caching is not serving cached results |
2095+
2096+
:::warning
2097+
The status endpoint should be restricted to localhost or trusted IPs. Remove or restrict the `<Location>` block in production.
2098+
:::
2099+
2100+
#### Troubleshooting
2101+
2102+
| Check | Command | Expected |
2103+
| --- | --- | --- |
2104+
| watchd running? | `systemctl is-active maxcache-htcache-watchd` | `active` |
2105+
| SHM file exists? | `ls -la /dev/shm/htcache_invalidate` | File present |
2106+
| File too large? | `wc -c /path/to/.htaccess` | Under 256 KB (default `MaxCacheHTCacheMaxFileSize`) |
2107+
| Path excluded? | `grep MaxCacheHTCacheExclude /etc/apache2/conf.d/maxcache_htcache.conf` | Path not listed |
2108+
| Log: `htcache: entry limit reached (50000/50000), skipping /path` | Cache is full — increase `MaxCacheHTCacheEntries` | Remaining directories use standard Apache processing |
2109+
| Log: `htcache: per-docroot entry limit reached (256/256) for /home/user` | Single user filled their quota — increase `MaxCacheHTCacheMaxEntriesPerDocroot` | Other users are not affected |
2110+
| Log: `htcache: arena memory exhausted (400MB/400MB)` | Shared memory arena is full — increase `MaxCacheHTCacheMemorySize` | Restart Apache after changing |
2111+
2112+
If changes must take effect immediately, restart Apache: `systemctl restart httpd`.
2113+
18912114
## MAx Cache for NGINX
18922115
18932116
### Overview

0 commit comments

Comments
 (0)