LiteSpeed Web Cache Developer’s guide

Cache objects are primarily identified by URI, this includes both URL and QUERY_STRING.

This cache is shared by all users.

This cache stores objects for individual clients.

You may need to save different variations of the same URL. Traditionally, this is set by a “Vary” header, for “transfer-encoding”. This is not enough for current web applications, so we expand it with LiteSpeed-specific response headers and rewrite rule environment variables.

This can be used to store multiple cache copies based on User-Agent (desktop/mobile view), multi-language, multi-user classifications (registered vs guest), visitor geographic information, etc.

Each cache object is saved as one file under hashed directories. Cache objects are identified by a Cache Key which has the following components:

• HOST
• URI
• QUERY_STRING
• Client IP
• Session Cookies
• Vary String

For a public cache object, the key is: HOST, URI, QUERY_STRING, and optionally a Vary String

For a private cache object, the key is: HOST, URI, QUERY_STRING, IP, Session Cookies, and optionally a Vary String

The Vary String can be set directly via a rewrite rule or fetched from a special cookie value.

Works similarly to the regular “Cache-control” header, but is for internal use. LiteSpeed Web Server will follow this if it is set, regardless of the value of the “Cache-control” header. Possible values are:

• “no-cache”
• “no-store”
• “max-age”
• “max-stale”
• “public”
• “private”
• “s-maxage”
• “no-vary”
• “esi”

Use the following header to turn on ESI for a specific response:
X-LiteSpeed-Cache-Control: esi=on

To cache a response for an hour:
X-LiteSpeed-Cache-Control: public, max-age=3600

Tell LiteSpeed Web Server to purge cache objects, it can purge by URL, or by Tag.

Purge all public cache:
X-LiteSpeed-Purge: *

Purge all private cache for the current user:
X-LiteSpeed-Purge: private, *

Purge public cache by Tag:
X-LiteSpeed-Purge: tag=Cat1, tag=Page2

Purge private cache by Tag:
X-LiteSpeed-Purge: private, tag=Cat1, tag=Page2

Purge by URL: Currently, only URLs that exactly match are supported
X-LiteSpeed-Purge: /phpinfo.php
X-LiteSpeed-Purge: private, /phpinfo.php

As of now, this does not support regular expressions or wildcards in the Tag and URL, these will be added later.

Assign a tag to a cache object. Each object can have multiple tags assigned to it.
X-LiteSpeed-Tag: Cat1, Page3

Tags are saved together with the cache object.

The main purpose of tagging is to purge cache objects by tag.

Set the cache vary value for the current response:
X-LiteSpeed-Vary: value=US

This tells the server to cache the object with a vary value of “US”.

By default, the cached object cannot be reached as the vary value is not set, to retrieve it for a request, you can use the following rewrite rule:
RewriteRule /us/view - [E=cache-control:vary=US]

Register a list of vary cookies for the current response:
X-LiteSpeed-Vary: cookie=cookie1,cookie=cookie2

The server needs to track vary cookies for each individual URL saved in cache manager storage, this is expensive and should be avoided whenever possible.

The rewrite rule method is preferred as it does not need to save for every URL.

Generally speaking, cookies will contain private information, so by default, all pages that are cached in LiteSpeed Cache will have the ‘Set-Cookie’ header dropped. The lsc-cookie header is used to send out a ‘Set-Cookie’ header for the pages served from cache. The lsc-cookie header follows the same syntax as a Set-Cookie header, but will be sent to the client along with the cached page.

In other words, the lsc-cookie is a cacheable Set-Cookie which will be converted and sent out as a Set-Cookie.

For example, if I have <?php header(‘LSC-Cookie: lsc_cached_page=1’); ?> in my plugin, when the page is served from cache, the response header will include Set-Cookie: lsc_cached_page=1.

One example of how to use this is to check if the client supports cookies. If the web application always generates a cookie on every page and a page is served from the cache without any cookies, the web application may assume that the client does not have cookies enabled.

This header is inserted by Litespeed Web Server when it serves from cache, possible values are:
X-LiteSpeed-Cache: hit
X-LiteSpeed-Cache: hit,private
X-LiteSpeed-Cache: hit,litemage

This cookie is always added as part of the cache key, unless the “no-vary” cache-control is set in the response header X-litespeed-cache-control: no-vary.

Control cache behavior by setting environment variables.

Syntax:

RewriteRule url1 - [E=cache-control:value1,E=cache-control:value2]
RewriteRule url2 - [E=cache-vary:value1,E=cache-control:value2]

Environment variables can have the following keys
cache-control/cache-ctrl

Regular cache-control directives:
RewriteRule .* - [E=cache-control:max-age=300]
RewriteRule .* - [E=cache-control:private,max-age=300]

Flush private cache:
RewriteRule /flush_cache - [E=cache-control:flush]
You cannot flush the public cache through rewrite rules.

Append a vary string to a cache object key directly:
RewriteRule url2 - [E=cache-control:vary=vary_value]
This directly appends vary_value to a cache key and a CGI environment variable
example: cache-control:vary=ismobile

Cache objects vary based on cookie values, this has the same effect as the X-LiteSpeed-Vary response header, the difference is that it only applies for the current request and it is not persistently associated with that URL.

cache-vary:<cookiename>
For example: cache-vary:isloggedin

Examples:
Cache response for 5 minutes (300 seconds).
RewriteRule .* - [E=cache-control:max-age=300]
RewriteRule HTTP_USER_AGENT mobi [E=cache-control:vary=ismobile]

====
For xenforo and Magento under wp uri paths, use rewrite rules to set different default vary cookies.
For a cookie vary set by a rewrite rule, we will add an Environment variable, like LSCACHE_VARY_COOKIE
This needs to be set via a cache-vary environment variable. E=Cache-Vary:mycookie1 mycookie1 is the name of the cookie.
RewriteRule .? - [E=Cache-Vary:_my_custom_vary]^M
====

ESI
Rewrite Rules can also control the ESI engine for a request. To turn on the ESI engine for a request:
RewriteRule .* - [E=esi_on:1]

To turn off the ESI engine for a request:
RewriteRule .* - [E=esi_on:0]

LiteSpeed’s Apache-style configuration directives must be nested in <IfModule LiteSpeed> and </IfModule> tags. For example:

<IfModule LiteSpeed> 
 CacheEnable public /
 CacheRoot c:/cacheroot
 CacheMaxExpire 604800
</IfModule>

syntax: CacheEnable [cache_type] [url-string]

The CacheEnable directive instructs LiteSpeed Web Server to cache urls at or below url-string. Both public and private caches can be enabled based on the value specified with the cache_type argument.

# Enable public cache
CacheEnable public /

# Enable private cache
CacheEnable private /

syntax: CacheDisable [cache_type] [url-string]

The CacheDisable directive instructs LiteSpeed Web Server to not cache urls at or below url-string. Both public and private caches can be disabled based on the value specified with the cache_type argument.

# Disable public cache
CacheDisable public /

# Disable private cache
CacheDisable private /

syntax: CacheRoot directory

The CacheRoot directive defines the name of the directory on the disk to contain cache files.
CacheRoot c:/cacheroot

syntax: CacheMaxFileSize bytes

The CacheMaxFileSize directive sets the maximum size, in bytes, for an object to be considered for storage in the cache.
CacheMaxFileSize 64000

syntax: CacheIgnoreCacheControl On|Off

Ordinarily, requests containing a Cache-Control: no-cache or Pragma: no-cache header value will not be served from the cache. The CacheIgnoreCacheControl directive allows this behavior to be overridden. CacheIgnoreCacheControl On tells the server to attempt to serve the resource from the cache even if the request contains no-cache header values. Resources requiring authorization will never be cached.
CacheIgnoreCacheControl On

Warning:
This directive will allow serving from the cache even if the client has requested that 
the document not be served from the cache. This might result in stale content being served.

syntax: CacheMaxExpire seconds

The CacheMaxExpire directive specifies the maximum number of seconds for which cacheable HTTP documents will be retained without checking the origin server. Thus, documents will be out of date at most this number of seconds. This maximum value is enforced even if an expiry date was supplied with the document.
CacheMaxExpire 604800

syntax: CacheLookup public on|off

The CacheLookup directive instructs LiteSpeed Web Server on whether or not to check public cache. Typically, on a web server level, you want to set this off with the following directive:
CacheLookup public off

And then turn it on at a per-site basis with the following directive:

CacheLookup public on

Add cache vary based on User-Agent string to save to and serve from the correct cache copy.

Add cache vary for logged in users, but only cache non-logged in users.

https://www.litespeedtech.com/support/wiki/doku.php/litespeed_wiki:cache:lscache:geoip-support

LSCache supports GEOIP. To enable it, the following steps need to be followed:

1. Enable the Geolocation database:
   In the LSWS Web Console: General →General settings:→ Enable IP GeoLocation → Yes
2. Install the GeoIP database (for CentOS users):
   yum install Geoip-data
   or
   yum install GeoIP-GeoLite-data
   
   Also check the installation location
   rpm -ql Geoip-data
   or
   rpm -ql GeoIP-GeoLite-data
   
   It may return the database path as:
   /usr/share/GeoIP/GeoIP.dat
   
   In the LSWS Admin Console, configure the database location: General →General settings:→ IP to GeoLocation DB ( enter the database path ).
3. Install other modules:
   yum install GeoIP GeoIP-devel zlib-devel
4. Enable GeoIP on Apache Conf Config the same way you do in Apache, by placing the following directive:
   GeoIPEnable On
5. Use rewrite rules to control redirects:
   For example, add the following rewrite rules to your .htaccess file:
   

   <IfModule LiteSpeed>
     RewriteEngine on
     RewriteRule .* - [E=Cache-Control:vary=%{ENV:GEO_COUNTRY}]
   </IfModule>

You can add rewrite conditions for more specific rules. For example: Show different content or currencies for UK, EU, US, and the rest of the world.

You can also refer to this Maxmind page for rewrite examples.