TCP Probe Command Reference

The following commands are defined in the Intermapper TCP Probe Scripting Language. For an example of a custom probe script, see the Annotated Example of the FTP (Login) Script.

Device I/O Commands

The following commands send data to the device or read one or more lines from the input (from the connection to the device being tested). Each command that reads a device compares its string to the current line, which is the most recently-read line from the connection. If there is no current line (for example, if a SEND command has been executed), these statements read one or more lines to get the current line.

• EXPT "string" #fail - searches incoming lines for the specified string.
• MTCH "string" #fail - searches the next incoming line for the specified string.
• SKIP "string" #fail - ignores all incoming lines containing the specified string.
• DISC #discfail - jumps to a specified line number if the probe is suddenly disconnected.
• CONN #timeout ["TELNET"]["SECURE"] - specifies the connect timeout of the probe and whether to process Telnet options.
• RCON - reconnects to the specified server and port.
• PORT #port_num #connect_timeout - this is no longer required (the remote port number is now a separate parameter in the configuration dialog).
• LINE [ON | OFF] - specifies whether the script reads incoming data as lines or as raw data.
• NEXT - clears the input buffer so that subsequent MTCH commands operate on newly-received information.
• SEND "string" - sends the specified string to a remote device.
• BRCV {BER sequence} - receives TCP data and decodes from BER format into a local format.
  
• BSND {BER sequence} - encodes local data in BER format and sends. See LDAP probes for examples and syntax.

Commands That Control Script Flow

The following commands control the order of operations in the script:

• CHCK "string" #fail - determines if the string is not empty.
• DONE status ["message"] - terminates a script with a specified condition.
• EXIT - terminates a script with the condition specified previously by STAT.
• FAIL - specifies the line to jump to if a CONN command fails to connect.
• GOTO #statement - branches immediately to the specified statement number.
• NBGT #arg1 #arg2 #line - (Numeric Branch Greater Than) branches to #line if #arg1 is greater than #arg2.
• NBNE #arg1 #arg2 #line - (Numeric Branch Not Equal) compares two numeric arguments and branches to the indicated line if they are not equal.
• SBNE "arg1" "arg2" #line - (String Branch Not Equal) compares two string arguments and branches to the indicated line if they are not equal.
• STAT status ["message"] - specifies the status condition of a script when it ends.
• WAIT #secs #idlefail #discfail - specifies the number of seconds the probe waits for a response.

String Processing Commands

The following commands process and manipulate strings:

• EVAL $result := expression - assigns the evaluated value of expression to ${result}.
• STOR "variable" "string" - stores the string into the variable named variable.
• SCAT "variable1" "variable2" #fail - concatenates variable1 and variable2, placing the resulting string in variable1.
• NADD "variable" #number - (Numeric Add) adds a numeric value to a variable.

Commands That Measure Time

• STRT - starts a millisecond timer that Intermapper can use to determine the elapsed time for an event.
• TIME "variable" - sets the named variable to the current number of milliseconds from the most recent STRT command.
• WAIT #secs #idlefail #discfail - specifies the number of seconds the probe waits for a response.

Probe Command Details - Alphabetical

BRCV {BER Sequence}

Receives TCP data and decodes from BER format into a local format, checking for expected tags and values as indicated. BER stands for Basic Encoding Rules for ASN.1. See LDAP probes for examples and syntax.

Intermapper- specific BER syntax required information:

• { - starts a sequence (sequences can be nested)
• } - ends a sequence
• [ - starts a hexadecimal tag
• ] - ends a hexadecimal tag
• # - indicates that a literal number follows
• " - begins and ends a literal string

Example

BRCV { #1, [61]{ [0A]#ENUM, "", "" } } else @PARSE_ERROR

BSND {BER sequence}

Encodes local data in BER format and sends. BER stands for Basic Encoding Rules for ASN.1. See LDAP probes for examples and syntax.

Example

BSND { #1, [60]{ #3, "${Bind Name}", [80]"${Bind Password*}"} }

CHCK "string" #fail

Use the CHCK command to determine if the string is not empty. If the string is empty, the script jumps to the specified fail line.

This command can be used to construct scripts whose control changes depending on whether an optional parameter is supplied.

Possible failures - None

CONN #timeout ["TELNET"]["SECURE"]

Use the CONN command to specify the connection timeout of the probe and whether to process Telnet options.

If you use the CONN command, it must be the first statement of the script. When the script executes, the parameters of the CONN statement determine the options Intermapper uses to connect to the remote computer.

#timeout - specifies the number of seconds to wait while trying to connect before giving up.

"TELNET" - i f the second parameter of the CONN command is "TELNET" (including the quotation marks), then the connection is created in a mode where the TCP stream automatically processes and negatively acknowledges incoming Telnet options. This allows the Telnet probe to ignore the telnet options and work in line-by-line mode for the remainder of the script.

SECURE - creates an SSL connection, places the word SECURE at the end of the line.

SECURE:ADH - uses anonymous Diffe-Hellman key exchange.

SECURE:NO_TLS - TLSv1 is disabled when making a secure connection. The HTTPS (SSLv3) probe uses this option.

Possible Failures - None

DISC #discfail

Use the DISC command to cause the script to jump to a specified line number if the probe is suddenly disconnected. You can use this command to identify scripts that fail because of a TCP disconnection.

The script disconnect line can also be set using the third parameter to the WAIT command.

DONE status ["message"]

Use the DONE command to terminate the script with one of the following conditions: 

[OKAY | WARN | ALRM | DOWN]

The optional message parameter allows you to provide more detail about the condition. The status values for the DONE command must be in upper case .

Example

DONE ALRM "[HTTP] 500 Response received."

This example sets the status of the device to ALRM. The condition of the device (displayed in the device Status window and the Device List window) is set to [HTTP] 500 Response received. to provide you with an indication of the reason for the alarm.

Possible Failures - None

Tip - If the final statement of your script is not a DONE command, the script automatically terminates with a DONE OKAY status.

EVAL $result := expression

Assigns a value to the variable in ${result} based on expression.

This expression can use any operator or function defined in Probe Calculations. Using this expression, you can perform variable assignments, arithmetic calculations, relational and logical comparisons, as well as use built-in functions to perform bitwise, rounding, and mathematical operations. You can also perform operations on strings using regular expressions.

Examples

-- Simple Assignment EVAL $msgstring := $otherstring --Simple subtraction of numeric values EVAL $newopen := $fileopen - $prevfileopen --Use of function and conditional logic EVAL $prevtest := defined("test") == 1 ? $test : 0 --Use of regular expression EVAL $msg_part := ($msg =~ "(.*)| *([^|]+)$")

Numerous examples that use the EVAL command can be found in the built-in TCP probes.

EXIT

Use the EXIT command to terminate the script. This sets the status and condition string to whatever is specified by a previous STAT command.

EXPT "string" #fail

Use the EXPT command to EXPecT or search for the specified string in any number of incoming lines.

• If the string is found, the script goes to the next statement.

• If the string is not found, the script goes to the statement specified in the fail parameter.
  

  NOTE:

  • EXPT is identical to MTCH, except in the following ways:
    • MTCH fails if the next line or block does not match what is specified.

    • EXPT keeps going until it finds a line or text block that matches what is specified.

  • Both EXPT and MTCH can use regular expressions. For more information, see String Matching.
    

Example

EXPT "220 " #14

Possible Failures

The EXPT command can fail if the expected text is not received before the connection closes. In that event, the script goes to the statement specified by #fail.

However, if the timeout specified by a previous WAIT command expires before the connection closes, the script goes to the #idlefail line specified by the WAIT command instead.

FAIL #

Specifies the line number to go to if the probe fails to connect. The FAIL command must follow immediately after a CONN command line.

Possible Failures 

If the statement number is out of bounds, the script terminates with a DONE command and DOWN status.

GOTO #statement

Use the GOTO command to branch immediately to the specified statement number.

Possible Failures

If the statement number is out of bounds, the script terminates with a DONE command and DOWN status.

LINE [ON | OFF]

Use the LINE command to specify whether the script should read incoming data as lines or as raw data.

Tip - After you match some data in LINE ON mode, you should not match any more because your position in the buffer is not restored and you might miss something.

Possible Failures - None

MTCH "string" #fail

Use the MTCH command to MaTCH, or search for the specified string in the next incoming line. If found, the script falls through to the next statement.

Example

MTCH "331" #16

If the next incoming line does not contain the desired string or if the connection closes before the next line can be read, this script fails. In either case, the script goes to the statement specified by #fail.

If the idle timeout expires, the script jumps to the #idlefail line specified by the previous WAIT command.

NADD "variable" #number

The NADD (Numeric Add) command adds a numeric value to a variable. The variable is looked up and converted to a numeric value. The number is added and the result is converted to a string and placed in the variable.

Example

NADD "fred" #3
adds 3 to the "fred" variable value. If "fred" contains 3, the result is 6. If "fred" contains golf, the result is 3 (because the conversion from a string to a number yields 0).

If the number is missing, the script adds 0 to the value.

Possible Failures None

NBGT #arg1 #arg2 #line

Use the NBGT (Numeric Branch Greater Than) command to branch to #line if #arg1 is greater than #arg2.

Example

NBGT #${arg1} #${arg2} @exit
branches to the @exit label if the ${arg1} numeric is greater than the ${arg2} numeric.

Possible Failures None

NBNE #arg1 #arg2 #line

The NBNE (Numeric Branch Not Equal) command compares the two numeric arguments and branches to the indicated line if the arguments are not equal.

Example

NBNE #${arg1} #${arg2} @exit branches to the @exit label if the ${arg1} numeric is not equal to the ${arg2} numeric.

Possible Failures None

NEXT

The NEXT command clears the input buffer (represented by the ${LINE} variable) so subsequent MTCH commands operate on newly-received information.

Possible Failures None

PORT #port_num #connect_timeout

Deprecated This command is no longer required in a script because the remote port number is now a separate parameter in the configuration dialog.

If present, this command must be in the first statement of the script. The first parameter specifies the default TCP port to connect to on the remote computer. The #connect_timeout parameter is the number of seconds to wait for the probe to connect.

Possible Failures None

RCON

Takes no parameters.

See the Barracuda probes for examples and syntax.

Possible Failures None

SBNE "arg1" "arg2" #line

The SBNE (String Branch Not Equal) command compares the two string arguments and branches to the indicated line if the arguments are not equal.

Example

SBNE "${arg1}" "${arg2}" @exit
branches to the @exit label if the string ${arg1} is not equal to ${arg2}.

Possible Failures None

SCAT "variable1" "variable2" #fail

The SCAT (String ConCATenate) command concatenates variable1 and variable2 and places the resulting string in variable1.

Example

STOR "name" "Fred"
sets the variable ${name} to the string "Fred"

SCAT "name" "Flintstone" @TOO_LONG
sets the variable ${name} to the value "FredFlintstone"

Possible Failures If the sum of the lengths of the strings exceeds 65,535 characters, the SCAT command fails and transfers to the @TOO_LONG label.

SEND "string"

Use the SEND command to send the specified string to the remote device.

To send a line of data, you must explicitly specify the CR-LF using the quotation convention.

Example

SEND "Greetings!\r\n"
transmits the data "Greetings!" followed by a CR-LF.

Possible Failures This command cannot fail. If the data cannot be sent because of a network failure or device failure, the failure appears in a subsequent EXPTor MTCH command.

SKIP "string" #fail

Use the SKIP command to ignore all incoming lines containing the specified string. The script falls through to the next statement when an incoming line does not contain the string.

Possible Failures

If the connection closes unexpectedly, the script jumps to #fail.
If the WAIT timeout (as defined by the WAIT command) expires, the script jumps to #idlefail.

STAT status ["message"]

Use the STAT command to specify the status of the device when the script ends. This command does not terminate the script. You can also specify a condition string as the second argument.

The status must be one of the following:

[OKAY | WARN | ALRM | DOWN | CRIT]

Example

STAT ALRM "[HTTP] 500 Response received."

STOR "variable" "string"

The STOR command stores the string into the variable named variable. You can set a variable to a numeric value by enclosing the number in double quotation marks (" "). Subsequent parts of the script refer to this variable as ${variable}.

Examples

STOR "fred" "foobar"
sets the variable fred to the text string foobar. Subsequent parts of the script can refer to this variable as ${fred}.

STOR "fred" "3"
sets the variable "fred" to the string value "3".

Possible Failures None

STRT

The STRT command starts a millisecond timer that Intermapper can use to determine the elapsed time for some event. See the TIME command.

Example

STRT Starts the timer.

Possible Failures None

TIME "variable"

The TIME command sets the named variable to the current number of milliseconds from the most recent STRT command.

Example

TIME "connecttime"
sets the variable connecttime to the number of milliseconds since the most recent STRT command. If there was no previous STRT command, the variable will be set to zero.

Possible Failures None

WAIT #secs #idlefail #discfail

Use the WAIT command to specify the number of seconds the probe waits for a response.

Parameter 1 - #secs - the number of seconds to wait for a response. If you do not include a WAIT command in your script, the default timeout is 60 seconds.

Parameter 2 - #idlefail - If present, the script goes to this line number if the probe is idle for the specified number of seconds. This idle handler supercedes the error line number specified by the EXPT, SKIP, or MTCH commands. If the #idlefail parameter is not included, the script branches to the failure handler of the current command.

Parameter 3 - #discfail - If present, the script goes to this line if the probe is unexpectedly disconnected. This allows you to identify scripts that fail because of a TCP disconnection.

Possible Failures None

Tip: You should specify all three parameters in the WAIT command.

Annotated Example of the FTP (Login) Script

01) PORT #21 (default tcp port)
02) WAIT #30 seconds
03) EXPT "220 " else goto -1- #14
04) SEND "USER ${User ID}\r\n"
05) MTCH "331" else goto -2- #16
06) SEND "PASS ${Password}\r\n"
07) MTCH "230" else goto -3- #20
08) SEND "NOOP\r\n"
09) MTCH "200" else goto -4- #24
10) SEND "QUIT\r\n"
11) EXPT "221" #+1 (i.e. can't fail)
12) DONE OKAY
13)
14) DONE DOWN "[FTP] Unexpected greeting from port ${_REMOTEPORT}. ${_LINE:50})" -1-
15)
16) MTCH "500" else goto #+2 -2-
17) DONE ALRM "[FTP] Port ${_REMOTEPORT} did not recognize the 'USER' command."
18) DONE ALRM "[FTP] Unexpected response to USER command. (${_LINE:50})"
19)
20) MTCH "530" else goto #+2 -3-
21) DONE WARN "[FTP] Incorrect login for \"${User ID}"."
22) DONE ALRM "[FTP] Unexpected response to PASS command. (${_LINE:50})"
23)
24) DONE ALRM "[FTP] Unexpected response to NOOP command. (${_LINE:50})"

Explanation of the Script

01) PORT #21 (default tcp port)
02) WAIT #30 seconds

Line 1 - the PORT command at the beginning of the script specifies the default TCP port number for FTP, port 21.

Line 2 - the WAIT command specifies that the script fails if it does not receive responses back within 30 seconds.

03) EXPT "220 " else goto -1- #14

Line 3 - FTP servers normally send one or more "220" lines to greet new FTP control connections. Our script scans the incoming lines for "220 ".

Note the space following the 220; we do not want to match an incoming "220-"; the incoming dash indicates there are still more 220 lines to be read but we only want to match the final 220 line.

If the script fails to find "220 " before the connection closes or within 30 seconds, the script branches to statement 14. The "-1-" is an arbitrary label used to make the destination of the branch more easily visible.

The else goto -1- string has no function (except readability) in the script command text. This statement can also be written as EXPT "220 " #14 . Note that statement #14 also has comment of "-1-" to show it is the destination.

04) SEND "USER ${User ID}\r\n"

Line 4 - sends the FTP USER command. With this command, we send the user ID specified by the user, for example, anonymous. Note that you must include the carriage-return and line-feed at the end of the string sent, to denote the line ending.

05) MTCH "331" else goto -2- #16

Line 5 - the script looks for the 331 response to the USER command.

If something else arrives, the script goes to statement 16. Unlike the EXPT command, the MTCH command fails immediately if the next line does not contain the required text.

[...] (Skipping down to statement 16).

16) MTCH "500" else goto #+2 -2-
17) DONE ALRM "[FTP] Port ${_REMOTEPORT} did not recognize the \"USER" command."
18) DONE ALRM "[FTP] Unexpected response to USER command. (${_LINE:50})"

Line 16 - statement 16 is executed only if statement 5 fails; meaning, if an unexpected response to the USER command is received. The response is checked to see if it matches 500, which indicates that the command is not supported. This is possible if you accidentally try to pass the USER command to a TCP service other than FTP.

If the server's response matches 500, the script is terminated with the device in the ALARM status (in statement 17). The message reports that the server did not recognize the USER command.

If the server's response does not match 500, the script skips two lines to statement 18. This statement terminates the script with the ALARM status and uses the ${LINE" } macro to include the first 50 characters of the response line in the message.