System Config Page

After installation, start here: Stores > Configuration. This is where you tell Magento to use LiteMage, and then give LiteMage some basic instructions.

System Tab

!System Config, System Tab

Magento has a built-in full page cache, so if you want to use LiteMage, you need to change the default. In the Full Page Cache section of the System tab, next to Caching Application, make sure Use system value is unchecked, and then choose LiteMage Cache Built in to LiteSpeed Server from the drop-down.

You can change how quickly content expires, if you wish. Under TTL for public content, uncheck Use system value, and enter your preferred TTL in seconds.

Press the Save Config button when you finish making changes.

LiteMage Cache Tab

General Settings

!System Config, LiteMage Tab

By default, LiteMage does not cache if there's a context vary change in the response. Context Vary Bypass allows you to override this behavior for global, cacheable contexts. List the context variables here in a comma-delimited string, and LiteMage will cache them despite any changes.

Enable Custom Vary controls whether to allow customized varies (for example, different currencies based on GeoIP). And if it is allowed, you must choose how to handle a customer's first visit. Is it more important that they are served from cache for that visit? Or is it more important that the value of the context variable is evaluated immediately?

  • No does not enable custom vary.
  • Yes and allow guest mode for first visit ensures that the customer gets a fully-cached version of the page on the first visit. However, the content served will be based on the view of a non-logged-in guest and will not take the value of the custom vary into account until the customer loads the next page.
  • Yes and enforce vary checking on first visit will show the customer the correct content for the custom vary, but the customer will not be served from cache until their next page load.

Developer Settings

!System Config, LiteMage Tab

You can enable debug mode, if you are trying to troubleshoot a problem. There are three options in the Enable Debug setting: No, which is the default setting; Yes; and Yes and set X-LiteMage-Debug response headers. You can learn more about what this last setting does for you in our Troubleshooting Guide.

Cache Management Page

!Cache Management

The Cache Management page (System > Cache Management) is where you enable page cache so LiteMage can work. It's also the place where you can flush the cache, and keep an eye on your LiteMage plan usage.

Enable Page Cache

If Page Cache does not have a green Enabled indicator in the Status column, then you will need to enable it. Click the checkbox next to Page Cache, select Enable from the dropdown box at the top of the table, and press Submit. LiteMage Cache will then be enabled.

You can disable LiteMage in the same manner, except you would choose Disable from the drop-down list.

Flush LiteMage Cache

The Flush Magento Cache button at the top flushes all of the enabled caches on the Cache Type list, including Page Cache, aka LiteMage.

To flush only LiteMage, click the checkbox next to Page Cache, select Refresh from the dropdown box at the top of the table, and press Submit. LiteMage Cache will then be flushed.

Check LiteMage Usage

Here's what each field of the usage chart indicates:

  • Current LiteMage Plan: Your current plan, which would be LiteMage Starter, LiteMage Standard, or LiteMage Unlimited.
  • Public Cache Hits: Number of requests that hit public cache since the last Flush All. This number should not be 0.
  • LiteMage Cached Objects: Current publicly cached object count. There should be more than 0 of these.
  • Not Cached (Limited by Plan): Number of requests not served from cache due to plan limitations. You can upgrade your LiteMage plan if this value is not 0. If your store's number of cached objects hasn't reached the limit yet, it will show 0. This is fine. It means your store is in good shape and does not require more caching than your plan can handle.

Cache Warmup

The LiteMage 2 cache crawler travels through your site, refreshing pages that have expired in the cache. This makes it less likely that your visitors will encounter un-cached pages.

Before You Begin

  1. Install and enable LiteMage Cache for Magento2
  2. Crawler Engine: The crawler must be enabled at the server level, or you will see the warning message Server crawler engine not enabled. Please check..... If you are using a shared hosting server, please contact your hosting provider, or see our instructions.
  3. SiteMap: Prepare your site's sitemap, e.g.

How to Use the Crawler Script

  • Download it from here
  • Change the permissions so that the file is executable: chmod +x
  • Run the script: bash SITE-MAP-URL

More Options

  • -h, --help: Show this message and exit.
  • -m, --with-mobile: Crawl mobile view in addition to default view.
  • -c, --with-cookie: Crawl with site's cookies.
  • -b, --black-list: Page will be added to blacklist if HTML status error and no cache. Next run will bypass page.
  • -g, --general-ua: Use general user-agent instead of lscache_runner for desktop view.
  • -i, --interval: Change request interval. -i 0.2 changes from default 0.1 second to 0.2 seconds.
  • -v, --verbose: Show complete response header under /tmp/crawler.log.
  • -d, --debug-url: Test one URL directly. as in sh -v -d
  • -qs,--crawl-qs: Crawl sitemap, including URLS with query strings.
  • -r, --report: Display total count of crawl result.

Example commands:

  • To get help: bash -h
  • To change default interval request from 0.1s to custom NUM value: bash SITE-MAP-URL -i NUM
  • To crawl with cookie set: bash -c SITE-MAP-URL
  • To store log in /tmp/crawler.log: bash -v SITE-MAP-URL
  • To debug one URL and output on screen: bash -d SITE-URL
  • To display total count of crawl result: bash -r SITE-MAP-URL


Using multiple parameters at the same time is allowed

How to Generate a Sitemap

Magento 2 has a built in module for generating a sitemap and it's fast.

Enable sitemap

Navigate to Magento Admin > Stores > Settings > Configuration > Catalog > XML Sitemap


Set Generation Settings > Enabled to Yes


Configuring a Single Sitemap for All Storefronts

Navigate to Magento Admin > Marketing > Seo & Search > Sitemap

  1. Click the Add Sitemap button
  2. Enter values
    • Filename: sitemap.xml
    • Path: /
  3. Click the Save & Generate button


If all went well, a sitemap.xml file will have been generated in your Magento 2 document root.

Crawl Interval

How often do you want to re-initiate the crawling process? This depends on how long it takes to crawl your site and what you set for Public Cache TTL.

The default TTL is one day(24hr). Maybe, for example, you'd like to run the script by cronjob every 12 hours instead.


This will run twice a day, at 3:30am/15:30: 30 3/15 * * * path_to_script/ SITE-MAP-URL -m -i 0.2


You can also use an online crontab tool to help you to verify the time settings.

Run Crawler After any Product Update on Magento 2

In Magento 2, by design, all cached are purged upon any product updates. LiteMage doesn't have any control over this behavior. Therefore, you may find pages uncached even if you have set your crawl interval less than the site TTL. It doesn't mean LiteMage 2 doesn't work well or that the Crawler doesn't work well. It is simply a Magento 2 design matter.

To avoid the above situation, we would recommend you schedule a specific window of time to do any product changes through Magento admin. For example, two hours from 6:00pm to 8:00pm off-peak time. Then, run the crawler immediately after the change. With this workflow, the likelihood of users encountering uncached pages is kept to a minimum.

How to Verify the Crawler is Working

When using the browser developer tool, load a previously uncached page. You should see X-LiteSpeed-Cache: hit,litemage on the first view.


Last update: September 5, 2020