Worldwide [change] |Account |Register |About Cisco
Guest

Hierarchical Navigation

Cisco CSS 11500 Series Content Services Switches

WebNS 4.0 Scripted Keepalives Configuration Example

Downloads

Document ID: 12076


Contents

Introduction
Before You Begin
      Conventions
      Prerequisites
      Components Used
      Background Theory
Configure
      Viewing a Script Keepalive in a Service
      Socket Primitives
      Socket Administration
      Copying Script Files
      Script Samples
Verify
Troubleshoot
Related Information

Introduction

This document describes the initial implementation of scripted keepalives. This method of scripting is most closely related to functionality which is present in Reliability, Availability, and Serviceability (RAS) dialup clients, terminal programs, and general scripting utilities. This feature utilizes the CSS's rich scripting language.

Configuring this with a simple socket API (connect/disconnect/send/receive) will give the user the ability to tailor their own protocol, or write their own sequence of steps to provide a reliable ALIVE or DOWN state of a service. You are currently limited to FTP, HTTP, ICMP, and TCP. With this new feature, you can remain on top of the current protocols by writing your own scripts. For example, a user can develop a script specifically toned to connect to a POP3 server without requiring Cisco to build a keepalive type POP3 to suit their needs. This feature will allow customers to create their own custom keepalives to suit their specific requirements.

Before You Begin

Conventions

For more information on document conventions, see the Cisco Technical Tips Conventions.

Prerequisites

There are no specific prerequisites for this document.

Components Used

This document applies to CSS 11000/CSS 11500 or CSS 11800 with WebNS software.

The information presented in this document was created from devices in a specific lab environment. All of the devices used in this document started with a cleared (default) configuration. If you are working in a live network, ensure that you understand the potential impact of any command before using it.

Background Theory

Once you have developed a Command Line Interface (CLI) script offline using a text editor such as Notepad, you can upload that script to the /script directory of the CSS and configure the script keepalive option on a service. You are allowed to create a script keepalive without having a script present on the system. In the case of a script keepalive running without a script on the system, a constant DOWN state will remain on the service. This allows an administrator to write a configuration and implement the configuration before writing out (or uploading) all of the scripts.

A script must reside in the /<current running version>/script/ directory for the script keepalive to find the script. Path names are not accepted, only script names when configuring the script keepalive. If the script is present elsewhere on the system, the script keepalive will assume it does not exist. This means, however, when the software is upgraded on the system, the old scripts reside in the old version’s script directory. To copy the scripts from the old directory, see the Copying Script Files section of this document.

You can pass 128 characters in a quoted argument. Assuming a standard of seven characters per argument, you can get about 18 arguments in one script. The command line will only accept 90 characters however.

It is recommended that script keepalives be configured with a lower frequency than a standard keepalive because many scripts will have a multi-step process such as connecting, sending a request, and waiting for a specific type of response. Due to this, it is recommended to have a frequency of ten seconds or higher so that the keepalive has time to finish completely. Otherwise, state transitions may occur more often.

A script can return a status code of zero or non-zero. On a return of non-zero, the CSS will flag the service state as DOWN. On a return of zero, the CSS will flag the service state as ALIVE. Refer to the following script for an example:


!--- Connect to the remote host.


socket connect host einstein port 25 tcp 


!--- Validate that you did connect.


if $SOCKET "==" "-1" 
exit script 1 
endbranch

The CSS will always return a state of DOWN if the ${SOCKET} variable is set to negative one. It is very important to check the logic of your scripts to ensure that the correct value gets returned.

Configure

In this section, you are presented with the information to configure the features described in this document.

For large numbers of services that require use of script keepalives, it is highly recommended that they use a smaller subset of global keepalives to handle the work for them.

To configure a script keepalive, follow the same guidelines as for all other keepalive types. The command syntax is shown below.

CS100(config-service[serv1)# keepalive type script ap-kal-smtp "einstein"

or

CS100(config-service[serv1])# keepalive type script ap-kal-pop3 "einstein vxworks mipspci"

The first line will configure the current service keepalive to be of type script and to have the script name ap-kal-smtp with argument einstein. The second line shows ap-kal-pop3, which is similar to the first script, but will pass three arguments: einstein, vxworks, and mipspci. It is also possible to hit the Tab (or ?) key to see a complete list of all scripts available in the /<current running version>/script directory. This encourages you to adopt a script naming convention so that when you hit Tab or ?, you can clearly see the keepalive scripts available to use. A naming convention of ap-kal-type is used for scripts. For example, an SMTP script would be named ap-kal-smtp. Optionally, you can type in one not found in that list, assuming you wish to upload it at a later date. Scripts can be manipulated through the archive, clear, and copy commands, and can be upload/download from the /script directory on the switch.

The script name can be up to 32 characters long. The arguments must be passed in a quoted string, and can be up to 128 characters long. To disable the script keepalive, you would re-configure the service by issuing the following command:

CS100(config-service[cs100])# keepalive type none

Viewing a Script Keepalive in a Service

When a script keepalive is configured under a service, the script name can be seen in the show service command output. The script shows up under the keepalive type, and any potential arguments can be found directly under that line in the Script Arguments: field. If there are no script arguments, that field is not displayed. An example of the service cs100 with a script called ap-kal-pop3 with the arguments vxworks and mipspci is shown below.

webns_scripted_keepalives-1.gif

With this power, a script like ap-kal-pop3 could take three parameters, which would match the hostname, username, and password for a POP3 server. Simply logging in to the POP server is enough for the script to determine that this server is in the ALIVE state.

The show running-config command output is shown below.

webns_scripted_keepalives-2.gif

The above command output shows exactly what script (and arguments) have been configured on this service. If no arguments are present, the quoted text following the script name will not be present.

When working with script logging, the configuration is as follows:

webns_scripted_keepalives-3.gif

This example shows the service logging its script keepalive output to testlog.log.

Socket Primitives

There are a few socket commands that can be used in a script keepalive to assist in building a structured protocol. The socket primitives will allow for ASCII or hexadecimal send and receive functionality. Each command that has an optional RAW keyword will change the data from a standard ASCII to a hexadecimal conversion. For example, abcd in ASCII would be represented by 61626364, which denotes 0x61 0x62 0x63 0x64.

Refer to the following list of socket command for more information:

  • socket connect host hostname port port tcp | udp [ integer ] [ session ]

    - this command performs either a TCP or UDP connection. Performing a TCP connection involves a handshake (SYN-SYNACK...) to a specific IP/port. Performing a UDP connection is merely a reservation of the host/port. The socket value is received in a ${SOCKET} variable in the script.

    Note: Only 32 sockets can be opened at any one time across all scripts on the switch.

    The list below provides information on each parameter.

    • host - a keyword that should be followed by the hostname or IP address of the remote system.

    • port - keyword which should be followed by the port on which to negotiate a connection with.

    • tcp - a connection using TCP.

    • udp - a connection using UDP.

    • integer - a timeout value for the network establishment in seconds. If the time limit expires before the connection has been successfully made, the attempt fails. This only applies to a TCP connection, as UDP is connectionless. The default value is a timeout of five seconds.

    • session - a keyword that tells the socket to remain open until the session is finished. That means any scripts that open sockets in the session and do not close them on their own shall remain open until the user logs out.

  • socket send socket# string [ raw | base64 ]

    - this command writes data through a previously connected TCP connection.

    The list below provides information on each parameter.

    • socket# - the socket file descriptor (integer form). This descriptor is returned from connect.

    • string - quoted text string up to 128 characters in length.

    • raw - if specified, causes the string values to be transferred as actual hexadecimal bytes rather than a simple string. For example, 0D0A is not sent as ‘0’ ‘D’ ‘0’ ‘A,' but rather as 0x0D 0x0A (or carriage return, line feed).

    • base64 - this will base64 encode the string before sending it through the connection. Useful for HTTP basic authentication when connecting to a password protected web site.

  • socket receive socket# [ integer ] [ raw ]

    - this command fills up the 10K internal buffer with data coming in from the remote host. This command then locks the buffer so that no new data will be put in this internal buffer. You can proceed to use inspect to dump all data residing in this internal 10K buffer to standard output. Note: All previous data in the 10K internal buffer is flushed out before new data is put in.

    The list below provides information on each parameter.

    • socket# - the socket file descriptor (integer form). This descriptor is returned from connect.

    • integer - an integer value representing the number of milliseconds to wait before locking the internal 10K buffer and returning to the user. If no integer time out is not specified, receive will wait 100ms before returning to the user.

    • raw - if specified, causes the string values to be transferred as actual hexadecimal bytes rather than a simple string. For example, 0D0A is not sent as ‘0’ ‘D’ ‘0’ ‘A,' but rather as 0x0D 0x0A (or carriage return, line feed).

  • socket waitfor socket# string [ integer ] [ case-sensitive ] [ offset ] [raw]

    - this command is similar to socket receive, except that it returns immediately upon finding the specified string argument. Once the specified string is found, it will return ${STATUS} of zero. Otherwise, it returns 1. The data retrieved can be further viewed by issuing the socket inspect command.

    The list below provides information on each parameter.

    • socket# - the socket file descriptor (integer form). This descriptor is returned from connect.

    • string - the specific string that must be found to result in a ${STATUS} of zero, which indicates found. If the string is found, it returns immediately and does not wait the entire integer timeout length.

    • integer - an integer value representing the number of milliseconds to wait before locking the internal 10K buffer and returning to the user. If no integer time out is not specified, receive will wait 100ms before returning to the user.

    • case-sensitive - if specified, indicates that the string comparison should be case sensitive. For example, User: would not be equivalent to user:.

    • offset - how many bytes into the received data the string should be found. For example, if you search for a0 and give an offset of ten, you will look for a0 ten bytes into the data received.

    • raw - if specified, causes the string values to be transferred as actual hexadecimal bytes rather than a simple string. For example, 0D0A is not sent as ‘0’ ‘D’ ‘0’ ‘A,' but rather as 0x0D 0x0A (or carriage return, line feed).

  • socket inspect socket# [ pretty ][ raw ]

    - this command inspects the socket’s data buffer (internal) for actual data. If data is found, that data is displayed to standard output. If the characters displayed are non-printable, they will be represented by a dot (.) for readability.

    The list below provides information on each parameter.

    • socket# - the socket file descriptor (integer form). This descriptor is returned from connect.

    • raw - if specified, causes the string values to be displayed as actual hexadecimal bytes rather then a simple string. Rather then printing ABCD to standard out, it would print 41424344 (1 byte hexadecimal equivalent).

    • pretty - pretty printing of output. Each line will contain both the ASCII or hexadecimal equivalent for each byte of data. There will be 16 bytes printed on each line. For example, 0x41 0x42 0x43 0x44 0x10 0x05 ABCD.

  • socket disconnect socket# [ graceful ]

    - this command closes the connection to the remote host. This is done by sending RST to the remote host so that it knows you are done sending data.

    The list below provides information on each parameter.

    • socket# - the socket file descriptor (integer form). This descriptor is returned from connect.

    • graceful - graceful disconnect that sends a FIN rather than a RST to the remote host to close the connect.

Socket Administration

There is a limitation of 32 open (in use) sockets on the switch at any one time. If a user does a socket connect and does not end with a socket disconnect for that socket’s file descriptor (saved in ${SOCKET}), the socket remains open until a socket disconnect has been called with that socket as the parameter. Sockets opened within scripts are closed when the script ends (unless the session argument is passed in the socket connect). Sockets opened within sessions are closed when the session ends.

If a socket remains open, this usually is a case where the user has made a connection without properly closing. That socket will remain open and used until it is closed or until the script (or terminal connection) has been closed. The show sockets command has been implemented to list all the used socket file descriptors that are currently in use so that the user knows what is open and what is closed.

Note: If a remote host times out a socket, or the socket is closed by a remote host, the socket architecture is smart enough to clean it up, and take it out of the list of used sockets (found by issuing the show sockets command). This will only occur after a user attempts to make another transfer upon a socket that has been closed by the remote host (otherwise it sits idle awaiting the users needs).

The show sockets command output is shown below.

webns_scripted_keepalives-4.gif

The screen lists the socket ID (file descriptor), connected Host/Port pair, User, and a timer of how long the descriptor has been open. The User field would represent the line identifier as seen in the show lines command output on the CLI.

Retrieving data using socket receive is able to buffer 10K worth of data at one time. This buffer will remain unchanged until the user does another socket receive, at which point the buffer is cleaned out and re-filled with more data coming off the wire. Each socket descriptor (created from socket connect) will have its own 10K buffer.

Copying Script Files

When upgrading to a new version of code, all script files that you have modified in the previous version’s script directory will need to be copied to the new version.

Follow these steps before upgrading your switch:

  1. FTP to the CSS switch. Use the management port or VLAN circuit address.

  2. CD to the script directory.

  3. Download all scripts you have edited to your local machine.

  4. Upgrade your switch.

  5. Upload the scripts from your local machine to the switch’s new script directory.

Script Samples

The following scripts are available in order to provide you some default implementations. These samples contain scripts written for DNS, Echo, NetBios, Finger, Time, HttpList, PingList, HttpAuth, Imap4, CookieSet, POP3, HttpTag, MailHost, and SMTP.

Issue the show script ? command to see the scripts. Sample command output is shown below.

CS150# show script
  ap-kal-dns          NOV 17 09:58:36           1555
  ap-kal-echo         NOV 17 09:58:36           1920
  ap-kal-finger       NOV 17 09:58:36           1172
  ap-kal-httpauth     NOV 17 09:58:36           1927
  ap-kal-httplist     NOV 17 09:58:36           1674
  ap-kal-httptag      NOV 17 09:58:36           1180
  ap-kal-imap4        NOV 17 09:58:36           1556
  ap-kal-ldap         NOV 17 09:58:36           1640
  ap-kal-mailhost     NOV 17 09:58:36           2437
  ap-kal-netbios      NOV 17 09:58:36           1632
  ap-kal-pinglist     NOV 17 09:58:36            739
  ap-kal-pop3         NOV 17 09:58:36           1568
  ap-kal-setcookie    NOV 17 09:58:38           1436
  ap-kal-smtp         NOV 17 09:58:38           1310
  ap-kal-ssl          NOV 17 09:58:38           2053
  ap-kal-time         NOV 17 09:58:38           1064
  cache.map           NOV 17 09:58:38           1615
  commit_redundancy   NOV 17 09:58:38         109224
  commit_vip_redund.. NOV 17 09:58:38         132147
  default-profile     NOV 17 09:58:38           1240
  dnslookup           NOV 17 09:58:40           8009
  eql-cacheable       NOV 17 09:58:40           1186
  eql-graphics        NOV 17 09:58:40            234
  eql-multimedia      NOV 17 09:58:40            279
  flowinfo            NOV 17 09:58:40           5665
  monitor             NOV 17 09:58:40           3734
  pcm-collect-cfgs    NOV 17 09:58:40           2373
  pcm-repeat-cmd      NOV 17 09:58:40           4995
  service-load        NOV 17 09:58:40            920
  setup               NOV 17 09:58:40          24328
  showtech            NOV 17 09:58:40           2528
  testpeering         NOV 17 09:58:40          34142
  upgrade             NOV 17 09:58:40          17117
  ap-kal-ssl.txt      NOV 24 09:18:00           2053

Verify

There is currently no verification procedure available for this configuration.

Troubleshoot

Use the following guidelines to troubleshoot your configuration:

  • Run the script from the command line by issuing the script play command. Issue this command when logged in as a superuser to make sure it completes without error. If it does error out, the line that caused the error should be issued.

  • Take a sniffer trace between the CSS and the web server to observe what is actually returned when the script is run versus what the script is expecting to see.

  • In 5.x versions of code, the use-output command was added. This command must be used with all scripts that use the grep command. For example, keepalive type script ap-kal-dns arguments use-output.

Related Information

Updated: Jan 31, 2006 Document ID: 12076