Complete documentation

Documentation — WSA for cPanel/WHM

Web Site Accelerator (WSA) — full user manual.
Covers the WHM interface (administrator), the cPanel interface
(end user), the command line, per-package activation, and the
WordPress plugin / PHP class integrations.

For initial install, see
installation-en.md.

Overview
Installation
WHM interface (administrator)
Per-package activation in WHM
cPanel interface — Simple mode
cPanel interface — Advanced mode
Command line
WordPress plugin (generic)
PHP class (generic)

1. Overview

WSA places Nginx in front of Apache: Nginx listens on ports 80 and
443 as reverse proxy + cache server. Apache continues running
PHP/Perl/CGI on ports 8080 and 8443 (proxy ports). Three distinct
cache zones coexist:

Zone	Typical contents	Default size
Dynamic	PHP/HTML pages	4 GB
CSS / JS	`.css`, `.js` (static)	2 GB
Static / Media	Images, fonts, downloads	2 GB

Each zone is sized and managed independently. WSA also offers a bot
protection layer (AI, scanners, SEO, empty User-Agent), multi-level
rate limiting, and integration with cPanel SSL changes to rebuild
vhosts automatically.

The module follows a three-tier architecture:

/etc/wsa/ — module core (PHP, libraries, configuration,
SQLite database, logs, wsad daemon).
WHM (/usr/local/cpanel/whostmgr/docroot/cgi/wsa/) — global
configuration by the administrator.
cPanel (/usr/local/cpanel/base/frontend/{paper_lantern,jupiter}/wsa/) —
per-account configuration by the end user.

2. Installation

The install procedure is documented separately in
installation-en.md.

Quick reminder:

wget https://static.astralinternet.com/nginx/install/wsa-install && sh wsa-install stable

Followed by a verification in WHM (status banner, cache gauges,
X-Nginx-Cache-Status headers on a test site).

3. WHM interface (administrator)

The WHM interface is the global admin tool for the server. Reach it
via WHM → Plugins → WSA – Cache for cPanel server.

3.1 Home page

The home page gathers five blocks, top-down:

3.1.1 Status banner

Two rows:

Module state: enabled / disabled
Nginx state: running / stopped

Colour code: green (healthy), red (problem).

3.1.2 Action tiles (top row)

Two tiles colour-coded by risk level:

Rebuild Nginx conf (amber) — regenerates every vhost then hot
reloads (no active connection lost). Run this after any WHM or
cPanel configuration change.
Restart Nginx (red) — full process restart. Drops active
connections. Confirms via a dialog. Use only when a reload isn't
enough.

3.1.3 Cache row

Clear Nginx cache (blue tile, left) — empties all three cache
zones. Safe — the next request will repopulate.
Cache usage bars (right) — three progress bars for Dynamic,
CSS / JS, Media.

3.1.4 Bot Protection (24 h statistics)

Panel added in WSA 1.5.0. Shows:

Total blocked — cumulative requests blocked via HTTP 444 over
the last 24 hours
Unique IPs — distinct IPs blocked
Top User-Agent — most aggressive UA (with count)

A collapsible "Top 10 User-Agents" section exposes the full
detail. Statistics are cached for 5 minutes
(/etc/wsa/conf/bot_stats.json) so the WHM page load stays fast.
The panel disappears automatically if the Nginx log
(/var/log/nginx/access.log) is unreadable.

3.1.5 Configuration list

Three links to detailed configuration pages:

Module Configuration — see 3.2
Nginx Configuration — see 3.3
Cache Configuration — see 3.4

3.1.6 Danger zone

Visually separated section (red border) at the bottom of the page.
Contains a single Disable module button (or Enable module if
currently disabled). Clicking it:

Stops Nginx
Reassigns Apache to ports 80 and 443
All sites continue working but without cache

An explicit confirm dialog prevents accidental clicks.

3.2 Module Configuration

Settings specific to the WSA module (not Nginx).

Option	Description
Auto Update	Enables or disables automatic module updates via cron.
Dynamic Cache Size	Maximum on-disk size of the Dynamic zone. Predefined choices (256 MB, 512 MB, 1 GB, 2 GB, 4 GB) or custom value.
CSS / JS Cache Size	Same for the CSS / JS zone.
Media Cache Size	Same for the Media zone (images / fonts / videos).
Release Tier	Update branch: stable, current, edge, dev (if available).

After changes, click Save then Rebuild Nginx conf from the
home page to apply.

3.3 Nginx Configuration

The densest page — it exposes every Nginx directive WSA manages.
Options are grouped by collapsible sections:

General — worker_processes, worker_connections,
worker_rlimit_nofile, keepalive_timeout, client_max_body_size,
sendfile, tcp_nodelay, tcp_nopush, etc.
Rate Limiting — four independent mechanisms:
- Global request rate — global rate per real IP (disabled by
  default; enable with a typical 30 req/s + burst 100 limit).
- Login URI rate — strict rate (5 req/min default) on auth URIs
  (/wp-login.php, /xmlrpc.php, /administrator/,
  /admin.php, /login).
- Concurrent connections / IP — anti-Slowloris (50 simultaneous
  connections per IP by default).
- Concurrent connections / vhost — fairness across sites (1000
  concurrent connections per vhost by default).
- Whitelist — list of trusted IPs / CIDR never counted (CDN,
  monitoring, internal IPs).
Compression — gzip (on by default), gzip_static,
Build & install Brotli button, Enable Brotli checkbox,
compression levels.
Bot Protection — User-Agent blocklists by category:
- AI Crawlers — GPTBot, ClaudeBot, PerplexityBot, Bytespider,
  Anthropic-AI, etc.
- Security Scanners — Nikto, sqlmap, Wfuzz, etc.
- SEO Spiders — AhrefsBot, SemrushBot, MJ12bot, etc.
- Empty User-Agent — blocks requests with no UA at all.
- Custom UA list — free-form list editable by the administrator.
Caching behavior — proxy_cache_path levels,
proxy_cache_key, proxy_cache_use_stale, proxy_cache_lock,
inactive durations.
Other / Misc — miscellaneous directives (open file cache, log
format, DNS resolver, etc.).

Each option shows: label, brief description, default value, and the
appropriate control (text field, On/Off, multiple choice, or list
of values).

Below the main form, a separate sub-form contains the Build &
install Brotli / Uninstall Brotli buttons (rendered outside
the main <form> to avoid accidental submission).

3.4 Cache Configuration

Default cache settings, applied to every site on the server. A
site can override these values via the cPanel interface (Simple or
Advanced mode).

The page is organised by left-side vertical menu:

ALL (default) — all sections shown at once.
Dynamic Files — server TTL, browser TTL, cookie bypass list,
URI bypass list.
CSS / JS Files — server TTL, browser TTL, URI bypass.
Images / Fonts — server TTL, browser TTL, URI bypass.

Each section mirrors the structure of the corresponding tab in
cPanel Advanced mode (see
section 6) — directives are
identical, only the scope changes (global here vs. per-domain in
cPanel).

Important: the Bot Protection section is intentionally absent
from this page — it lives in Nginx Configuration to avoid
duplicating the UI.

4. Per-package activation in WHM

WSA is globally enabled or disabled on the server, but the
visibility of the cPanel interface is controlled individually
through cPanel's Feature Manager — which lets you reserve the WSA
panel for clients on a specific package.

The WSA code internally queries:

whmapi1 get_users_features_settings user=<user> feature=WSA-Website_Accelerator

When the feature is disabled for a client's package, WSA exists
on the server but the user does not see the cPanel icon nor the
Simple/Advanced mode panel.

4.1 Enable the feature for a package

WHM → Packages → Feature Manager.
Either edit an existing Feature List, or create a new one
(button Add a new feature list).
Tick WSA-Website_Accelerator in the list.
Save.
WHM → Packages → Edit a Package, select the package to edit.
Pick the Feature List you prepared in the previous step from
the dropdown.
Save Changes.

All current and future cPanel accounts assigned to this package
will see the WSA panel on their next cPanel login.

4.2 Disable for a package

Follow the same steps but untick WSA-Website_Accelerator in
the Feature List. WSA will continue proxying and caching their
sites — only the user interface is hidden.

4.3 Check a user's status

whmapi1 get_users_features_settings user=<username> feature=WSA-Website_Accelerator

The feature_list_setting field returns 1 (enabled) or 0
(disabled).

5. cPanel interface — Simple mode

Simple mode is the default view when a cPanel user opens the WSA
icon. It is a table with one radio column + one description column,
with mutually exclusive choices.

Choice	Behaviour
Default	Server-wide settings (defined by the admin in WHM → Cache Configuration).
Disable	No cache — every request goes straight to Apache. Useful for debugging.
Cache for 1 month	Long cache durations: suitable for content rarely updated (brochure sites).
Cache for 1 week	Frequency/performance compromise — recommended default for most WordPress / content-driven e-commerce sites.
Cache for 1 day	Short cycle — editorial sites, high-frequency blogs.
Store (e-commerce)	E-commerce preset: long CSS/JS/Media cache, very short dynamic (1 min), cart/checkout/login URIs auto-bypassed.

5.1 Compression indicator

In the top-right corner of the cPanel panel, a coloured dot
(traffic-light style) shows the state of compression codecs:

● Brotli/Gzip — both codecs active (optimal)
● Brotli — Brotli only
● Gzip — gzip only
(empty) — no compression

The indicator is read-only for the user; the setting is managed in
WHM by the administrator.

5.2 Switch to Advance mode button

At the bottom of the Simple panel, a button switches the user to
Advanced mode. Use it when the
client needs per-domain/subdomain settings or wants to fine-tune
TTLs individually.

5.3 Clear my cache button

Empties only the caches associated with the current user's domains
(not other accounts'). Safe — the next request repopulates.

6. cPanel interface — Advanced mode

Advanced mode allows configuration per domain and per subdomain.
Each entry in the user's domain list is editable separately.

6.1 Selecting a domain / subdomain

When entering Advanced mode, the user sees a list of all their
domains and subdomains. For each, two actions:

Edit — opens the configuration popup window (5 tabs, see
below).
Use server default — removes any customisation and reuses
global WHM defaults.

Subdomains inherit from the parent domain by default; editing a
subdomain creates a local exception visible in the list.

6.2 Basic tab

Selected by default when the popup opens. Four checkboxes (enable /
disable):

Option	Effect on HTTP response headers
Show "Powered By" header	Adds `X-Server-Powered-By: Nginx for WHM/cPanel by Astral Internet`.
Show Cache Status header	Adds `X-Nginx-Cache-Status: HIT/MISS/BYPASS/EXPIRED`. Very useful for debugging.
Add XSS Protection header	Adds `X-XSS-Protection: 1; mode=block` (always, on every response).
Add Content-Type Options header	Adds `X-Content-Type-Options: nosniff` (anti-MIME-sniffing).

6.3 Bot Protection tab

Lets you override server settings per domain. Each category is a
tri-state selector:

State	Effect
Server default	Inherits the global WHM setting (recommended).
Blocked	Forces blocking for this domain, even if disabled globally.
Allowed	Forces allowing for this domain, even if blocked globally.

Four bot categories:

AI Crawlers — GPTBot, ClaudeBot, PerplexityBot, Bytespider, etc.
Security Scanners — Nikto, sqlmap, Wfuzz, etc.
SEO Spiders — AhrefsBot, SemrushBot, MJ12bot, etc.
Empty User-Agent — requests with no User-Agent header.

Use case: a client publishes an API meant to be consumed by an
AI agent — flip AI Crawlers to Allowed for that domain only,
without loosening the server-wide policy.

6.4 Dynamic tab

Cache rules for dynamic content (generated HTML, JSON, APIs).
Includes a master Activate dynamic caching switch. If off, none of
the sub-options below apply.

Option	Description
Bypass Cache-Control header	Ignore `Cache-Control` / `Expires` directives sent by the application (useful against CMSes that force `no-cache`).
Server cache TTL	Duration Nginx keeps the response cached (numeric field + unit s/m/h/d/w/M).
Browser cache TTL	Value sent to the browser via `Expires` / `Cache-Control`.
Cookie bypass list	List of cookie names (one per line, add via + button); any request carrying one of these cookies bypasses the cache. Example: `wordpress_logged_in`, `woocommerce_cart_hash`.
URI bypass list	List of regex patterns (one per line); URIs that match bypass the cache. Example: `/wp-admin`, `/checkout`, `/cart`.

6.5 CSS / JS tab

Cache rules for .css and .js files. Same controls as the
previous tab, simpler:

Option	Description
Activate CSS/JS caching	Master switch for the tab.
Server cache TTL	Nginx TTL (typically longer than dynamic: 1 month).
Browser cache TTL	Browser TTL.
URI bypass list	URIs to exclude (rare for CSS/JS, useful for unversioned dev builds).

6.6 Images & Fonts tab

Cache rules for images, fonts, downloadable files. Same controls as
CSS / JS. Default TTLs are the longest (1 month → 1 year typically)
because these files rarely change and their version is usually
encoded into the URL.

Option	Description
Activate media caching	Master switch.
Server cache TTL	Nginx TTL.
Browser cache TTL	Browser TTL.
URI bypass list	URIs to exclude.

6.7 Save

Save button at the bottom of the popup. Changes are written to
the SQLite database (/etc/wsa/conf/wsa.sqlite) then the rebuild
hook regenerates the Nginx config for the affected domain. The
result is visible within a few seconds.

7. Command line

WSA exposes a complete CLI to automate its operations (Ansible,
cron, deployment scripts). The utility is installed at
/etc/wsa/wsa.

Important: in some environments the executable bit may be
missing (hardening, restorecon, etc.). The recommended form is
/etc/wsa/./wsa <flags> or, if that fails, the explicit PHP
invocation:
/usr/local/cpanel/3rdparty/bin/php /etc/wsa/wsa <flags>.

7.1 Help and version

/etc/wsa/./wsa --help        # Full help text
/etc/wsa/./wsa --version     # Installed version number
/etc/wsa/./wsa -h            # Short form of --help
/etc/wsa/./wsa -v            # Short form of --version

7.2 Cache management

Command	Effect
`--purgecache-all`	Empties all three cache zones.
`--purgecache-user=<user>`	Empties cache for a cPanel user.
`--purgecache-domain=<domain> --user=<user>`	Empties cache for a specific domain. `--user` is required.
`--purgecache-url=<url>`	Empties a specific URL. URL must start with `http://` or `https://`.
`--update-disk-usage`	Recalculates cache sizes and updates the WHM gauges.

/etc/wsa/./wsa --purgecache-url=https://example.com/article/123
/etc/wsa/./wsa --purgecache-user=clienta --verbose

7.3 Nginx configuration management

Command	Effect
`--rebuild`	Regenerates only modified vhosts (fast).
`--rebuild-user=<user>`	Regenerates a single cPanel user.
`--rebuild-forced`	Regenerates everything (slow — use after a WHM Cache Configuration change).
`--reload-nginx`	Hot reload without dropping connections.
`--restart-nginx`	Full restart (drops active connections).
`--check-httpd-conf`	Verifies whether Apache changed since the last rebuild.

7.4 Module enable / disable

/etc/wsa/./wsa --enable      # Enables WSA (Nginx takes ports 80/443)
/etc/wsa/./wsa --disable     # Disables WSA (Apache reclaims 80/443)
/etc/wsa/./wsa --update      # Updates the module via the configured branch
/etc/wsa/./wsa --check-wsad  # Verifies + restarts the wsad daemon if needed

7.5 Additional Nginx modules (Brotli, etc.)

All these flags accept a module name argument (e.g. =brotli).

Command	Effect	Exit code
`--nginx-list`	Lists supported modules.	0
`--nginx-status=<mod>`	JSON status (installed, static, enabled, version).	0 / 1
`--nginx-caninstall=<mod>`	Verifies prerequisites.	0 if yes
`--nginx-isinstalled=<mod>`	Is the module installed?	0 if yes
`--nginx-isstatic=<mod>`	Is the module statically compiled in Nginx?	0 if yes
`--nginx-isenabled=<mod>`	Is the SQLite flag set?	0 if yes
`--nginx-install=<mod>`	Compiles and installs the module. Combine with `--force` to recompile.	0 if success
`--nginx-uninstall=<mod>`	Removes the `.so` files.	0 if success
`--nginx-enable=<mod>`	Enables directives in `nginx.conf`.	0 if success
`--nginx-disable=<mod>`	Disables directives.	0 if success

# Complete Brotli workflow
/etc/wsa/./wsa --nginx-caninstall=brotli && \
  /etc/wsa/./wsa --nginx-install=brotli --verbose && \
  /etc/wsa/./wsa --nginx-enable=brotli && \
  /etc/wsa/./wsa --rebuild-forced

7.6 Global flags

Flag	Effect
`--verbose`	Prints details for every step (very useful for debugging).
`--user=<user>`	Specifies the target cPanel user (required with `--purgecache-domain`).
`--force`	Forces recompilation with `--nginx-install` even if up to date.

7.7 Standard exit codes

Code	Meaning
0	Success / yes / module installed / enabled
1	Failure / no / module absent / disabled
2+	Specific errors (see `/var/log/wsa/wsa.log`)

Designed to integrate naturally into shell scripts:

if /etc/wsa/./wsa --nginx-isinstalled=brotli; then
    echo "Brotli is already installed"
else
    /etc/wsa/./wsa --nginx-install=brotli --verbose
fi

8. WordPress plugin (generic)

The official "Cache Purge for Website Accelerator" extension
lets WordPress notify WSA every time a piece of content is modified,
so the cached version held by Nginx is immediately replaced by the
new one.

8.1 Installation

In WordPress: Plugins → Add New.
Search for "Cache Purge for Website Accelerator".
Click Install Now then Activate.

8.2 Configuration

The plugin works without configuration: it detects WSA via the
X-Server-Powered-By header and issues a CLI call to
--purgecache-url= on every WordPress content-change event:

Publishing or updating a post / page
Menu modification
Widget modification
Plugin enable / disable
Theme change
WooCommerce product create / update

8.3 Verification

Modify a post then reload the page from the visitor side. In the
response headers, X-Nginx-Cache-Status should switch to MISS
(cached version was purged) then HIT on the next reload.

9. PHP class (generic)

For developers who want to integrate cache purging into a non-
WordPress PHP project (custom CMS, Laravel/Symfony framework,
migration script, etc.), Astral Internet provides a royalty-free
PHP class.

9.1 Download

The class is distributed on the Astral Internet website
(astralinternet.com/cache-pour-serveur-cpanel)
under the Extensions → PHP class section.

9.2 Typical usage

require_once 'wsa_cache_purge.php';

$wsa = new WSA_Cache_Purge();

// Purge a URL after updating an article
$result = $wsa->purgeUrl('https://example.com/article/12345');

if ($result['success']) {
    error_log("Purged: {$result['deleted']} file(s) out of {$result['tried']} variants");
} else {
    error_log("Purge failed: {$result['msg']}");
}

9.3 Main methods

Method	Description
`purgeUrl(string $url): array`	Purges a specific URL. URL must be absolute (`https://...`).
`purgeDomain(string $domain, string $user): bool`	Purges an entire domain.
`purgeUser(string $user): bool`	Purges all domains for a cPanel user.
`purgeAll(): bool`	Total purge (root only).

9.4 Cache key variants

Every purgeUrl() call handles 8 possible variants:

2 schemes (http / https)
2 HTTP methods (GET / HEAD)
2 mobile flavours (desktop / mobile)

→ A single call therefore purges every cached version of one URL,
without the integrator having to worry about variants.

9.5 Notes

The class needs to be invoked through PHP-FPM or CLI under an
account that can write to /var/cache/nginx/wsa_* (typically
nobody or the cPanel user owning the site).
For multi-tenant use, prefer --purgecache-url= via
shell_exec() rather than instantiating the class directly —
this routes through the WSA CLI which validates permissions.

Document updated for WSA 1.5.8 — April 2026.
For anything not covered here: support@astralinternet.com.