Monitors and Services

---

You can define an unlimited number of TCP/IP monitors and services. Once defined, these can be used on any device on your maps.

WhatsUp Gold is shipped with monitors/services already defined for you:

• HTTP Content Scan
• Radius Server (Remote Authentication and Dial-In User Service)
• IMail Server
• WS-FTP Server
• WhatsUp Gold Web Server v5
• WhatsUp Gold Web Server v6
• WhatsUp Gold Web Server v7
• WhatsUp Gold Web Server v8

You can define additional TCP services. For example, you may want to monitor an IRC (Internet Relay Chat) service, a Lotus Notes server, a Microsoft SQL server, or a Microsoft Exchange service.

If you are running any common services (like SMTP, POP3, etc.) on a non-standard port number, you can also edit their definitions.

Defining a Custom TCP/IP Service

The monitoring of a service always involves a protocol handshake and can also include some additional information exchange between WhatsUp Gold and the service. You can search the response from the service for an exact match of a particular text string, or you can use rule expressions to analyze the response for a more generic text pattern.

For example, if you are looking for any error message, and you know that all possible error messages have the word "fail" in common, you can use a rule expression to look for just the word "fail." Or, you can create a rule expression that looks for any number of possible error messages. You can search for "this," "that," or "the other."

To define a custom TCP/IP service:

1. From the Configure menu, Select Monitors & Services. You see the following dialog box.
   

You can do the following from this dialog box:

• Click New to create a new custom service or monitor.
• Click Edit to edit a custom service or monitor. (First select the service you want to edit.) You can also double-click the desired service or monitor to edit it.
• Click Copy to copy a custom service or monitor. (First select the service you want to copy.)
• Click Delete to delete a custom service. (First select the service you want to delete.)

2. Click the New button.
   
3. From the Service Type list box, select TCP/IP Service.
4. In the Service Name text box, enter a unique name for the service. This name will be displayed as a selectable option on the Services dialog box of the device properties.
5. Click OK.

6. Select a Network Type. Select the TCP or UDP network type.
   • Example: The network type for the IRC (Internet Relay Chat) service is TCP.
   • Example: The network type for the RADIUS (Remote Authentication and Dial-In User Service) service is UDP.
7. Select a Port Number. Enter the TCP or UDP port that you want to monitor.
   • Example: 6667 is the port number for the IRC (Internet Relay Chat) service.
   • Example: 1645 is the port number of the RADIUS (Remote Authentication and Dial-In User Service) service.
8. Set the Timeout in Seconds.

Note: Since some devices may be at a different site or may take longer to respond, you can change the default amount of time that WhatsUp Gold waits for a response from the device. This can be from 1 to 500 seconds; or from 501 to 999 milliseconds. In other words, if you enter a value greater than 500, the value is interpreted as milliseconds.

9. Enter your script. It can be any length and can use the keywords and rules expressions described in the following sections.
10. Click OK to save the custom service.
11. You can now turn on monitoring of the service on any device in any network map.

Script Syntax

Note: You create a script using keywords. In general the Script Syntax is Command=String. Command is either Send, Expect, SimpleExpect, or Flow Control. A script can have as many send and receive lines as needed. However, the more you have, the slower the service checking.

Keywords.

• To send a string to a port, use the Send= keyword.
• To expect a string from a port, use the SimpleExpect= or Expect= keyword.
• To comment out a line, use the # symbol as the first character of the line.
• To have conditional responses on "error" or "success" of a step within the scripts, use Flow Control Keywords.

Examples:

• To compare responses byte-by-byte (expanding escape codes as you go), use a SimpleExpect= keyword. For more information, see "SimpleExpect Keywords".
• To Expect on connect, use an Expect= keyword. Enter either an exact text string or a rule expression that you expect the remote service to send to you when you connect. To view the Rule Expression Editor, click the Browse button. For more information on composing a rule expression, see "Using Rule Expressions".
• To Send command on connect, use a Send= keyword. Enter the command to send to the service's port. For example: for IRC (Internet Relay Chat), the send command is: "Version\r\n"
• To Expect a command response, use another Expect= keyword. Enter an exact text string or a rule expression that represents the expected response to the "Send" command. For example: for IRC, this is ":irc"
• To Send to disconnect, use a Send= keyword. Enter a command string to disconnect from the service properly. For example: for most TCP/IP servers, the string QUIT\r\n is proper. If a command string is not specified, the connection is closed by sending a FIN packet and then an RST packet.

Note: Depending on the plug-ins you have installed, there are many other services/monitors you can define. Others include: DNS Monitoring, Telnet Monitoring, SNMP Monitoring, and NT Service. See the WhatsUp Gold help topic: "Plug-Ins" for more information.

SimpleExpect Keywords

Keyword	Description
%nnn	Binary value (for example %000 is null, %027 is escape)
.	Matches any character
\%	The "%" character
\.	The "." character
\\	The "\" character

Flow Control Keywords

The script language has been expanded to have conditional responses on "error" or "success" of a step within the scripts. This is done by using the following keywords.

IfState - This checks for the current state (ok or error) and jumps to a label if true.

Valid syntax: IfState {ERR|OK} label

Example: IfState ERR End
IfState OK Bye

Goto - This immediately jumps to a label.

Valid syntax: Goto End

Example: Goto End

Exit - This immediately ends the script with an optional state (ok or error). The optional state overrides the current state.

Valid syntax: Exit {ERR|OK}

Example: Exit ERR
Exit OK

:Label - This defines a label that can be the target of a jump. A label is defined by a single word beginning with the ":" character.

Valid syntax: (with a name following)

Example: :Bye

OnError - This allows for a global handling of an error situation.

Valid Syntax: OnError {EXIT|CONTINUE|GOTO} label

Example: OnError EXIT (Default behavior)
OnError CONTINUE
OnError GOTO Logoff

Using Rule Expressions

The rule expression syntax is:

search_text quantifier

Note that search_text can be any combination of literal text and the text patterns shown below.

To create a rule expression:

1. In the "Monitors & Services" dialog box shown on page 86, click the Add/Edit Expect Rule button to view the Rule Expression Editor.
   
   
2. Select the contains option to look for messages that contain the search string; select Doesn't contain to look for messages that do not contain the search string.
3. Select Match Case to search for text that matches the case of the search string; to ignore case, make sure Match Case is cleared.
4. Enter the expected text by doing one or more of the following:
   • Type the literal text that you want to search for. For example, if you want to find the word fail, type fail.
   • Type the text and quantifiers you want to search for; see "Rule Expressions Text and Quantifiers Tables".
   • Click Insert Expression to insert a generic form of a text pattern or a quantifier. Then edit the inserted expression. See "Rule Expressions Text and Quantifiers Tables" below.
5. Click OK to save the rule.

Rule Expressions Text and Quantifiers Tables

Text Pattern	Expression
Placing this in the first position (before any other expression) causes the search engine to start comparison with the first byte in the received buffer.	^
Match any character	.
Match X or Y	(x/y)
Match any word character (a-z, A-Z, 0-9)	\w
Match any non-word character	\W
Match any digit (0-9)	\d
Match any non-digit	\D
Match any white space (spaces and/or tabs and/or carriage returns)	\s
Match any non-white space	\S
Match any punctuation character (any printable character other than a space or alphanumeric characters)	\p
Match any non-punctuation character	\P
Match `.'	\.
Match Binary value	%nnn where nnn is a number between 000 and 255

Quantifier	Expression
Match Zero or more	*
Match One or more	+
Match n times	{n}
At least n, but not more than m (where n and m are numbers)	{n,m}

Note: As shown above, the following characters have special meaning in a rule:

{}()|*+,.%\ 

If you want to use one of these characters in a search string, precede it with a backslash.

For example, to search for a plus sign, enter \+ in the search string.

Testing a Rule Expression

To test a rule expression, you use the Rule Expression Editor.

1. If the Rule Expression Editor is not visible, from the Configure menu, select Monitors & Services. Then, select the rule you want to test. Click the Add/Edit Expect Rule button to view the Rule Expression Editor.
2. In the lower text box of the Rule Expression Editor, copy a message that meets your intended search criteria, select Contains, and click Test Expression.
   

   If the rule expression does what you intended it to, The Comparison Text MATCHED the Pattern Specified is displayed.

   

   If the rule expression doesn't test true, The Comparison text DID NOT MATCH the pattern specified is displayed. Edit the rule expression and test again. For a long or complex rule expression, we recommend you test one part of it at a time.

Defining an SNMP Object to Monitor

Once you install the SNMP Monitor Plug-In, you can monitor SNMP objects on a device.

Note: The device must be SNMP manageable because that is where the community string information is entered.

You can define the SNMP object (and instance) to monitor.

1. From the Configure menu, Select Monitors & Services. You see the following dialog box.
   

You can do the following from this dialog box:

• Click New to create a new custom service or monitor.
• Click Edit to edit a custom service or monitor. (First select the service you want to edit.)
• Click Copy to copy a custom service or monitor. (First select the service you want to copy.)
• Click Delete to delete a custom service. (First select the service you want to delete.)

2. Click the New button.
   
3. From the Service Type list box, select SNMP Monitoring.
4. In the Service Name text box, enter a unique name for the service. This name will be displayed as a selectable option on the Services dialog box of the device properties.
5. Click OK.
   
6. Click the Browse button next to the Object ID box; then, locate and select the appropriate SNMP object in the MIB object tree.
7. In the Check it for list box, there are three selections you can choose. Depending on whether you select Constant Value, Range of Values, or Rate of Change in Value, your dialog box will change accordingly. Click Help to learn about the different possibilities.

Ipswitch, Inc. http://www.ipswitch.com

©Ipswitch 2003