[ Main Index | ipSentry Application Index ]
 

The ipSentry Scripted TCP/IP Network Monitoring Add-In provides you with a simple TCP/IP based scripting monitor allowing you to script commands that would normally be entered manually in order to provide a more in-depth monitoring of various TCP/IP base hosts such as SMTP, POP3, FTP, and others.

From the Scripted TCP/IP Network Monitor configuration window, click the NEW or EDIT buttons for the TCP Script.

The TCP Scripting add-in is based on a simple Connect, Send, Receive, Wait, and Quit dialogue type logic. 

In this document, we will breakdown the logic of the sample FTP Script that is provided with the add-in to outline several key features and requirements of the scripting logic.

Scripted TCP/IP Network Monitor Configuration - Script Editor

Scripted TCP/IP Network Monitoring Add-In

The script above performs the task of connection to an FTP server, logging in as an anon user, setting the FTP PASV mode since no secondary port is opened for standard FTP, perform a directory change, and then quit.

If a failure occurs at any point, the add-in return a CRITICAL state to ipSentry thus triggering any failure alerts which have been configured.

This is a transcript of a session with our FTP server that we will emulate via the TCP/IP Scripting monitor.

220-Microsoft FTP Service
220 FTP Server of RGE, Inc.
USER ANONYMOUS
331 Anonymous access allowed, send identity (e-mail name) as password.
PASS @here.now
230-Welcome to the FTP Server of RGE, Inc.
Home of ipSentry Network Monitoring Software
Visit https://ipsentry.com
230 Anonymous user logged in.

PASV
227 Entering Passive Mode (12,100,48,226,86,174).
CWD /pub/ipsentry
250 CWD command successful.
quit
221 Goodbye

The lines in blue contain data received from the host and the lines in black contain the data/commands that we are sending to the host.

Here is a line-by-line descriptive of the script displayed above.

#Comments
Lines beginning with a sharp sign (#) are considered comments and perform no function.  Use this option to add comments to your script for reference when editing in the future.

WAITCONNECT <TIMEOUT>
This line uses the WAITCONNECT keyword which causes the script to begin the connection process and establish a TCP connection with the remote host on the specified port as displayed on the main configuration.
If the connection can not be obtained within <TIMEOUT> seconds, the script will fail.

WAITQUIET 1
This line will cause the script to wait until there has been one second of quiet on the connection.  That is, there has been no data received from the host.

SEND "USER anonymous<CRLF>"
This line sends the USER logon sequence.

WAITFOR 2 "331"
This line will wait for up to 2 seconds for the FTP server to return the 331 response code.

SEND "PASS @here.now<CRLF>"
This lines sends our password to the host.

WAITFOR 2 "logged in."
We will wait up to 2 seconds for logon initialization to occur and received the "logged in." response.

SEND "PASV<CRLF>"
We want to enter passive mode on the FTP server so we send the PASV command.

WAITFOR 3 "Entering Passive Mode"
Wait for up to 3 seconds to enter passive mode.

WAITQUIET 1
Wait for 1 second of quiet on the TCP/IP connection.

SEND "CWD /pub/ipSentry<CRLF>"
Send the command to change directories to /pub/ipSentry

WAITFOR 1 "250 CWD command successful."
Wait for successful command response within 1 seconds.

NOFAIL
Everything we want to check has been accomplished.  From this point, no failures in the script will be counted as failures.

SEND "QUIT<CR>"
Send the QUIT command to be kind to the server.

WAITQUIET 1
Wait for 1 second of quiet time on the TCP/IP connection.

QUIT
Quit the script.  Notice this is not the same as sending the "QUIT" command to the server.  The QUIT command terminates the scripting regardless of any lines that might be contained after this command.

As you can see, the scripting functionality is quite intuitive.  We are simply sending data and expecting data.

The Commands
The TCP/IP Scripting contains a small set of commands that can be used.  The command set has been left intentionally been kept small and concise in order to minimize the learning curve required to create a TCP script.

SEND
Syntax: SEND "data to send with script keywords"
Used to send data to the currently connected host.  If the connection is dropped before or during the send, it will fail.  If the remote host can not accept the data in it's entirety, the script will fail.
The data that is to be sent MUST be enclosed within quotations.

If you need to send special characters such as a quote, or binary data, please see scripting escape codes for the keys and escape sequences that should be used in their place.

e.g.  To send a Return followed by a Line Feed (ASC[13]ASC[10]) you would use the keyword <CRLF>
Example: SEND "User myusername<CRLF>"

WAITFOR
Syntax: WAITFOR seconds "text to wait for"
Used to wait for specific data to be received within the specified amount of time.  If the data is not received within the specified # of seconds, the script will fail.  The text that is to be received MUST be enclosed within quotations.

If you are expecting to received characters such as a quote, or special characters, please see scripting escape codes for the keys and escape sequences that should be used in their place.

e.g.  To await a Return followed by a Line Feed (ASC[13]ASC[10]) you would use the script keyword <CRLF>
Example: WAITFOR 5 "MyDataLine<CRLF>"

WAITQUIET
Syntax: WAITQUIET seconds
Waits for the inbound connection to be quite for the specified # of seconds.  This command should be used only when you know that quite time will occur on the connection as it will continue to wait until no data is being received for the # of seconds specified.

WAITCONNECT
Syntax: WAITCONNECT seconds
Starts the connection to the specified host.  If the connection can not be established within the number of seconds specified, the script will fail.

DISCONNECT
Syntax: DISCONNECT
Abruptly terminates the TCP/IP connection.

NOFAIL
Syntax: NOFAIL
Removes failure checking from scripted operations that follow this command.  Once you specify NOFAIL in the script, any timeouts or other failures will be ignored and the script will return OK.

QUIT
Syntax: QUIT
Stops script processing.

Script Keywords
There are a few keywords that can be used to represent information that you may not be able to enter directly into the script without disturbing the script file layout.   For example, there is not a method to enter a Return followed by Line Feed  into the script directly.  In this case, you would need to either enter the keyword or escape code for these special characters.

A pre-defined set of keywords or script variables have been defined in order to allow scripts that are created for use with many different pagers, paging functionality through a wide variety of text paging terminals with minimal effort.

These key script variables are replaced with various settings from the pager configuration entry.

The commands available which will ultimately make up the script are as follows:
Note, if you must send data that is exactly identical to a keyword, you will need to escape the < and > using the appropriate ASCII values:
"<" = <\060>
">" = <\062>

<PASSWORD>
This key is replaced by the "Password" field value if you have specified that this monitoring entry uses a password and entered it into the field provided in the main TCP/IP scripting configuration.

<STX>
This key is replaced by ASCII Character 2.

<ETX>
This key is replaced by ASCII Character 3.

<EOT>
This key is replaced by ASCII Character 4.

<ACK>
This key is replaced by ASCII Character 6.

<NAK>
This key is replaced by ASCII Character 21.

<RS>
This key is replaced by ASCII Character 30.

<CR>, ^M
This key is replaced by ASCII Character 13.

<ESC>
This key is replaced by ASCII Character 27.

<LF>
This key is replaced by ASCII Character 10.

<TAB>
This key is replaced by ASCII Character 9.

<QUOTE>
This key is replaced by ASCII Character 34.

<\nnn>
Replaced by the ASCII character (nnn).
e.g.: \013 is the same as <CR> or ^M
e.g.: \034 is the same as <QUOTE> or (")

The Syntax
Each command has a specific syntax as outlined above in the command section.

The most common cause for script failures (non logic failures) is improper syntax of the SEND and WAITFOR commands or simple misspelling of the commands themselves.

More specifically, failure to enclose the data portion within quotes, or leaving the data open-quoted (e.g.: "no end quote ).

Another common failure is neglecting to insert a value in the "WAITFOR" command which specifies how many seconds the script should wait to receive the value (e.g.: WAITFOR "this" is an invalid command. )

Other than the two problems noted above, we believe the scripting engine is designed to be simple and logical requiring no formal programming experience.

The script files provided in the ipSentry distribution can be used as templates and examples for additional help in creating a script for your own specific use.

The Script Files
All TCP scripts must reside in the IPSCRIPTS folder under the directory in which the TCP Scripting add-in is installed.
The default installation path is: \PROGRAM FILES\RGE INC\ipSentryV6\AddIns\IPSTCPSCR\IPSCRIPTS\*.SCR

All scripts must have the file extension of ".SCR".

This is the folder in which ipSentry will look for all available scripts that will be listed in the drop-down box on the script configuration screen.

The first line of each script file will be considered the description or "title" of the script and should be somewhat descriptive.

ipSentry does provide a simple script editor that should be used.  However, you may find using another editor to be more functional when initially setting up and test scripts.

Any line in a script file that begins with a pound sign (#) will be considered a comment line and will be ignored by the script processor.

 



     If you require additional assistance, please visit our on-line support forum at http://forum.ipsentry.com.
 
  Copyright ©1997-2018 by RGE, Inc. - All Rights Reserved
  ipSentry® is a registered trademark of RGE, Inc.
Web Site: https://ipsentry.com
Support Email: support@ipsentry.com