Cisco CSS 11000 Series Content Services Switches

Product Bulletin: WebNS Scripted Keepalive Guidelines

Product Bulletin No. 2161

Cisco CSS 11000 and CSS 11500 Series
Content Services Switches with Cisco WebNS
Software, Scripted Keepalive Guidelines


The Cisco® WebNS Software for Cisco CSS 11000 and CSS 11500 content services switches supports scripted keepalives that allow for custom health-checking of applications and resources. This bulletin outlines a method for determining the resources required to run various types of scripted keepalives on the Cisco CSS switches.

For details about using and creating scripts, see the product documentation at: product/webscale/css/css_710/advcggd/scripts.htm

For details on keepalives, see the product documentation at univercd/cc/td/doc/product/webscale/css/css_710/bsccfggd/services.htm#1026607

Scripted keepalives use the Cisco CSS Scripting Language that is included with the Cisco CSS software to simulate a transaction with a back-end application server. Scripted keepalives are used in conjunction with services, such as those serving content, that require application-level monitoring for health. This function allows users to automatically remove services that have network connectivity, but do not have accurate application data. As an example, scripted keepalives can be used to inspect a Web page and compare its contents with a previous version to make sure the content has not changed. If it has changed, the keepalive fails and the service is not used to provide content to users.

A maximum of up to 255 scripted keepalives can be configured on a Cisco CSS switch. The flexibility offered by this feature is valuable, but does require varying amounts of CPU resources depending on the complexity and frequency of the keepalives. The following information provides guidance on the configuration and use of scripted keepalives based on their need for CPU resources.

In Cisco WebNS Software versions 5.00 and 6.10 for the Cisco CSS 11000 and version 5.10 for the Cisco CSS 11500, scripted keepalives used an automatic calibration technique that dynamically adjusted the frequency at which a script was run. If required, this adjustment would override the frequency for this keepalive set by the administrator. For example a scripted keepalive that assumed the default frequency and was set to run at a frequency of 5 seconds could be run at any frequency up to 60 seconds based on the time required to execute the script. While this approach protected the system as a whole, it could mislead administrators and cause challenges in troubleshooting situations.

In Cisco WebNS 5.20 and Cisco WebNS 7.10 and higher for the Cisco CSS 11500, scripted keepalives adhere strictly to the keepalive frequency set by the administrator. This approach has the benefit of accurately reflecting configurations to the administrator for operational and troubleshooting situations. The strict adherence to the keepalive frequency requires that administrators understand the impact and resources of different types of scripts. If a script is run too frequently there is the possibility that it will cause excessive stress on the CPU, negatively affecting device availability and performance. Administrators should set the frequency for scripted keepalives 2 or more seconds beyond the time required for a script to execute with a minimum frequency of five seconds1.

The following guidelines apply to scripts that perform a single request/response protocol on top of TCP:

  • Environments where the flow rate is expected to be high (greater than 500 flows per second), it is recommended NOT to exceed 10 script keepalives per second (50 @ 5 seconds, 100 @ 10 seconds, 200 @ 20 seconds, 255 @ 26 seconds).
  • Environments where the flow rate is expected to be low (100 or fewer flows per second), it is recommended NOT to exceed 15 script keepalives per second (75 @ 5 seconds, 150 @ 10 seconds, 255 @ 17 seconds).
  • The following scripts provided by Cisco Systems® are of this type: [ap-kal-httplist (one request), ap-kal-httpauth, ap-kal-httptag, ap-kal-echo (TCP version), ap-kal-finger, ap-kal-ssl, ap-kal-smtp, ap-kal-time, ap-kal-setcookie, ap-kal-netbios, ap-kal-ldap).
  • For scripts that perform multiple request response pairs, the aforementioned maximums can be conservatively reduced by the number of pairs. For example, ap-kal-imap4 performs three request/response interactions reducing the maximum rate at a low flow rate yields 15/3 or 5 per second (25 @ 5 seconds, 50 @ 10 seconds, 100 @ 20 seconds, 255 @ 51 seconds). The ap-kal-httplist may also be reduced if it is used in a fashion that results in probing multiple hosts. (Also: ap-kal-pop3: 2 pairs, ap-kal-mailhost: 4 pairs).

For scripts that perform a single request/response protocol on User Datagram Protocol (UDP), the following guidelines are applicable:

  • Environments where the flow rate is expected to be high greater than 500 flows per second), it is recommended NOT to exceed 15 script keepalives per second (75 @ 5 seconds, 150 @ 10 seconds, 255 @ 17 seconds).
  • Environments where the flow rate is expected to be low (100 or fewer flows per second), it is recommended NOT to exceed 20 script keepalives per second (100 @ 5 seconds, 200 @ 10 seconds, 255 @ 13 seconds).
  • Scripts that interact with external servers can be adversely affected by poorly performing servers. The aforementioned maximums should be damped in environments where it is known that the server response times are poor or unpredictable.

Scripts that execute combinations of command-line interface (CLI) commands require independent examination. For example, it is recommended that the ap-kal-pinglist does not exceed seven per second because of the overhead of using the CLI ping (35 @ 5 seconds, 70 @ 10 seconds, 140 @ 20 seconds, 255 @ 37 seconds). It is recommended that the native icmp keepalive type be used whenever possible.

To aid administrators in determining the overhead of custom scripts, two scripts are available; `script-config' and `script-deconfig'. These scripts create and remove a series of scripts with a specified frequency to allow the administrator to observe the induced workload. Use the `show system-resources cpu_summary' command when the scripts are running to observe the workload.

The syntax is as follows:

script play script-config "theCount theFreq theScriptNamescript theScriptArg1 theScriptArg2"


script play script-deconfig "theCount"

To test a custom script named `my-custom':

a) Run: script play script-config "100 10 my-custom"

b) Observe the CPU via `show system-resources cpu_summary' command over a period of at least 5 times the configured frequency.

c) Deconfig: script play script-deconfig "100"

d) Repeat step a as needed—repeat this procedure as needed

If the administrator is carrying out this testing without subjecting traffic to the Cisco CSS switch, a CPU de-rating must be applied to account for the lack of traffic. For a moderate traffic load Cisco suggests a factor of two.Therefore, to achieve 50 percent CPU utilization under a moderate load, aim for 25 percent when testing the script configuration's absent traffic. Simulating the actual deployment environment is recommended to optimize this process.

Additionally administrators are reminded that the keepalive retry period cannot be lower than the time required to execute the script and should be adjusted in conjunction with the keepalive frequency.