Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision 		Previous revision
litespeed_wiki:cache:developer_guide [2016/05/16 16:18]
Rob Holda [CacheRoot] 		litespeed_wiki:cache:developer_guide [2020/07/31 19:38] (current)
Lisa Clarke Redirect to new Documentation Site
Line 1: Line 1:
-====== LiteSpeed Web Cache Developer’s guide ====== +~~REDIRECT>​https://​docs.litespeedtech.com/​lscache/​devguide/overview/~~
- +
-===== Concepts ===== +
-==== cache objects ==== +
-Cache objects are primarily identified by URI, this includes both URL and QUERY_STRING. +
-==== public cache ==== +
-This cache is shared by all users. +
-==== private cache ==== +
-This cache stores objects for individual clients.  +
-==== cache vary ==== +
-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.  +
- +
-===== How cache objects are stored ===== +
-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.  +
- +
- +
-===== Response Headers ===== +
-==== X-Litespeed-Cache-Control ====  +
- +
-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''​ +
- +
-==== X-LiteSpeed-Purge ==== +
-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. +
- +
-==== X-LiteSpeed-Tag ====  +
-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.  +
- +
-==== X-LiteSpeed-Vary ==== +
-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.   +
- +
-==== lsc-cookie ==== +
-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. +
- +
-==== X-LiteSpeed-Cache ==== +
-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''​ \\ +
- +
-===== Special Cookies ===== +
-==== _lscache_vary ==== +
-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''​. +
- +
-===== Rewrite Rules ===== +
-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-Vary ==== +
-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]''​ +
-  +
-===== Apache configuration directives ===== +
-LiteSpeed’s Apache-style configuration directives must be nested in ''<​IfModule LiteSpeed>''​ and ''</​IfModule>''​ tags. For example: +
- +
-<​code>​ +
-<​IfModule LiteSpeed>​  +
- ​CacheEnable public / +
- ​CacheRoot c:/​cacheroot +
- ​CacheMaxExpire 604800 +
-</​IfModule>​ +
-</​code>​ +
- +
-==== CacheEnable ==== +
-**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. \\ +
-<​code>​ +
-# Enable public cache +
-CacheEnable public / +
-</​code>​ +
-<​code>​ +
-# Enable private cache +
-CacheEnable private / +
-</​code>​ +
- +
-==== CacheDisable ==== +
-**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. \\ +
-<​code>​ +
-# Disable public cache +
-CacheDisable public / +
-</​code>​ +
-<​code>​ +
-# Disable private cache +
-CacheDisable private / +
-</​code>​ +
- +
-==== CacheRoot ==== +
-**syntax:** ''​CacheRoot directory''​ \\ \\ +
-The ''​CacheRoot''​ directive defines the name of the directory on the disk to contain cache files. \\ +
-''​CacheRoot c:/​cacheroot''​ +
- +
-==== CacheMaxFileSize ==== +
-**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''​ +
- +
-==== CacheIgnoreCacheControl ==== +
-**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''​ \\ +
- +
-<​code>​ +
-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. +
-</​code>​ +
- +
-==== CacheMaxExpire ==== +
-**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''​ +
- +
-==== CacheLookup ==== +
-**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''​ \\ \\ +
- +
-===== Use cases ===== +
-==== Cache separate views for desktop/​mobile users ==== +
-Add cache vary based on User-Agent string to save to and serve from the correct cache copy.  +
- +
-==== Cache only for guest visitors ==== +
-Add cache vary for logged in users, but only cache non-logged in users.  +
- +
-==== How to enable geolocation for LSCache ==== +
-[[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: +
-  - Enable the Geolocation database: \\ In the LSWS Web Console: General →General settings:​→ [[https://www.litespeedtech.com/docs/​webserver/​config/​general#​enableIpGeo | Enable IP GeoLocation]] → Yes +
-  - 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:​→ [[https://​www.litespeedtech.com/​docs/​webserver/​config/​general#​geolocationDB|IP to GeoLocation DB]] ( enter the database path ). +
-  - Install other modules: \\ ''​yum install GeoIP GeoIP-devel zlib-devel''​ +
-  - Enable GeoIP on Apache Conf Config the same way you do in Apache, by placing the following directive: \\ ''​GeoIPEnable On''​ +
-  - Use rewrite rules to control redirects: \\ For example, add the following rewrite rules to your ''​.htaccess''​ file: \\ <​code><​IfModule LiteSpeed>​ +
-  RewriteEngine on +
-  RewriteRule .* - [E=Cache-Control:​vary=%{ENV:​GEO_COUNTRY}] +
-</​IfModule></​code>​ +
- +
-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 [[http://​dev.maxmind.com/​geoip/​legacy/​mod_geoip2/#​Redirecting_a_client_based_on_country|Maxmind]] page for rewrite examples. +
  • Admin
  • Last modified: 2016/05/16 16:18
  • by Rob Holda