Integrated caching

The integrated cache provides in-memory storage on the Citrix ADC appliance and serves Web content to users without requiring a round trip to an origin server. For static content, the integrated cache requires little initial setup. After you enable the integrated cache feature and perform basic setup (for example, determining the amount of Citrix ADC appliance memory the cache is permitted to use), the integrated cache uses built-in policies to store and serve specific types of static content, including simple webpages and image files. You can also configure the integrated cache to store and serve dynamic content that is marked as non-cacheable by Web and application servers (for example, database records and stock quotes).

Note

The term Integrated Cache can be interchangeably used with AppCache; note that from a functionality point of view, both terms mean the same.

When a user issues a new request for this bug report, the Citrix ADC appliance goes to the origin server for updated copies of all the responses that are associated with the report instance. It stores the responses in the content group, and serves them to the user’s browser, which reassembles the report and displays it.

To enable the appliance to find cached objects in a content group, you can configure selectors. The selectors match cached objects against expressions, or you can specify parameters for finding objects in the content group. If you use selectors as recommended by Citrix, configure them first, so that you can specify selectors when you configure content groups. Next, set up any content groups that you want to add, so that they are available when you configure the policies. To complete the initial configuration, create policy banks by binding each policy to a global bind point or a virtual server. Or, you can bind a label that can be called from other policy banks.

Integrated caching can be improved using pre-loading cached object method before they are scheduled to expire. To manage the handling of cached data, you can configure caching-related headers inserted into the responses. The integrated cache can also act as a forward proxy for other cache servers.

Note:

Integrated caching requires some familiarity with HTTP requests and responses. For information about the structure of HTTP data, see Live HTTP Headers at "<http://livehttpheaders.mozdev.org/>."

How integration cache works

The integrated cache monitors HTTP and SQL requests that flow through the Citrix ADC appliance and compares the requests with stored policies. Depending on the outcome, the integrated cache feature either searches the cache for the response or forwards the request to the origin server. For HTTP requests, integrated caching serves as partial content from the cache in response to single byte-range and multi-part byte-range requests.

Cached data is compressed if the client accepts compressed content. You can configure expiration times for a content group, and you can selectively expire entries in a content group.

Data that is served from the integrated cache is a hit, and data served from the origin is a cache miss, as described in the following table.

Transaction Type Specification
Cache Hit Responses that the Citrix ADC appliance serves from the cache, including: Static objects, for example, image files and static webpages, 200 OK pages, 203 Non-Authoritative Response pages, 300 Multiple Choices pages, 301 Moved Permanently pages, 302 Found pages, 304 Not Modified pages, These responses are known as positive responses. The Citrix ADC appliance also caches the following negative responses: 307 Temporary Redirect pages, 403 Forbidden pages, 404 Not Found pages, 410 Gone pages. To further improve performance, you can configure the Citrix ADC appliance to cache more types of content.
Storable Cache Miss For a storable cache miss, the Citrix ADC appliance fetches the response from the origin server, and stores the response in the cache before serving it to the client.
Non-Storable Cache Miss A non-storable cache miss is inappropriate for caching. By default, any response that contains the following status codes is a non-storable cache miss: 201, 202, 204, 205, 206 status codes, All 4xx codes, except 403, 404 and 410, 5xx status codes

Note To integrate dynamic caching with your application infrastructure, use the NITRO API to issue cache commands remotely. For example, you can configure triggers that expire cached responses when a database table is updated.

To ensure the synchronization of cached responses with the data on the origin server, you configure expiration methods. When the Citrix ADC appliance receives a request that matches an expired response, it refreshes the response from the origin server.

Note Citrix recommends that you synchronize the times on the Citrix ADC appliance and one or more back-end servers.

How dynamic cache works

Dynamic caching evaluates HTTP requests and responses based on parameter-value pairs, strings, string patterns, or other data. For example, suppose that a user searches for Bug 31231 in a bug reporting application. The browser sends the following request on the user’s behalf:

GET /mybugreportingsystem/mybugreport.dll?IssuePage&RecordId=31231&Template=view&TableId=1000

Host: mycompany.net

User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.9) Gecko/2008052906 Firefox/3.0

Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8

Accept-Language: en-us,en;q=0.5

. . .

In this example, GET requests for this bug reporting application always contain the following parameters:

  • IssuePage
  • RecordID
  • Template
  • TableId

GET requests do not update or alter the data, so you can configure these parameters in caching policies and selectors, as follows:

  • You configure a caching policy that looks for the string mybugreportingsystem and the GET method in HTTP requests. This policy directs matching requests to a content group for bugs.
  • In the content group for bugs, you configure a hit selector that matches various parameter-value pairs, including IssuePage, RecordID, and so on.

Note

A browser can send multiple GET requests based on one user action. The following is a series of three separate GET requests that a browser issues when a user searches for a bug based on a bug ID.

GET /mybugreportingsystem/mybugreport.dll?IssuePage&RecordId=31231&Template=view&TableId=1000

GET /mybugreportingsystem/mybugreport.dll?IssuePage&Template=viewbtns&RecordId=31231&TableId=1000

GET /mybugreportingsystem/mybugreport.dll?IssuePage&Template=viewbody&RecordId=31231&tableid=1000

To fulfill these requests, multiple responses are sent to the user’s browser, and the webpage that the user sees is an assembly of the responses.

If a user updates a bug report, the corresponding responses in the cache must be refreshed with data from the origin server. The bug reporting application issues HTTP POST requests when a user updates a bug report. In this example, you configure the following to ensure that POST requests trigger invalidation in the cache:

  • A request-time invalidation policy that looks for the string mybugreportingsystem and the POST HTTP request method, and directs matching requests to the content group for bug reports.
  • An invalidation selector for the content group for bug reports that expires cached content based on the RecordID parameter. This parameter appears in all of the responses, so the invalidation selector can expire all relevant items in the cache.

The following excerpt shows a POST request that updates the sample bug report.

POST /mybugreportingsystem/mybugreport.dll?TransitionForm HTTP/1.1\r\n

User-Agent: Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.0) Opera 7.23 [en]\r\n

Host: mybugreportingsystem\r\n

Cookie:ttSearch.134=%23options%3Afalse%23active%23owner%3Afalse%23unowned%3Afalse%23submitter%3Afalse%23incsub%3Atrue;

Cookie2: $Version=1\r\n

. . .

\r\n

ProjectId=2&RecordId=31231&TableId=1000&TransitionId=1&Action=Update&CopyProjectId=0&ReloadForm=0&State=&RecordLockId=49873+issues+in+HTTP&F43. . .

When the Citrix ADC appliance receives this request, it does the following:

  • Matches the request with an invalidation policy.
  • Finds the content group that is named in the policy.
  • Applies the invalidation selector for this content group and expires all responses that match RecordID=31231.

When a user issues a new request for this bug report, the Citrix ADC appliance goes to the origin server for updated copies of all the responses that are associated with the report instance. It stores the responses in the content group, and serves them to the user’s browser, which reassembles the report and displays it.

Configure integrated cache

To use the integrated cache, you must install the license and enable the feature. After you enable the integrated cache, the Citrix ADC® appliance automatically caches static objects as specified by built-in policies and generates statistics on cache behavior. (Built-in policies have an underscore in the initial position of the policy name.)

Even if the built-in policies are adequate for your situation, you might want to modify the global attributes. For example, you might want to modify the amount of Citrix ADC appliance memory allocated to the integrated cache.

If you would like to observe cache operation before changing settings, see “Displaying Cached Objects and Cache Statistics.”

Note: The Citrix ADC cache is an in-memory store that is purged when you restart the appliance.

To install integrated cache license

  • An integrated cache license is required. For information about licenses, see information about obtaining the licenses topic.

  • Obtain a license code from Citrix, go to the command line interface, and log in.

At the command line interface, copy the license file to the /nsconfig/license folder.

  • Reboot the Citrix ADC appliance by using the following command:

reboot

To enable integrated caching: When you enable integrated caching, the Citrix ADC appliance begins caching server responses. If you have not configured any policies or content groups, the built-in policies store cached objects in the Default content group.

At the command prompt, type one of the following commands to enable or disable integrated caching:

enable ns feature IC

To configure global attributes for caching

Global attributes apply to all cached data. You can specify the amount of Citrix ADC memory allocated to the integrated cache, Via header insertion. A criterion for verifying that a cached object must be served. The maximum length of a POST body permitted in the cache, whether to bypass policy evaluation for HTTP GET requests, and an action to take when a policy cannot be evaluated.

The cache memory capacity is limited only by the memory of the hardware appliance. Also, any packet engine (central distribution hub of all incoming TCP requests) in the nCore Citrix ADC appliance is aware of objects cached by other packet engines in the nCore Citrix ADC appliance.

Note: When the default global memory limit is set as 0 and the Integrated Caching (IC) feature is enabled, the appliance does not cache any objects. For caching, you must explicitly configure the global memory limit. However, if you enable “set authentication, authorization, and auditing parameter enableStaticPageCaching” option, there will be some default memory configured in the appliance. This memory is insufficient for caching large Objects and so it is necessary to assign a higher memory limit for IC. You can perform this by configuring the “set cache parameter –memLimit” command. The new setting is applied only after you save the configuration and reboot the appliance.

You can modify the global memory limit configured for caching objects. However, when you update the global memory limit to a value lower than the existing value (for example, from 10 GB to 4 GB), the appliance continues to use the memory limit.

It means that even though the integrated caching limit is configured to some value, the actual limit used can be higher. This excessive memory is however released when the objects are removed from cache.

The output of the show cache parameter command indicates the configured value (memory Usage limit) and the actual value being used (memory usage limit (active value)).

At the command prompt, type:

set cache parameter [-memLimit <MBytes>] [-via <string>] [-verifyUsing <criterion>] [-maxPostLen <positiveInteger>] [-prefetchMaxPending <positiveInteger>] [-enableBypass(YES|NO)] [-undefAction (NOCACHE|RESET)]

To enable integrated caching by using the GUI:

Navigate to System > Settings, click Configure Basic Features, and select Integrated Caching.

To configure global settings for caching by using the GUI:

Navigate to Optimization > Integrated Caching, click Change Cache Settings, and configure the global settings for caching.

To set up built-in content group, pattern set, and policies for Integrated Cache:

The Citrix ADC appliance includes a built-in integrated caching configuration that you can use for caching content. The configuration consists of a content group called ctx_cg_poc, a pattern set called ctx_file_extensions, and a set of integrated cache policies. In the content group ctx_cg_poc, only objects that are 500 KB or smaller are cached. The content is cached for 86000 seconds, and the memory limit for the content group is 512 MB. The pattern set is an indexed array of common extensions for file-type matching.

The following table lists the built-in integrated caching policies. By default, the policies are not bound to any bind point. You must bind the policies to a bind point if you want the Citrix ADC appliance to evaluate traffic against the policies. The policies cache objects in the ctx_cg_poc content group.

Integrated caching policy name Policy rule
_cacheVPNStaticObjects HTTP.REQ.URL.SET_TEXT_MODE(IGNORECASE).CONTAINS_INDEX("ctx_file_extensions").BETWEEN(101,150)
_cacheTCPVPNStaticObjects HTTP.REQ.URL.ENDSWITH(".css")
_cacheOCVPNStaticObjects HTTP.REQ.URL.ENDSWITH(".pdf")
_cacheWFStaticObjects HTTP.REQ.URL.ENDSWITH(".js")
_mayNoCacheReq HTTP.RES.HEADER("Content-Type").CONTAINS("application/x-javascript")
_noCacheRest TRUE

Flush cache configuration

You can flush a cache group, cache groups, or cache object locator. Following are the commands to flush cache objects.

At the command prompt, type:

flush cache contentgroup all

Example

    0x00000089bae000000004 DEFAULT GET  //1.1.1.1:80/html/index.html?name=hello
    0x00000089bae000000005 DEFAULT GET  //1.1.1.1:80/html/index.html?name=hi

    Flush cache contentGroup all
    done

flush cache contentgroup <content group name>

Example

    0x00000089bae000000004 DEFAULT GET  //1.1.1.1:80/html/index.html?name=hello
    0x00000089bae000000005 DEFAULT GET  //1.1.1.1:80/html/index.html?name=hi

    Flush cache ob -| 0x00000089bae000000004
    done

flush cache object (-locator <positive_integer> | (-url <URL> (-host <string> [-port <port>] [-groupName <string>] [-httpMethod ( GET | POST )])))

Example

    0x00000089bae000000006 DEFAULT GET //1.1.1.1:80/html/index.html

    flush cache ob -URL /html/index.html -host 1.1.1.1 -groupName DEFAULT
    done

Flush cache configuration by using the Citrix ADC GUI

Complete the steps given below to configure cache flushing using the Citrix ADC GUI

  1. Navigate to Optimization > Content Groups.
  2. In the Content Groups detailed pane, click Add.
  3. In the Create Cache Content Groups page, set the following parameter under Others tab:
    1. Flush Cache. Select the check box to flush the cache object.
  4. Click Create and Close.

    Flush cache objects

Configure integrated caching for various scenarios

The following section describes the configuration of integrated caching on NetScaler appliance for various scenarios.

Starting from NetScaler 9.2 release, the integrated caching has more memory for caching. The integrated caching memory is only limited by the memory available on the hardware appliance. You can allocate up to 50 percent of the available memory to the integrated caching feature.

To set the memory allocation for the cache by using the CLI

At the command prompt, type:

set cache parameter -memlimit <value>

Note

The default global memory limit for integrated caching is zero. Therefore, even if you enable the integrated caching feature, the NetScaler appliance does not cache any objects until the global memory limit is explicitly set.

The following section instructs you to configure integrated caching on different scenarios.

Note

The memory limit of the NetScaler appliance is identified when the appliance starts. Therefore, any changes to the memory limit require you to restart the appliance to make the changes applicable across the packet engines.

Integrated caching is enabled and cache memory limit is set to non-zero

Consider a scenario, where you start the appliance, the integrated caching feature is enabled and the global memory limit is set to a positive number. The memory you had set earlier is allocated to the integrated caching feature during the boot process. You might want to change the memory limit to another value depending on the available memory on the appliance.

Configuring by using the CLI

  1. Display the cache parameter

    > show cache parameter
            Integrated cache global configuration:
            Memory usage limit: 500 MBytes
            Memory usage limit (active value): 500 MBytes
            Maximum value for Memory usage limit: 843 MBytes
            Via header: NS-CACHE-9.3: 18
            Verify cached object using: HOSTNAME_AND_IP
            Max POST body size to accumulate: 0 bytes
            Current outstanding prefetches: 0
            Max outstanding prefetches: 4294967295
            Treat NOCACHE policies as BYPASS policies: YES
            Global Undef Action: NOCACHE
    
  2. Set a non-zero memory limit

    set cache parameter -memlimit 600
    

Note

The preceding command displays the following warning message: Warning: To use a new Integrated Cache memory limit, save the configuration and restart the NetScaler appliance.

  1. Save the configuration

    save config
    
  2. From the shell prompt, run the following command to verify in the configuration file.

    root@ns# cat /nsconfig/ns.conf | grep memLimit
    
  3. Change the memory limit

    set cache parameter -memLimit 600 -via NS-CACHE-9.3: 18 -verifyUsing HOSTNAME_AND_IP -maxPostLen 0 -enableBypass YES -undefAction NOCACHE
    
  4. Reboot the appliance

    root@ns# reboot
    
  5. Verify the new value for the memory limit

    > show cache parameter
            Integrated cache global configuration:
            Memory usage limit: 600 MBytes
            Memory usage limit (active value): 600 MBytes
            Maximum value for Memory usage limit: 843 MBytes
            Via header: NS-CACHE-9.3: 18
            Verify cached object using: HOSTNAME_AND_IP
            Max POST body size to accumulate: 0 bytes
            Current outstanding prefetches: 0
            Max outstanding prefetches: 4294967295
            Treat NOCACHE policies as BYPASS policies: YES
            Global Undef Action: NOCACHE
    

After all packet engines start successfully, the integrated caching feature negotiates the memory you had configured. If the appliance cannot use the configured memory, then the memory is allocated accordingly. If the available memory is less than the one you allocated, the appliance recommends a lesser number. The integrated caching feature uses same as the active value.

Integrated caching is disabled and cache memory limit is set to non-zero

In this scenario, when you start the appliance, the integrated caching feature is disabled and the global memory limit is set to a positive number. Therefore, no memory is allocated to the integrated caching during the boot process.

Configuring by using the CLI

  1. Display the cache parameter

    > show cache parameter
            Integrated cache global configuration:
            Memory usage limit: 600 MBytes
            Maximum value for Memory usage limit: 843 MBytes
            Via header: NS-CACHE-9.3: 18
            Verify cached object using: HOSTNAME_AND_IP
            Max POST body size to accumulate: 0 bytes
            Current outstanding prefetches: 0
            Max outstanding prefetches: 4294967295
            Treat NOCACHE policies as BYPASS policies: YES
            Global Undef Action: NOCACHE
    
  2. Set a new memory limit

    set cache parameter -memlimit 500
    

Note

The preceding command displays the following warning message: Warning: Feature not enabled [IC].

  1. Save the configuration

    save config
    
  2. From the shell prompt, run the following command to verify in the configuration file

    root@ns# cat /nsconfig/ns.conf | grep memLimit
    
  3. Change the memory limit

    set cache parameter -memLimit 500 -via NS-CACHE-9.3: 18 -verifyUsing HOSTNAME_AND_IP -maxPostLen 0 -enableBypass YES -undefAction NOCACHE
    
  4. Verify the new value for the memory limit

    > show cache parameter
            Integrated cache global configuration:
            Memory usage limit: 500 MBytes
            Maximum value for Memory usage limit: 843 MBytes
            Via header: NS-CACHE-9.3: 18
            Verify cached object using: HOSTNAME_AND_IP
            Max POST body size to accumulate: 0 bytes
            Current outstanding prefetches: 0
            Max outstanding prefetches: 4294967295
            Treat NOCACHE policies as BYPASS policies: YES
            Global Undef Action: NOCACHE
    
  5. Enable the integrated caching feature

    enable ns feature IC
    
  6. Verify the new value for the memory limit

    > show cache parameter
            Integrated cache global configuration:
            Memory usage limit: 500 Mbytes
            Memory usage limit (active value): 500 Mbytes
            Maximum value for Memory usage limit: 843 MBytes
            Via header: NS-CACHE-9.3: 18
            Verify cached object using: HOSTNAME_AND_IP
            Max POST body size to accumulate: 0 bytes
            Current outstanding prefetches: 0
            Max outstanding prefetches: 4294967295
            Treat NOCACHE policies as BYPASS policies: YES
            Global Undef Action: NOCACHE
    

Note

500 MB of memory is allocated to the integrated caching feature.

  1. Save the configuration to ensure that the memory is automatically allocated to the feature when the appliance is restarted.

Integrated caching is enabled and cache memory is set to zero

In this scenario, when you start the appliance, the integrated caching feature is enabled and the global memory limit is set to zero. Therefore, no memory is allocated to the integrated caching during the boot process.

Configuring by using the CLI

  1. Verify the memory limits set in the ns.conf file from shell prompt

    root@ns# cat ns.conf | grep memLimit
    
  2. Change the memory limit

    set cache parameter -memLimit 0 -via NS-CACHE-9.3: 18 -verifyUsing HOSTNAME_AND_IP -maxPostLen 4096 -enableBypass YES -undefAction NOCACHE
    
  3. Verify the value for the memory limit

    > show cache parameter
            Integrated cache global configuration:
            Memory usage limit: 0 Mbytes
            Maximum value for Memory usage limit: 843 MBytes
            Via header: NS-CACHE-9.3: 18
            Verify cached object using: HOSTNAME_AND_IP
            Max POST body size to accumulate: 0 bytes
            Current outstanding prefetches: 0
            Max outstanding prefetches: 4294967295
            Treat NOCACHE policies as BYPASS policies: YES
            Global Undef Action: NOCACHE
    

Note

The memory limit is set to 0 MB and no memory is allocated to the integrated caching feature.

  1. Set the memory limits to ensure the integrated caching feature caches objects

    set cache parameter -memLimit 600
    

Once you run the preceding command, the appliance negotiates memory for the integrated caching feature and the available memory is assigned to the feature. It results in appliance caching objects without restarting the appliance.

  1. Verify the value for the memory limit

    > show cache parameter
            Integrated cache global configuration:
            Memory usage limit: 600 Mbytes
            Memory usage limit (active value): 600 Mbytes
            Maximum value for Memory usage limit: 843 MBytes
            Via header: NS-CACHE-9.3:
            Verify cached object using: HOSTNAME_AND_IP
            Max POST body size to accumulate: 0 bytes
            Current outstanding prefetches: 0
            Max outstanding prefetches: 4294967295
            Treat NOCACHE policies as BYPASS policies: YES
            Global Undef Action: NOCACHE
    

Note

600 MB of memory is allocated to the integrated caching feature.

  1. Save the configuration. Ensure that the memory is automatically allocated to the feature when the appliance is restarted.

  2. Verify the memory limits set in the ns.conf file from shell prompt

    root@ns# cat /nsconfig/ns.conf | grep memLimit
    
  3. Change the memory limit

    set cache parameter -memLimit 600 -via NS-CACHE-9.3: -verifyUsing HOSTNAME_AND_IP -maxPostLen 4096 -enableBypass YES -undefAction NOCACHE
    

Integrated caching is disabled and cache memory is set to zero

In this scenario, when you start the appliance, the integrated caching feature is disabled and the global memory limit is set to zero. Therefore, no memory is allocated to the integrated caching during the boot process.

Configuring by using the CLI

  1. Verify the memory limits set in the ns.conf file from shell prompt

    root@ns# cat /nsconfig/ns.conf | grep memLimit
    
  2. Change the memory limit

    set cache parameter -memLimit 0 -via NS-CACHE-9.3: 18 -verifyUsing HOSTNAME_AND_IP -maxPostLen 4096 -enableBypass YES -undefAction NOCACHE
    
  3. Verify the value for the memory limit

    > show cache parameter
            Integrated cache global configuration:
            Memory usage limit: 0 Mbytes
            Maximum value for Memory usage limit: 843 MBytes
            Via header: NS-CACHE-9.3: 18
            Verify cached object using: HOSTNAME_AND_IP
            Max POST body size to accumulate: 0 bytes
            Current outstanding prefetches: 0
            Max outstanding prefetches: 4294967295
            Treat NOCACHE policies as BYPASS policies: YES
            Global Undef Action: NOCACHE
    

Note

The memory limit is set to 0 MB and no memory is allocated to the integrated caching feature. Also, when you run any cache configuration command, the following warning message is displayed: Warning: Feature not enabled [IC].

  1. Enable the integrated caching feature

    enable ns feature IC
    

Note

At this stage, when you enable the integrated caching feature, the appliance does not allocate memory to the feature. As a result, no object is cached to the memory. Also, when you run any cache configuration command, the following warning message is displayed: No memory is configured for IC. Use set cache parameter command to set the memory limit.

  1. Set the memory limits to ensure the integrated caching feature caches objects

    set cache parameter -memLimit 500
    

Once you run the preceding command, the appliance negotiates memory for the integrated caching feature and the available memory is assigned to the feature. It results in the appliance caching objects without restarting the appliance.

Note

The order in which you enable the feature and set the memory limits is important. If you set the memory limits before enabling the feature, then the following warning message is displayed: Warning: Feature not enabled [IC].

  1. Verify the value for the memory limit

    > show cache parameter
            Integrated cache global configuration:
            Memory usage limit: 500 Mbytes
            Memory usage limit (active value): 500 Mbytes
            Maximum value for Memory usage limit: 843 MBytes
            Via header: NS-CACHE-9.3:
            Verify cached object using: HOSTNAME_AND_IP
            Max POST body size to accumulate: 0 bytes
            Current outstanding prefetches: 0
            Max outstanding prefetches: 4294967295
            Treat NOCACHE policies as BYPASS policies: YES
            Global Undef Action: NOCACHE
    

Note

500 MB of memory is allocated to the integrated caching feature.

  1. Save the configuration

    save config
    
  2. Verify the memory limits set in the ns.conf file from shell prompt

    root@ns# cat /nsconfig/ns.conf | grep memLimit
    
  3. Change the memory limit

    set cache parameter -memLimit 500 -via NS-CACHE-9.3: 18 -verifyUsing HOSTNAME_AND_IP -maxPostLen 4096 -enableBypass YES -undefAction NOCACHE