Server Load-Balancing Guide vA4(2.0), Cisco ACE 4700 Series Application Control Engine Appliance
Chapter: Using TCL Scripts with the ACE
Using TCL Scripts with the ACE
You can copy, upload, and execute Toolkit Command Language (TCL) scripts on the ACE. TCL is a widely used scripting language within the networking community. TCL also has large libraries of developed scripts that can easily be found from various sites. Using TCL scripts, you can write TCL scripts for customized health probes. You can also execute ACE CLI commands in these scripts. The ACE also supports UDP socket functions.
Note 
The ACE does not support custom scripts to monitor itself.
Note The ACE can simultaneously execute only 200 scripted probe instances. When this limit is exceeded, the show probe detail command displays the "Out-of Resource: Max. script-instance limit reached" error message in the Last disconnect err field and the out-of-sockets counter increments.
This chapter provides information on scripts and contains the following topics:
•Copying and Loading Scripts on the ACE
•Configuring Health Probes for Scripts
•Displaying Script Information
Scripts Overview
The ACE supports several specific types of health probes (for example HTTP, TCP, or ICMP health probes) when you need to use a diverse set of applications and health probes to administer your network. The basic health probe types supported in the current ACE software release may not support the specific probing behavior that your network requires. To support a more flexible health-probing functionality, the ACE allows you to upload and execute TCL scripts on the ACE.
The TCL interpreter code in the ACE is based on Release 8.44 of the standard TCL distribution. You can create a script to configure health probes. Script probes operate similarly to other health probes available in the ACE software. As part of a script probe, the ACE executes the script periodically, and the exit code that is returned by the executing script indicates the relative health and availability of specific real servers. For information on health probes, see Chapter 4, Configuring Health Monitoring. If the script includes commands for ACE CLI commands, these CLI commands execute when the script probe executes. For information on TCL commands to execute ACE CLI commands, see Table A-4.
Cisco Systems-Supplied Scripts
For your convenience, the following Cisco Systems-supplied sample scripts for the ACE are available to support the TCL feature and are supported by the Cisco Technical Assistance Center (TAC):
•ECHO_PROBE_SCRIPT
•FINGER_PROBE_SCRIPT
•FTP_PROBE_SCRIPT
•HTTP_PROBE_SCRIPT
•HTTPCONTENT_PROBE
•HTTPHEADER_PROBE
•HTTPPROXY_PROBE
•IMAP_PROBE
•LDAP_PROBE
•MAIL_PROBE
•POP3_PROBE
•PROBENOTICE_PROBE
•RTSP_PROBE
•SSL_PROBE_SCRIPT
These scripts are located in the probe: directory and are accessible in both the Admin and user contexts. To list the contents of this directory, use the following command:
host1/Admin# dir probe:
You can use these sample scripts with probes after you load the scripts into memory and associate them with probes. When you configure a new scripted probe, the ACE looks for the script file in the disk0: directory first, then the probe: directory. If a script file with the same name resides in both the probe: directory and the disk0: directory, the ACE uses the file in the disk0: directory. Note that the script files in the probe: directory are read-only, so you cannot copy or modify them. However, you can copy files from the probe: directory. For more information, see the Cisco 4700 Series Application Control Engine Appliance Administration Guide.
For information about loading scripts into memory, see the "Loading Scripts into the ACE Memory" section. For information about associating a script with a probe, see the "Associating a Script with a Probe" section in Chapter 4, Configuring Health Monitoring.
Probe Suspects
A probe suspect is a destination (IP address and port) to which the ACE sends a probe. Typically, the IP address is the address associated with the object on which the probe is configured (for example, an rserver, a serverfarm, or an rserver configured in a serverfarm). You can configure the port using the probe scripted command. The IP address and port for each suspect are passed to the script in the scriptprobe_env array (see the "Environment Variables" section) as realIP and realPort, respectively. If you do not specify a port in the probe scripted command, the health probe scripts specify a default port in the script itself. For example, the SSL_PROBE_SCRIPT file specifies a default port of 443, the standard HTTPS port. For more information about the probe scripted command, see the "Configuring Health Probes for Scripts" section.
Probe Script Quick Start
Before you can run a probe script, you must copy the script onto the ACE, configure a script probe, and then associate the script with the probe. Table A-1 provides steps to copy and load a script on the ACE, and configure an associated scripted probe.
Copying and Loading Scripts on the ACE
You load scripts onto the ACE through script files. A script file contains only one script. The ACE supports the configuration of 256 unique script files.
When using scripts on the ACE, the following considerations apply:
•Each script is always identified by its unique name as defined when copying the script file into the ACE disk0: file system. The script name must be unique across contexts.
•During probe configuration, you can assign a script to a probe. If the script is unavailable at that time, the probe attempts to execute the script and returns an error code. If this situation occurs, a syslog message displays to indicate the probe failure and why the probe failed. If the script is unavailable due to an error when loading the script, a syslog message would indicate the script load failure. You can also use the show script command to display the exit codes. For a list of exit codes, see Table A-7.
•To change a script that is already loaded into memory, you must unload and then reload the script. For information on loading a script file, see the "Loading Scripts into the ACE Memory" section. For information on reloading a script, see the "Removing Scripts from ACE Memory" section.
After the script is changed in memory, the ACE applies the changes automatically the next time that the script executes. The command line arguments specified during probe configuration still apply after the reloading of the script.
Note Because the ACE does not replicate probe scripts to the standby in a redundant configuration, you must copy the scripts from the probe: directory of the active ACE to the probe: directory of the standby ACE. Otherwise, configuration synchronization does not work properly.
This section contains the following topics:
•Unzipping and Untarring ACE Sample Scripts
•Loading Scripts into the ACE Memory
•Removing Scripts from ACE Memory
•Reloading Modified Scripts in ACE Memory
Copying Scripts to the ACE
You can copy a script from a server to the ACE disk0: file system by using the copy command in Exec mode. You can also copy the file from the supervisor engine to the ACE.
Because of virtualization, by default, a script file is copied into the directory for the context that you are currently accessing. A script file in one context cannot be seen from another context. For details about virtualization, see the Cisco 4700 Series Application Control Engine Appliance Virtualization Configuration Guide. The syntax of this command is as follows:
copy [ftp://server/path | tftp://server[:port]/path | sftp://[username@]server/path] disk0:filename
The keywords and arguments are as follows:
•ftp://server/path—Specifies the File Transfer Protocol (FTP) network server and the source location of the script file including its filename.
•tftp: //server[:port]/path]—Specifies the Trivial File Transfer Protocol (TFTP) network server and the source location of the script file including its filename.
•sftp:[//[username@]server][/path]—Specifies the Secure File Transfer Protocol (SFTP) network server and the source location of the script file including its filename.
•disk0:filename—Specifies the destination filename for the script on the ACE disk0: file system. If you do not enter a filename, you are prompted to enter a filename or accept the source filename. You will use this filename when you load the script into the ACE memory and configure the probe.
Note The filename that you assign to the script must be unique across the contexts.
For example, to copy a script from an FTP server to the ACE, enter:
host1/Admin# copy ftp://192.168.1.1/test1/FTP_PROBE_SCRIPT disk0:ftp1.tcl
Enter username:
At the prompt, you must provide a username for the server.
Using the ACE Sample Scripts
Cisco Systems provides sample probe scripts that you can use to associate with a health probe. The scripts are stored in the probe: directory.
You can also copy the zipped sample scripts file for the ACE onto disk0:. After you copy the zipped file, use the gunzip command in Exec mode to unzip its contents. For information about using this command, see the "Unzipping and Untarring ACE Sample Scripts" section.
Unzipping and Untarring ACE Sample Scripts
Sample scripts for the ACE are available to support the TCL feature. All of these scripts are provided in a zipped file which contains a .tar file. After you copy the zip file to the ACE, you need to unzip it and then untar it. When you untar the file, the ACE automatically creates an ace_scripts directory and places all of the individual scripts in it.
Note Some browsers, such as Internet Explorer version 6.0, automatically uncompresses a .tgz file. If you download the sample script file to the ACE with a browser that uncompresses the file, you can untar the file with the untar command. It is unnecessary to use the gunzip command on it.
You can unzip the sample scripts file by using the gunzip command in Exec mode. The syntax for this command is as follows:
gunzip disk0:[path/]filename.tgz
The filename argument is the name of the zipped scripts file.
For example, to unzip the ace_scripts.tgz scripts file, enter:
host1/Admin# gunzip disk0:ace_scripts.tgz
The ACE unzips the file and places the ace_scripts.tar file in the disk0: file system.
To untar all of the script files from the ace_scripts.tar file, use the untar command in Exec mode. The syntax for the command is as follows:
untar disk0:[path/]filename
The filename argument is the name of the .tar file in the disk0: file system. The filename must end with a .tar extension.
For example, to untar all of the script files into the ace_scripts directory in the disk0: file system, enter:
host1/Admin# untar disk0:ace_scripts.tar
To view the scripts in the ace_scripts directory, use the dir command in Exec mode. For example, enter:
host1/Admin# dir disk0:ace_scripts/
Before you can load a sample script into memory, you must copy the script out of the ace_scripts directory into the disk0: directory. Use the copy disk0: command. For example, to copy the ftp1.tcl script from the ace_scripts directory to the disk0: directory, enter:
host1/Admin# copy disk0:ace_scripts/ftp1.tcl disk0:ftp1.tcl
Loading Scripts into the ACE Memory
You can load the script into memory on the ACE and enable it for use by using the script file name command in configuration mode. The syntax of this command is as follows:
script file name script_name
The script_name argument is the name of the script in the disk0: or probe: file system.
Note To load a script into memory, the script must be in the disk0: or probe: directory. The ACE does not load script files in a disk0: or probe: subdirectory.
For example, to load a script into memory:
host1/Admin(config)# script file name ftp1.tcl
To run the script or create a health probe using that script, use the script name you configured; do not use the script file from which the script was loaded.
Removing Scripts from ACE Memory
After a script file has been loaded, the scripts in that file exist in the ACE independent of the file from which that script was loaded. You can remove a script from memory and the running configuration by using the no script file name command in configuration mode.
The syntax of this command is as follows:
no script file name script_name
The script_name argument is the name of the script in the disk0: or probe: file system.
For example, to remove the script with the name ftp1.tcl, enter:
host1/Admin(config)# no script file ftp1.tcl
Reloading Modified Scripts in ACE Memory
If a script file is subsequently modified, you can update the script in memory by reloading it. Reloading a script requires the following:
1. Removing the script from memory by using the no script file name command in configuration mode. For information on removing a script from memory, see the "Removing Scripts from ACE Memory" section.
2. Reloading the modified script into memory by using the script file name command in configuration mode. For information about loading a script into memory, see the "Loading Scripts into the ACE Memory" section.
After the script is reloaded into memory, the ACE applies the changes automatically in the next script execution. The command-line arguments specified during probe configuration still apply after the reloading of the script.
For example, to reload the script ftp1.tcl, enter:
host1/Admin(config)# no script file name ftp1.tcl
host1/Admin(config)# script file name ftp1.tcl
Configuring Health Probes for Scripts
You can create a scripted probe that the ACE periodically executes for each real server in any server farm associated with a probe. Depending upon the exit code of a script, the real server is considered passed or failed. For more information on exit codes, see the "Exit Codes" section.
To create a scripted probe, use the probe scripted probe_name command in configuration mode. This command enters a probe configuration mode that is similar to the existing ACE health probe modes (such as HTTP, TCP, DNS, SMTP, and so on).
The probe scripted configuration mode includes the faildetect, interval, passdetect, and receive commands.The script script_name command can process up to 80 arguments that are passed to the script when it is run as part of the health probe function. When you configure each interval of time, an internal ACE scheduler schedules the health scripts. For more information on configuring scripted probes and the associated commands, see Chapter 4, Configuring Health Monitoring.
After creating the scripted health probe, attach the probe to the server farm and the virtual server. For example, enter:
host1/Admin(config)# serverfarm host tests
host1/Admin(config-sfarm-host)# probe test1
host1/Admin(config-sfarm-host)# rserver test
host1/Admin(config-sfarm-host-rs)# inservice
host1/Admin(config-sfarm-host-rs)# exit
Writing Probe Scripts
Probe scripts test the health of a real server by creating a network connection to the server, sending data to the server, and checking the response. The flexibility of this TCL scripting environment makes the available probing functions possible.
Write the script as if you intend to perform only one probe. You must declare the result of the probe using the exit command. Depending upon the exit code of a script, the real server is considered passed or failed. For more information about exit codes, see the "Exit Codes" section.
A health script typically performs these actions:
•Opens a socket to an IP address.
•Sends one or more requests.
•Reads the responses.
•Analyzes the responses.
•Closes the socket.
•Exits the script by using an exit code for success or failure.
This section provides information to assist you when you write a probe script. The topics are as follows:
•TCL Script Commands Supported on the ACE
•Example for Writing a Probe Script
TCL Script Commands Supported on the ACE
The ACE TCL script feature is based on the TCL 8.44 source distribution software. Table A-2 lists the TCL commands that are supported by ACE.
|
|
|||
|---|---|---|---|
|
|
|||
append |
array |
binary |
break |
case |
catch |
concat |
continue |
encoding |
error |
eval |
exit |
expr |
fblocked |
for |
foreach |
format |
gets |
glob |
global |
if |
incr |
info |
join |
lappend |
lindex |
linsert |
list |
llength |
lrange |
lreplace |
lsearch |
lset |
lsort |
namespace |
proc |
regexp |
regsub |
rename |
return |
scan |
set |
split |
string |
subst |
switch |
unset |
uplevel |
upvar |
variable |
while |
|
|
|
|||
after |
clock |
time |
|
|
|
|||
close |
eof |
fconfigure |
fileevent |
flush |
read |
socket |
update |
vwait |
|||
1 The puts command can appear in a script, however, the ACE does not display its output. |
Table A-3 lists the TCL command not supported by the ACE.
Table A-4 lists the TCL command specific to the ACE.
|
|
|
|---|---|
disable_real serverfarmName realIp port ,-1 | all probeNumId probeNameId |
Disables a real server from the server farm by placing it in the PROBE_FAIL state. This command returns a 1 if successful and returns a 0 if it fails, as follows: disable_real SF_TEST 1.1.1.1 -1 10 cisco
Note |
enable_real serverfarmName realIp port ,-1 | all probeNumId probeNameId |
Enables a real server from the PROBE_FAIL state to the operational state. This command returns a 1 if successful and returns a 0 if it fails, as follows: enable_real SF_TEST 1.1.1.1 -1 10 cisco Note |
gset varname value |
Allows you to preserve the state of a probe by setting a variable that is global within an instance (probe to server association). In an instance of the probe, the value is retained. Each time the probe comes back to execute the script after the firing interval expires, the probe can then access this value. The same probe associated under a different server will not be able to access this value. Variables in a probe script are only visible within one probe thread. Each time a probe exits, all variables are gone. For example, if a probe script contains a 'gset x 1 ; incr x', variable x would increase by 1 for each probe attempt. • • • |
set sock [socket -sslversion version -sslcipher cipher $ip $port] |
Opens a socket and configures the specified SSL version number (version) and cipher (cipher), and enables accelerated SSL connections from a TCL script. The version argument is the SSL version that the probe supports. Enter one of the following case-sensitive keywords. • • • The cipher argument is the RSA cipher suite that the probe expects from the back-end server. By default, the HTTPS probe accepts any of the RSA configured cipher suites. Enter one of the following case-sensitive keywords: • • • • • • • • • • • You must enter both version and cipher values. If you enter the incorrect version or cipher value including the wrong case (upper or lowercase), the command uses the default value. Typically, the $ip keyword is the IP address of the real server to which the ACE sends the probe. |
set sock (continued) |
Typically, the $port keyword is the port that you define in the scripted probe. If you do not define a port value in the scripted probe, the ACE uses the port defined with the real server. Although it is not a typical usage, you can define any IP address and port in the TCL script and then use those values in the set sock command, regardless of what is configured in the real server or the scripted probe. |
vsh_conf_cmd $cmd_string |
Allows the execution of the command or set of commands specified in the preceding set command string (cmd_str) by invoking the Vegas shell (Vsh). If you specify more than one command in the command string, separate them by the \n characters. For example, enter: set cmd_str "rserver rs \n inservice" vsh_conf_cmd $cmd_str |
vsh_show_cmd $cmd_string |
Allows the executing of the show command in the preceding set command string (cmd_str) by invoking the Vegas shell (Vsh). The output for the show command is set as a return value in the interpreter and the script invoking the commands must capture the results and parse the data. For example, enter: set cmd str "show rserver rs1" set buffer [vsh_show_cmd $cmd_str] |
ping [numpacket] host A.B.C.D |
Allows you to ping a host from a script. This command returns a 1 if successful and returns a 0 if it fails, as follows: set result [ping 3 1.1.1.1] |
xml xmlConfigString |
Sends an XML configuration string to the ACE from a TCL script. This command works only when the XML server is enabled on the ACE. Refer to the XML configuration section. This command returns a string with the XML configuration result, as follows: set cfg_result [ xml {
<config> <csm_module slot="6"> <serverfarm name="SF_TEST"> </serverfarm> </config> } ] |
The UDP command set allows Scotty-based TCL scripts to run on the ACE. Scotty is the name of a software package that allows you to implement site-specific network management software using high-level, string-based APIs. The TCL UDP command reference is located at this URL:
http://wwwhome.cs.utwente.nl/~schoenw/scotty/
Table A-5 lists the UDP commands used by the ACE.
Environment Variables
Health probe scripts have access to many configured items through a predefined TCL array. The most common use of this array is to find the current real server IP addresses of the suspect during any particular launch of the script.
Whenever the ACE executes a script probe, a special array called scriptprobe_env is passed to the script. This array holds important parameters that may be used by the script.
Table A-6 lists the members of the scriptprobe_env array.
|
|
|
|---|---|
realIP |
Suspect IP address. |
realPort1 |
Suspect IP port. |
intervalTimeout1 |
Configured probe interval in seconds. |
openTimeout |
Configured socket open timeout for this probe. |
recvTimeout1 |
Configured socket receive timeout for this probe. |
failedTimeout1 |
Configure failed timeout. |
retries1 |
Configured retry count. |
healthStatus |
Current suspect health status. |
contextID |
The ID for the context running this script. |
failedRetries1 |
Consecutive successful retries on a failed server before marking it as passed. |
isRouted |
Boolean to determine if this IP address is a routed address. |
pid |
Process identifier of the TCL process. |
runID |
Pointer to the event structure (em_event_t). |
1 Configurable parameter |
For more information about the configurable parameters in the scriptprobe_env array, see the "Configuring General Probe Attributes" section in Chapter 4, Configuring Health Monitoring.
Exit Codes
The probe script uses exit codes to signify various internal conditions. The exit code information can help you troubleshoot your scripts if they do not operate correctly. A probe script indicates the relative health and availability of a real server using the exit code of the script. By calling exit 30001, a script indicates that the server successfully responded to the probe. Calling exit 30002 indicates that the server did not respond correctly to the health probe.
For example, if a probe script fails and exits with 30002, the corresponding server is marked as PROBE_FAILED and is temporarily disabled from the server farm. The ACE continues to probe the server. When the probe successfully reconnects and exits with 30001, the ACE marks the server status as OPERATIONAL and enables the server from the server farm again. The exit 30001 must occur the number of failedRetries times before the server is marked as OPERATIONAL. See the previous section on environmental variables for further information on the failedRetries member name.
These situations can cause a script to fail and mark the suspect PROBE_FAILED:
•TCL errors—Occurs when scripts contain errors that are caught by the TCL interpreter, for example, a syntax error.
The syntax error message is stored in the special variable erroInfo and can be viewed using the show script command in Exec mode. Another example of TCL errors would cause the TCL interpreter to abort and call panic.
•A stopped script—Caused by an infinite loop and wait indefinitely for a response. Each script must complete its task within the configured time interval. If the script does not complete its task, the script controller terminates the script, and the suspect is failed implicitly.
•Error conditions—Occurs when a connection timeout or a peer-refused connection is also treated as an implicit failure.
Table A-7 shows all exit codes used in the ACE.
Example for Writing a Probe Script
This example shows how a script is written to probe an HTTP server using a health script:
# get the IP address of the real server from a predefined global array
# scriptprobe_env
set ip $scriptprobe_env(realIP)
set port 80
set url "GET /index.html HTTP/1.0\n\n"
# Open a socket to the server. This creates a TCP connection to the
# real server
set exit_msg "opening socket"
set sock [socket $ip $port]
fconfigure $sock -buffering none -eofchar {}
# Wait for the response from the server and read that in variable line
set exit_msg "receiving response"
set line [ read $sock ]
# Parse the response
if { [ regexp "HTTP/1.. (\[0-9\]+) " $line match status ] }
# Close the socket. Application MUST close the socket once the # request/response is over.
# This allows other applications and tcl scripts to make
# a good use of socket resource. Health monitoring is allowed to open
# only 200 sockets simultaneously.
set exit_msg "closing socket"
close $sock
# decide the exit code to return to control module.
# If the status code is OK then script MUST do exit 30001
# to signal successful completion of a script probe.
# In this example any other status code means failure.
# User must do exit 30002 when a probe has failed.
if { $status == 200 } {
set exit_msg "probe success"
exit 30001
} else {
set exit_msg "probe fail : can't find status code"
exit 30002
Displaying Script Information
The following sections provide information for displaying scripted probe and script information:
•Displaying ACE Script and Scripted Probe Configuration
•Displaying Scripted Probe Information
•Displaying Global Scripted Probe Statistics
•Displaying the Statistics for an Active Script
•Displaying the Script Contents
Displaying ACE Script and Scripted Probe Configuration
You can display configuration information for scripts and scripted probes on the ACE by using the show running-config command in Exec mode. For example, enter:
switch/Admin# show running-config
Generating configuration....
logging enable
boot system image:
script file name ftp1.tcl
probe scripted bts_test_probe
interval 10
receive 8
script test.tcl
rserver host bts_test_rserver
ip address 10.86.209.1
probe bts_test_probe
inservice
snmp-server user www Network-Monitor
snmp-server user admin Network-Monitor
context Admin
...
Displaying Scripted Probe Information
You can display configuration and probe result information about scripted probes by using the show probe command in Exec mode. The syntax of this command is as follows:
show probe scripted_probe_name [detail]
The keyword, argument, and option are as follows:
•scripted_probe_name—Information for the specified scripted probe name.
•detail—(Optional) Displays detailed probe information including configuration information and statistics.
If you do not enter a probe name, this command shows a summary of information for all configured probes.
For example, to view the SCRIPT-1 scripted probe and detailed information, enter:
host1/Admin# show probe SCRIPT-1 detail
Table A-8 describes the fields in the show probe command output for a scripted probe.
|
|
|
|---|---|
probe |
Name of the probe. |
type |
Probe type. |
description |
Configured string that describes the probe. |
port |
Port number that the probe uses. By default, the probe uses the port number based on its type. |
address |
Not used for scripted probes. |
addr type |
Not used for scripted probes. |
interval |
Time interval in seconds that the ACE sends probes to a server marked as passed. |
pass intvl |
Time period in seconds to send a probe to a failed server. |
pass count |
Number of successful probe replies before enabling failed server. |
fail count |
Consecutive number of failed probes before marking the server as failed. |
recv timeout |
Time period in seconds to receive a server response to the probe. |
script filename |
Script filename. |
probe association |
Serverfarm or real server association. |
probe results |
|
probed-address |
Destination or source address for the probe. |
probes |
Total number of probes. |
failed |
Total number of failed probes. |
passed |
Total number of passed probes. |
health |
Current health of probe: PASSED or FAILED. |
Additional Detailed Output: |
|
Socket state |
Socket state. |
No. Passed states |
Number of passed states. |
No. Failed states |
Number of failed states. |
No. Probes skipped |
Number of skipped probes. |
Last status code |
Last exit code (see Table A-7). |
Last disconnect err |
Message for the exit code (see Table A-7). |
Last probe time |
Timestamp for the last probe. |
Last fail time |
Timestamp for the last failed probe. |
Last active time |
Timestamp for the last active time. |
Internal error |
Counter for the number of internal errors encountered. |
Displaying Global Scripted Probe Statistics
You can display the global statistics for all scripted probes by using the show stats probe type scripted command in Exec mode. For example, enter:
host1/Admin# show stats probe type scripted
Table A-9 describes the fields in the show stats probe type scripted command output.
Displaying the Statistics for an Active Script
You can display the statistics for a script file active on the ACE including exit codes and exit messages by using the show script command from Exec mode. The syntax for this command is as follows:
show script script_name probe_name [rserver_name [port_name]] [serverfarm sfarm_name]
The keywords, arguments, and options are as follows:
•script_name—Name of the script.
•probe_name—Name of the scripted probe that is associated with the script.
•rserver_name [port_name]—(Optional) Name of the real server and optional port number that uses the scripted probe.
•serverfarm sfarm_name—Specifies the name of the server farm that uses the scripted probe, enter.
For example, to display the statistics for the ECHO_PROBE_SCRIPT script for the SCRIPT1 probe, enter:
host1/Admin# show script ECHO_PROBE_SCRIPT SCRIPT1
Table A-10 describes the fields in the show script command output.
|
|
|
|---|---|
Script |
Name of the script. |
Scripted probe |
Probe associated with the script. |
Probe-association(s): (count=number) |
Total number of real servers and server farms associated with the scripted probe. |
Rserver/Serverfarm |
Name of the real server or server farm for the script statistics. |
Exit code |
Current exit code for the script. See Table A-7 for information on exit codes. |
Child PID |
Child process identifier for the script. |
Exit message |
Value of the TCL gset variable from the script. |
Panic string |
Indication of an internal problem with the TCL interpreter. |
Internal error |
Error code message associated with the exit code. |
Last RunStart count/Last RunStart time |
Number of times that the script successfully started and the last time stamp. |
Last RunEnd count/Last RunEnd time |
Number of times that the script successfully ended and the last time stamp. |
Last Probe OK count/ Last Probe OK time |
Number of times that the scripted probe passed and the last time stamp. |
Last ProbeFail count/ Last ProbeFail time |
Number of times that the scripted probe failed and the last time stamp. |
Last ForkFail count/ Last ForkFail time |
Number of times that the fork failed and the last time stamp. |
Last Kill count/ Last Kill time |
Number of times that the script probe failed due to timeout and the last time stamp. |
Last Panic count/ Last Panic time |
Number of times that there was an internal problem with the TCL interpreter and the last time stamp. |
Last Nodecreate Error count/Last Nodecreate Error time |
Number of times that the ACE ran out of memory for the TCL worker thread node and the last time stamp. |
Last Unassociated Script count/ Last Unassociated Script time |
Number of times that the script in memory could not be associated and the last time stamp. |
Last Fail Internal/ Last Fail Internal |
Number of times that the script had an internal syntax error and the last time stamp. |
Last Socket-Limit count/ Last Socket-Limit time |
Number of times that the ACE ran out of sockets for the TCL script and the last time stamp. |
Last PV-Read count/ Last PV-Read Time |
Number of times that the persistent variable table was read and the last time stamp. |
Last PData-Null count/Last PData-Null time |
Number of times that the probe data pointer is null and the last time stamp. |
Last Unknown count/ Last Unknown time |
Number of times that the script passed an error code that is not recognized and last time stamp. |
Displaying the Script Contents
You can display the contents for a script file loaded on the ACE by using the show script command from Exec mode. The syntax for this command is as follows:
show script code script_name
The keyword and argument are as follows:
•code—Displays the code within the script file.
•script_name—Name of the script.
For example, to display the code within the ECHO_PROBE_SCRIPT script, enter:
host1/Admin# show script code ECHO_PROBE_SCRIPT
Debugging Probe Scripts
You can debug a script probe by doing the following:
•Use the EXIT_MSG variable in the script. Each probe suspect contains its own EXIT_MSG variable. This variable allows you to trace the status of a script and check the status of the probe.
This example shows how to use the EXIT_MSG variable in a script:
set EXIT_MSG "before opening socket"
set sock [ socket $ip $port]
set EXIT_MSG " before receive string"
gets $s
set EXIT_MSG "before close socket"
close $s
If a probe suspect fails when receiving the message, you should see EXIT_MSG = before you receive the string. You can view the EXIT_MSG variable with the show script command in Exec mode.
•Use the show probe command in Exec mode to view the current active probe suspects in the system. For more information on this command, see the "Displaying Script Information" section.
•Use the show script command in Exec mode to view the following:
–The last exit status with the exit code number.
–The internal error that is generated by the TCL compiler. When the script has a TCL runtime error, the TCL interpreter stops running the script and the ACE displays this error.
–The EXIT_MSG variable value of the TCL gset command from the script.
Feedback