LiteSpeed’s built-in cache module — LSCache — stores full HTTP responses at the web server layer, meaning a cache hit never touches PHP, your database, or any application code. For WordPress operators on cPanel/WHM or bare OpenLiteSpeed this changes the performance ceiling entirely: a warm page is served in under a millisecond from disk, regardless of how expensive the underlying PHP render is. This article explains how the module works mechanically so you can make informed decisions about purge rules, ESI configuration, and plugin interaction.
How to verify
Check that the LSCache module is loaded and that a response is actually being cached:
# LiteSpeed Enterprise (cPanel)
/usr/local/lsws/bin/lshttpd -v 2>&1 | head -4
# OpenLiteSpeed
/usr/local/lsws/bin/lswsctrl status
# First request (miss), second request (hit)
curl -sI https://example.com/ | grep -i x-litespeed-cache
# X-LiteSpeed-Cache: miss
curl -sI https://example.com/ | grep -i x-litespeed-cache
# X-LiteSpeed-Cache: hit
# Where cache files live (default storage path)
ls -lh /tmp/lscache/example.com/ 2>/dev/null || \
ls -lh /var/www/example.com/cache/ 2>/dev/null
# Cache control headers the app is setting
curl -sI https://example.com/ | grep -iE 'cache-control|x-litespeed'
If X-LiteSpeed-Cache is absent entirely, the module is either not loaded or the application is sending no-store / private cache-control directives that instruct LSCache to skip storage.
What’s happening
LSCache is not a reverse proxy bolted in front of your server. It is a native module compiled into the LiteSpeed binary itself, running in the same process as the HTTP engine. When a cacheable response arrives from your application (PHP via LSAPI, or any backend), LSCache serialises the response headers and body to a configurable storage path on disk. On the next matching request, the module intercepts the request before it is dispatched to LSAPI, reads the cached file, and streams it directly to the client. The PHP interpreter is never invoked.
The module determines whether a response is cacheable by reading two header families. First, standard HTTP cache-control semantics: responses with Cache-Control: no-store, private, or a Set-Cookie header that the module is not configured to ignore will not be cached. Second, LiteSpeed-specific X-LiteSpeed-Cache-Control headers set by the application (or by the LSCache for WordPress plugin), which override the standard headers and provide tag-based metadata used for targeted purges. The tags — arbitrary strings like post_1234, term_12, url_/shop/ — are stored alongside the cached file and allow a single API call to purge exactly the pages that contain a given piece of content.
Cache entries are stored in a flat-file layout under the configured storagePath. Each file is named by a hash of the request URI, scheme, and cache-control vary keys (typically Accept-Encoding, Cookie presence, and user-agent class for mobile/desktop splitting). The module supports stale-while-revalidate semantics: when a cached entry expires, the first request that arrives triggers a background revalidation fetch while still serving the stale file to the client. This means cache expiry events have no latency impact on users when configured correctly.
The procedure
1. Confirm LSCache is enabled at the server level.
On cPanel/WHM, navigate to WHM > LiteSpeed Web Server > Manage > Tuning and verify that Enable Cache is set to Yes. On OpenLiteSpeed, check your httpd_config.conf for the module block:
module cache {
ls_enabled 1
}
2. Enable the module at the virtual host level.
In your vhost configuration file (/usr/local/lsws/conf/vhosts/<domain>/vhconf.conf):
module cache {
ls_enabled 1
storagePath /var/www/example.com/cache
checkPrivateCache 1
checkPublicCache 1
maxCacheObjSize 10000000
maxStaleAge 6000
}
maxCacheObjSize is in bytes (10 MB here). maxStaleAge is in seconds and controls the stale-while-revalidate window.
3. Install and activate the LSCache application plugin.
For WordPress, install the official LiteSpeed Cache plugin (LSCWP). It sets X-LiteSpeed-Cache-Control: public,max-age=604800 on cacheable pages and no-cache on cart, checkout, and logged-in sessions. Without the plugin, LSCache will only cache responses that carry standard public cache-control headers — uncommon in WordPress without intervention.
4. Verify cache hit headers on production.
for i in 1 2 3; do
curl -s -o /dev/null -w "Request $i: %{http_code} - " https://example.com/
curl -sI https://example.com/ | grep -i x-litespeed-cache
done
The first request shows miss, subsequent requests show hit. If you see miss on every request, enable LiteSpeed’s cache debug log temporarily:
# In httpd_config.conf or vhconf.conf
debugLevel 10
Then tail /usr/local/lsws/logs/error.log and look for LS_CC_REASON entries that explain why each response was not stored.
5. Set an appropriate max-age.
The LSCWP plugin defaults to 604800 seconds (7 days). For sites with frequent content updates, 3600–86400 is more appropriate. Configure it under LSCWP > Cache > TTL or by setting X-LiteSpeed-Cache-Control: public,max-age=86400 in your application headers.
Common pitfalls
Cookies bypass the cache by default. Any request that carries a cookie LSCache does not recognise as ignorable will be treated as a private session and will not be served from cache. The LSCWP plugin handles common WordPress cookies (wordpress_logged_in_*, woocommerce_*), but custom plugins that set their own cookies will break caching unless you add those cookie names to the ignore list in LSCWP > Cache > Excludes.
The cache is per-listener, not global. If you run both HTTP and HTTPS listeners, the cache storage path must be shared, or you will have two independent caches with independent hit rates. The default configuration in LSCWP handles this, but a manual vhost config may not.
Cache-Control: no-store from upstream plugins overrides LSCache. Some security or session plugins emit no-store on every response. You will see X-LiteSpeed-Cache: miss on every request. Audit with curl -sI | grep cache-control and identify the source before adding blanket ignore rules.
Mobile/desktop cache split doubles your cache storage. LSCache can split cache entries by detected device class (mobile vs. desktop). This is useful but doubles storage and halves effective hit rates on mixed-traffic sites. Disable it if your theme is fully responsive and you do not serve a separate mobile site.
The cache module must be loaded at server start. Enabling or disabling the module requires a graceful restart of LiteSpeed (/usr/local/lsws/bin/lswsctrl restart), not a config reload. A reload alone will not pick up changes to the module’s enabled state.
For production LSCache tuning across a WordPress estate — purge rules, ESI fragments, WooCommerce cart exclusions — Stack Harbor’s managed operations handles the full cache lifecycle as part of the environment management service.