Alertra Script Language 1.9

Alertra Script Language
[next]  [Language Reference]  [table of contents]
Alertra

Alertra Script Language 1.9

This version:
http://www.alertra.com/asl/asl-script-1.9
(Printable version, Gzip'd TAR archive, ZIP archive)
Latest version:
http://www.alertra.com/asl/

Copyright © 2002-2014; Alertra, Inc.

Abstract

This document describes the Alertra Script Language (ASL) script syntax. You can use this document to familiarize yourself with writing ASL scripts. It contains a tutorial and reference sections to show you how to create scripts of your own. ASL scripts drive the agent application used by Alertra to perform protocol checks of Internet resources.

Status of this document

This section describes the status of this document at the time of its publication. Other documents may supersede this document.

This is the 6th release of this document. Changes since the last version include:

  • Language Reference changes to form statement.
  • Language Reference changes to formdata statement.
  • Language Reference changes to http statement.
  • Language Reference changes to https statement.
  • Language Reference addition of parseform statement.

Table of Contents

1. Introduction

Alertra ASL scripts are used by Alertra to perform a check of a given Internet resource. ASL provides mechanisms to specify the Internet resource, provide parameters to the various checks made, and check the results. ASL scripts run on the Alertra's network of remote monitoring stations, no software is installed on customer servers to run ASL scripts.

1.1. Features

ASL can check the following types of Internet resources:

  • FTP File Transfer Protocol Test retrieving files from FTP servers using anonymous logins or user specified credentials.
  • HTTP/HTTPS 1.0 and 1.1 Check your web sites with the ability to handle forms, check for changes to pages, and follow redirections.
  • IMAP4 Connect, get message count, delete messages.
  • MySQL Connect, execute queries, retreive results.
  • Nameserver Query to resolve domain name to IP.
  • PING Send ICMP requests to a server.
  • POP3 Connect, get message count, delete messages.
  • SMTP Connect, send message.
  • SSH Connect, login.
  • TELNET Connect, login.
  • TCP Sockets Using the tcp, send, recv primitives you can test virtually any socket based Internet resource.

Webmasters are continually on the watch for hackers and the possible defacement of their websites. ASL provides several means of detecting that changes have been made to the site:

  • Size Checking ASL can check the size of the content returned from any of the protocol commands and inform you when the size is not correct.
  • Content Checking ASL can also scan the returned content to make sure a particular string is found or not found depending on your requirements.
  • Digest Developed by NIST, SHA computes a one-way hash of the content returned from an HTTP or FTP commands. This hash is like a fingerprint for the content; any changes to the content will result in a different hash. With ASL you can detect changes to the hash and generate an alert accordingly.

1.2. Getting Started

The best way to get started with ASL is to read the Tutorial. In it you will find examples of several common scripts that you can use as a basis for your own scripts. There are also several articles available on site under the heading Scripting: Unlock the Power of Alertra.

2. Tutorial

This tutorial covers some general topics on writing scripts using the Alertra Scripting Language. For more detail discussion of specific topics, please see the Articles section of the Alertra web site under the heading Scripting: Unlock the Power of Alertra

Note: Some of the sample code blocks have been reformatted to fit comfortably within your web browser. Lines that end with the underline character, "_" continue the same statement on the next line. When writing your own ASL scripts, you must include the entire statement on the same line. There is no line-continuation character in ASL.

2.1. Check a Site

The simplest script to write is one that checks an Internet resource and accepts the default actions when the script fails:




# Check the following URL and 
# take the default action if it fails

dns "www.alertra.com"

tcp $HTTP_PORT

http get,redir "/"

The dns call looks up the given host name and stores the IP address for use by the other commands in the script. The tcp call makes a socket connection to port 80 (HTTP_PORT is a predefined constant representing the default connection port for HTTP servers) of the server. The http command actually retrieves the default page from the web server at the selected host. If there is a problem performing any of these tasks, an error is generated and notifications are generated based on the schedule for the script.

We can get a little fancier and check to see if the page has the size we expect and a required key phrase:




# Check a site, make sure the page is the correct

# size and has the given key phrase.

dns "www.alertra.com"

tcp $HTTP_PORT



http get "/login.asp?userid=jsmith&password=pocahontas"

if not "Sample Site Corp" in $CONTENT then begin
	error "Returned page not correct"

end

if not $CONTENT_LENGTH > 1024 then begin
	error "Page not correct size"

end

2.2. HTTP Parameters

We've already seen how you can pass parameters in the URL used to retrieve an HTTP document. Those used the GET method, but you can also use the POST method:




# Pass some parameters to an HTTP form

dns "www.sample.com"

tcp $HTTP_PORT



form userid = "jsmith"

form password = "pocahontas"

http post "/login.asp"

In case you're wondering, the socket connection created by the tcp command doesn't need to be explicitly closed. Any of the other protocol commands (except send and recv) will automatically close the socket.

2.3. Error Handling

If you want, you can change the default error handling used by ASL. Normally, any problem with a command aborts the script immediately and an error notification is sent to all contacts scheduled to be notified for this script.

You can change this by creating your own error handler. The on error command allows you to either install your own handler:




on error goto error_handler

Or you can just ignore errors:




on error goto next

Here is an example of installing and using a custom error handler.




on error goto script_error



# Get the IP address for the site

dns "www.alertra.com"



# Connect to the FTP server

tcp $FTP_PORT



# Request the readme.txt file with the anonymous login ID

# Only get the first 512 bytes of the file

ftp "/pub/readme.txt" "anonymous" "jsmith@virginia.com" 512



# Make sure we got the right file	

if not "Alertra" in $CONTENT then error "Returned file not correct."



goto exit

		

:script_error

	

# Ignore DNS errors

if not $LAST_COMMAND = "dns" then goto send_error

exit "DNS failed, site not checked."



:send_error

on error goto 0

error $LAST_MSG



:exit

The first line of our script changes how ASL handles errors. Anytime the error command is called or an internal command generates an error, the script will jump to the ":script_error" label. This allows you to handle script errors in a central location. This script looks at the name of the command that generated the error ($LAST_COMMAND). If the command was a DNS lookup DNS, the script chooses to ignore the error, log the fact that it failed, and exit gracefully.

The final section of the error handler removes the error handler and then re-generates the error so ASL's normal notification mechanism will notify the scheduled contacts of the error.

In your scripts, there really isn't any reason to do this, but just to show that it can be done, lets recode the original example with a totally custom error handler:




on error goto next



dns "www.alertra.com"

if not $LAST_CODE = "0" then goto bad_dns



tcp $HTTP_PORT

if not $LAST_CODE = "0" then wait 20;tcp $HTTP_PORT

if not $LAST_CODE = "0" then wait 20;tcp $HTTP_PORT

if not $LAST_CODE = "0" then goto bad_socket



http get,redir "/"

if not $LAST_CODE = "0" then goto bad_http



goto exit



:bad_dns

on error goto 0

info "(" + $LAST_CODE + ") " + $LAST_DESCRIPTION

error "Unable to resolve DNS entry.  Check primary " + "and secondary DNS servers."



:bad_socket

on error goto 0

info "(" + $LAST_CODE + ") " + $LAST_DESCRIPTION

error "Unable to connect to host. " + "Make sure HTTP server is running on port " + $HTTP_PORT + "."



:bad_http

on error goto 0

info "(" + $LAST_CODE + ") " + $LAST_DESCRIPTION

error "Unable to retrieve " + $LAST_RESOURCE + "."



:exit

This example shows two other features of ASL scripting. While trying to make the socket connection to the server, we attempt the connection 3 times and wait 20 seconds between each attempt. The IF statement allows you to chain commands together with a semi-colon, so we can wait and retry the connection in one statement. You could also use the begin/end construct to accomplish the same thing:




if not $LAST_CODE = "0" then begin

	wait 20

	tcp $HTTP_PORT

end

2.4. Saving Data

You can save the contents of variables for use the next time your script is called. This can be used to determine when things change. For instance, if you want to know that the IP address the DNS server returns for your site changes you could do something like this:




dns "www.alertra.com"

if $SAVE_IP = "" then set SAVE_IP = $LAST_IP

if not $SAVE_IP = $LAST_IP then goto new_ip



:check

tcp $HTTP_PORT

http get "/"



goto exit



:new_ip

warning "IP address used to be " + $LAST_IP + " but is now " + $SAVE_IP

goto check



:exit

set SAVE_IP = $LAST_IP

save SAVE_IP

In this script, we check the site as normal. If ASL is unable to connect to the web server, an error notification will be sent to the scheduled contacts. However, we also check to see if the IP address has changed. After we retrieve the IP address from the DNS server, we compare it to what the IP address was last time the script ran. To do that we have to work a little magic.

If you ask for the contents of a variable and it doesn't exist, ASL returns an empty string. So our first IF checks to see if we have a valid SAVE_IP. If we don't then we set the SAVE_IP to the value of the current IP. This keeps the next IF statement from firing the first time we run the script. The last bit of magic is taken care of in the ":exit" section. The save command stores the contents of the variable. The next time the script is run, the variable will already exist which is what we want.

This final script demonstrates how you can detect if there have been changes made to your site.




dns "www.alertra.com"

tcp $HTTP_PORT



http get "/index.html"

if $SAVE_DIGEST = "" then digest SAVE_DIGEST = $CONTENT

digest HASH = $CONTENT

if not $HASH = $SAVE_DIGEST then goto possible_hacker



goto exit



:possible_hacker

error "Page has been modified."



:exit

set SAVE_DIGEST = $HASH

save SAVE_DIGEST

The digest command creates a digest of the string it is given. The digest is like a fingerprint and it would be very difficult for someone to change the contents of a file in such a way that it would have different content but generate the same digest.

2.5. Low Level Functions

Low level functions can be used to interact with any socket based service that uses a text based protocol.




dns "www.alertra.com"

tcp 5602



send "HELO\n"

recv 

if $CONTENT = "Widget Server/1.0" then goto WidgetServer



error "Server did not return proper version."



:widgetserver



recv "login:"

send "jsmith\r\n"

recv "password:"

send "pocahontas\r\n"



recv "READY.\r\n"

goto exit



:exit

The commands send and recv are low level functions that allow you to send and receive character data (and to a limited extent binary data) on an open socket. The send command is fairly straight forward; when called it sends the data provided to the server. You can include \r and/or \n to signifiy the carriage-return and new-line characters respectively.

The recv command acts a little differently depending on how it is called. In the first call to recv, the socket is read until no more data is available and that data is placed in the $CONTENT variable. If no data is received before the default timeout, an error is generated. Since we don't have an error handler installed, the script would be aborted.

In the later recv calls we tell recv the text we expect to receive. Instead of storing the response in a variable, the string you pass is compared to the data read from the socket. If the data read doesn't end with the string passed, an error is generated. Notice that in the receive string you can also pass \r and \n to signify the carrige-return and line-feed characters.

2.6. Looping

FOR-loop

The for loop can be used to iterate over a fixed number of items:




for INTERATOR = START_INDEX to END_INDEX begin

	...

end

The for loop initializes ITERATOR to the value of START_INDEX. By default ITERATOR will then be incrememnted by 1 each time through the loop until it reaches END_INDEX.


for REC = 1 to $MYSQL_ROW_COUNT begin

	mysql cursor next

	if $MYSQL_COLUMN_status = "A" then begin

		info $MYSQL_COLUMN_0 + ", " + $MYSQL_COLUMN_email + ", Active"

	else

		info $MYSQL_COLUMN_0 + ", " + $MYSQL_COLUMN_email + ", Not Active"

	end

end

In this example, the loop iterates the over the rows in a MySQL resultset. The variable REC will be set to the current index of the for loop through each iteration. In the example above, the loop will start at 1 and increment REC by 1 until REC is equal to the value of the variable $MYSQL_ROW_COUNT. The default increment is 1, but you can control this by using the step modifier. With step you can increment by any integer value as well as use negative values to run the loop backwards:


for I = 10 to 1 step -1 begin

	info $I

end

Would result in the log containing the text:


10

9

8

7

6

5

4

3

2

1

If you only have one statement to execute in the loop, like the previous example, you could rewrite it like this:




for I = 10 to 1 step -1 info $I

WHILE-loop

The while loop allows a script to execute the same block of commands an indefinate number of times (note: ASL scripts are not allowed to execute more than 5,000 commands; a script that exceeds this limit will be killed by the system).




while EXPRESSION begin

	...

end

As long as the EXPRESSION remains true (1 is true in ASL while 0 is false), the loop will continue to execute. Once the EXPRESSION becomes false (0), then execution of the script will continue with the next statement after the while loop's end statement.




set N = 0

while $N <= 10 loop begin



	info "The value is " + $N

	set N = $N + 1

	

end

This example loops until the value of $N is greater than 10.

B. Definitions

ASL Alertra Scripting Language, the application and scripts that are used by Alertra to perform protocol checks (HTTP, FTP, SMTP, etc...).
key phrase A string used to check the contents of the page. If the phrase is not found ASL logs the check as an error.
label A designator inside a script that can be used as a target for goto statements.
check A single interaction with an Internet resource such as an HTTP or FTP server. An "interaction" encompasses making a socket connection with the resource and performing one or more actions to implement the required protocol.

Z. Language Reference

accumulate digest dns dnsbl error exit for
form formdata ftp gosub goto header http httpreset
https if imap imap4 info list mysql nameserver
on parseform ping pop3 portver recv resume return
runlimit save send set smtp ssh tcp telnet
timeout trace traceable udp untraceable wait warning while

accumulate

Cause content from all protocol commands to be accumulated in the $ACCUMULATED_CONTENT variable. If set for a script, after the script exists, the data in $ACCUMULATED_CONTENT will be saved in the "Content" field of the check record.

usage: accumulate

examples

accumulate

Gathers all $CONTENT data for all protocol commands in the $ACCUMULATED_CONTENT variable.

digest

Creates an SHA digest and places it in the given variable.

usage: digest [target] = [source]

parameters:

req name type description
Y target variable The variable name to put the digest in.
Y source reference/literal Provides the content to be digested.

examples

digest MAIN_PAGE = $CONTENT

Creates an SHA digest of the contents of the $CONTENT variable and puts it in the variable MAIN_PAGE.

digest KEY = "Some really long content"

Creates an SHA digest of the "Some really long content" and puts it in the variable KEY.

dns

Does a domain name lookup on the given name. This command is a prerequisite for all protocol commands (http, ftp, imap4, etc...).

Normally, HTTP/S session information (e.g. cookies and headers) are thrown out when the 'dns' command in executed. The 'noreset' option holds the session information over for use in subsequent HTTP/S requests.

Domain name information is cached by the Bind deamon. You can instruct the 'dns' command to use fresh data by including the 'nocache' option. This causes 'dns' to use it's own recursive name resolver instead of using Bind's. The name information will be downloaded from the nameserver each time. Use this if you are interested in measuring DNS performance time.

If you are connecting directly via an IP address, specify the IP address here instead of a domain name. DNS lookup. Available options are:

  • noreset Include the keyword 'noreset' to keep the HTTP/S session information from being cleared.

usage: dns [name] [noreset,nocache]

parameters:

req name type description
Y name expression Domain name to resolve to an IP.
N options list Comma separated list of options for the

examples

dns "www.alertra.com"

Gets the IP address for the domain name www.alertra.com. Makes this IP address available to all ASL protocol commands.

dns "192.168.42.30"

Since this is an IP address already, this dns command makes this IP address available to all ASL protocol commands.

dns "www.alertra.com" noreset

Gets the IP address for the domain name www.alertra.com. Makes this IP address available to all ASL protocol commands. HTTP/S session information is retained for subsequent HTTP/S commands.

dnsbl

Checks the given IP against DNS block lists used by mail servers to reject mail from known or suspected spam sources. Currently checks the sbl-xbl.spamhaus.org combined list.

If the IP is in the block lists this command will generate an error.

usage: dnsbl [IP]

parameters:

req name type description
Y ip expression The IP address to check with the DNS block lists.

examples

dnsbl 192.168.1.1

Check the DNS block lists for 192.168.1.1.

error

Causes the script execution to terminate with an error state and the given message to be sent to all eligible contacts.

usage: error [message]

parameters:

req name type description
Y The message to be sent to the eligible contacts. expression message

examples

error "Database query failed"

Ends the script and sends the message "Database query failed" to all eligible contacts.

exit

Causes the script execution to terminate with a success state and the given message to be appended to the check log.

usage: exit [message]

parameters:

req name type description
N message expression Optional message to be appended to the log

examples

exit "All pages are OK"

Exits the script immediately, marking the check successful and appends the text "All pages are OK" to the check's log.

exit

Exits the script immediately, marking the check successful.

for

The for loop allows iteration a fixed number of times. Note that scripts will only execute a maximum of 5,000 commands before generating a runtime error. This is to keep any script from running out of control.

You can use the 'begin' keyword in place of the statement to execute multiple commands on each iteration. Be sure to terminate the loop with an 'end' statement:

	for X = 1 to 5 begin
		....
	end

usage: for [target] = [expr1] to [expr2] [step [expr3]] [statement] [;] [statement...]

parameters:

req name type description
Y target variable Variable to receive the value of each iteration
Y expr1 expression The starting index of the loop
Y expr2 expression The ending index of the loop
N expr3 expression The increment to use each iteration (defaults to 1, can be negative)
Y statement statement The command(s) to execute on each iteration of the loop

examples

for X = 1 to 5 http get "/execute.php?cmd=" + $X

Interate from 1 to 5, assigning the value of each iteration to X. On each iteration, execute an http statement giving the value of X to the server script being executed.

for X = 5 to 1 step -1 http get "/execute.php?cmd=" + $X

Interate from 5 to 1, assigning the value of each iteration to X. On each iteration, execute an http statement giving the value of X to the server script being executed.

form

Sets the value of a form variable to the given expression. Form variables are sent with the next HTTP/S command and then cleared. Generally you should use the "encode" option with the http command to insure that the variable names and values are properly encoded for transport.

usage: form [target] = [source]

parameters:

req name type description
Y target variable The name of the form variable
Y source expression The value to place in the form variable

examples

form txtState = "New York"

Sets the value of the form variable "txtState" to "New York".

form "0_userName" = "guest"

Sets the value of the form variable "0_userName" to "guest". The form variable name is surrounded by quotes because it does not comply with ASL variable naming standards.

formdata

An alternate means of passing form variables, the formdata command allows you to set all form variables at one time. It also avoids the problem of form variables not meeting the ASL naming conventions which precludes the use of the form command. If you use this command, then you must make sure the data is properly encoded for HTTP transmission. The 'encode' option of the http command will not have any affect data submitted using this command.

usage: formdata [vars]

parameters:

req name type description
Y vars expression String to use in HTTP/S requests with form variables

examples

formdata "txtName=My%20website&txtFunction=monitor"

On the next HTTP/S request, the data "txtName=My%20websiteamp;txtFunction=monitor" will be sent as form variables.

ftp

Connects to an FTP server. Optionally can retrieve a file from that server.

usage: ftp [path] [userid] [password] [size]

parameters:

req name type description
Y path expression The directory path to change to after logging in. You can specify a complete file path; if you do the file up to 'size' will be downloaded.
N userid expression The userid to use when logging into the FTP server
N password expression The password to use when logging into the FTP server
N size expression The maximum amount (in bytes) of the file to download if a file was specified.

examples

ftp "/" "anonymous" "joe@garage.com"

Connects to the FTP server identified in the last dns command. The user "anonymous" and password "joe@garage.com" are supplied if the FTP server asks for authentication.

ftp "pub/readme.txt" "fzappa" "joe@garage.com" "50"

Connects to the FTP server identified in the last dns command. The user "fzappa" and password "joe@garage.com" are supplied if the FTP server asks for authentication. The first 50 bytes of the file "pub/readme.txt" are downloaded and stored in $CONTENT.

gosub

Cause execution of the script to jump to a given label in the script. Script labels are created by placing a ":" and then the name of the label. Label names must start with a character and cannot have spaces.

'gosub' differs from goto in that you can return from a 'gosub' call and resume script execution with the next command after the 'gosub'.

usage: gosub [label]

parameters:

req name type description
Y label literal The script label to jump to.

examples

gosub check_site

Assuming the script contains a label ":check_site", execution of the script will continue with the line after the label.

goto

Cause execution of the script to jump to a given label in the script. Script labels are created by placing a ":" and then the name of the label. Label names must start with a character and cannot have spaces.

usage: goto [label]

parameters:

req name type description
Y label literal The script label to jump to.

examples

goto check_site

Assuming the script contains a label ":check_site", execution of the script will continue with the line after the label.

header

Appends a header to the list of headers that will be sent with the next HTTP/S request. The text is sent as-is by this commnand, so the format must be appropriate and acceptable to the target web server.

usage: header [text]

parameters:

req name type description
Y text expression The string to be sent with the next HTTP/S request.

examples

header "x-script:alertra web site monitor"

Adds the header "x-script:alertra web site monitor" to the list of headers to be sent with the next HTTP/S request.

http

Makes an HTTP connection to the computer using the computer identified in the last dns and tcp commands.

If you use the 'GET' method, you can pass form variables in the 'request' parameter or by using the form or formdata commands. However, the 'POST' method requires that you use form or formdata to pass form variables.

You must specify one of 'get', 'head', or 'post' in the options parameter.

If you are posting form data you should usually include the 'encode' option. This will translate illegal characters in your form variables into hex characters acceptable in the HTTP protocol. The only reason not to use this option is if in setting the form variables you have manually translated the illegal characters already.

usage: http [options] [request] [user] [pass]

parameters:

req name type description
Y options list Comma separated list of options for the HTTP connection. Available options are:
  • head Retrieve only the HTTP header records.
  • get Use the 'GET' method of making the request.
  • post Use the 'POST' method of making the request.
  • redir Instructs the 'http' command to follow redirection commands to subsequent pages.
  • encode Converts form values to standard application/x-www-form-urlencoded format
Y request expression The page request sent to the HTTP server.
N user expression If the server requests authentication, the user to use to authenticate.
N pass expression The password for the user in authentication.

examples

http get,redir "/index.html"

Retrieves the page "/index.html" from the server using the 'GET' method. The 'http' command will follow all redirect commands from the server (redirect loop protection is built into ASL; the script will end with an error if a redirect loop is detected).

http post,encode "/scripts/checkcc.asp" "joe" "u571"

Posts whatever variables have been set with either the form or formdata commands to the "/scripts/checkcc.asp" page. If the variables were set with the form command, then they will also be encoded. If the server requests authentication information, it will be sent the user "joe" with the password "u571".

httpreset

Resets all of the headers, cookies, and other session data collected by previous HTTP/S commands.

usage: httpreset

examples

httpreset

Resets all HTTP/S related session data.

https

Makes an HTTPS connection to the computer using the computer identified in the last dns and tcp commands.

If you use the 'GET' method, you can pass form variables in the 'request' parameter or by using the form or formdata commands. However, the 'POST' method requires that you use form or formdata to pass form variables.

You must specify one of 'get', 'head', or 'post' in the options parameter.

If you are posting form data you should usually include the 'encode' option. This will translate illegal characters in your form variables into hex characters acceptable in the HTTP protocol. The only reason not to use this option is if in setting the form variables you have manually translated the illegal characters already.

usage: https [options] [request] [user] [pass]

parameters:

req name type description
Y options list Comma separated list of options for the HTTP connection. Available options are:
  • head Retrieve only the HTTP header records.
  • get Use the 'GET' method of making the request.
  • post Use the 'POST' method of making the request.
  • redir Instructs the 'http' command to follow redirection commands to subsequent pages.
  • encode Converts form values to standard application/x-www-form-urlencoded format
Y request expression The page request sent to the HTTPS server.
N user expression If the server requests authentication, the user to use to authenticate.
N pass expression The password for the user in authentication.

examples

https get,redir "/index.html"

Retrieves the page "/index.html" from the server using the 'GET' method. The 'https' command will follow all redirect commands from the server (redirect loop protection is built into ASL; the script will end with an error if a redirect loop is detected).

https post,encode "/scripts/checkcc.asp" "joe" "u571"

Posts whatever variables have been set with either the form or formdata commands to the "/scripts/checkcc.asp" page. If the variables were set with the form command, then they will also be encoded. If the server requests authentication information, it will be sent the user "joe" with the password "u571".

if

Conditionally perform a statement. If the expression evaluates to anything besides "0", the statement will be executed. If the expression evaluates to "0" the statement will not be executed. Use of the keyword 'not' reverses this behavior.

Normally you would branch using a goto statement, but you can use any valid statement after the then clause. Additionally, you can have multiple statements executed by separating them with a semicolon (;).

You can use the 'begin' keyword in place of the statement to execute multiple commands. Be sure to terminate the if with an 'end' statement:

	if not "My web site" in $CONTENT then begin
		....
	end

usage: if [not] [expr] then [statement] [;] [statement...]

parameters:

req name type description
N not literal Include this literal to negate the value of the expression.
Y expr expression The expression to be evaluated.
Y statement statement The command(s) to execute if the expression evaluates to true.

examples

if "Login Successful" in $CONTENT then goto success

If the variable $CONTENT (which always contains the result from the last protocol command) contains the text "Login Successful" the script will branch to the label ":success". Otherwise the script will continue with the next statment after the if.

if not "Login Successful" in $CONTENT then error "Login to site was unsuccessful"

If "Login Successful" is not in $CONTENT, then the script will be terminated with an error message ("Login to site was unsuccessful"). Otherwise, the script will continue with the next statement after the if.

imap

See imap4.

examples

imap4

Interacts with an IMAP4 server to perform the following functions: connect, message count, and clearing messages.

usage: imap4 [operation] [user] [password] [options]

parameters:

req name type description
Y operation keyword One of:
  • connect: Initiates a connection to the IMAP server
  • msgcount: Returns the current number of messages in the mailbox; count is placed in $CONTENT.
  • clear: Tells the IMAP server to delete all the messages in the mailbox
Y user expression Login ID of user's mailbox
Y password expression Password for the user's mailbox
N options list Available options are:
  • ssl Use secure connection (SSL)

examples

imap4 connect "joe" "garage"

Establishes a connection to the server and logs in.

imap4 msgcount $USER $PASS

Assuming $USER contains "jack" and $PASS contains "beanstalk", this command will log into the IMAP4 server, query it for current number of messages in the inbox and place that number in $CONTENT.

imap4 clear "jill" "beanstalk"

Logs into the IMAP4 server and deletes all the messages in the account's inbox.

imap4 connect "joe" "garage" ssl

Establishes a secure connection to the server and logs in.

info

Inserts a message into the log for this check.

usage: info [message]

parameters:

req name type description
Y message expression Text of the message to be added to the log.

examples

info "Starting Database Check"

Adds a message to the log that says, "Starting Database Check".

list

Returns an element from the given list. Indexes are zero based. The list value is stored in a global variable called "LIST_VALUE".

usage: list [list] [sep] [index]

parameters:

req name type description
Y list expression A string containing a list of values sepearated by a common string.
Y sep expression A string containing the separator used in the list
Y index expression Index of the element to return from the list

examples

list "foo;bar;zot" ";" "0"

Returns "foo" from the list.

list "foo;bar;zot" ";" "1"

Returns "bar" from the list.

mysql

Interact with a MySQL database server by connecting and optionally executing queries.

connection

On the initial connection, this command will attempt to execute the query "SHOW STATUS" to gain the value of all status variables maintained by MySQL. These variables will be added to the global namespace as MYSQL_STATUS_X where "X" is the name of the variable. For instance, after executing this command:

	mysql connect "guest" "love" "mysql"

You could query the value of a status variable like this:

	if $MYSQL_STATUS_ABORTED_CLIENTS > 10 then error "aborted clients"

More information on the "SHOW STATUS" query can be found here.

executing queries

After connecting to a MySQL server, you can execute any number of queries. The scripting engine uses a single cursor for a connection to the server, so each query will over write the results from the last. This sample code illustrates how to execute a query and retrieve the results:

	mysql exec 'select user_id, email, status from users'
	for REC = 1 to $MYSQL_ROW_COUNT begin
		mysql cursor next
		if $MYSQL_COLUMN_status = "A" then begin
			info $MYSQL_COLUMN_0 + ", " + $MYSQL_COLUMN_email + ", Active"
		else
			info $MYSQL_COLUMN_0 + ", " + $MYSQL_COLUMN_email + ", Not Active"
		end
	end

After the query is executed, the variable MYSQL_ROW_COUNT is set to the number of rows returned by the query. That variable can be used within a for loop to retrieve the records. Calling mysql cursor next "loads" the next record into global variables. You can access the column values by index or by name (e.g. MYSQL_COLUMN_0 and MYSQL_COLUMN_email respectively).

usage: mysql [connect [user] [password] [database]] [exec [query]] [cursor next] [close]

parameters:

req name type description
Y operation keyword One of:
  • connect: Connects to the MySQL server, logs in and selects the given database.
  • exec: Executes the query with the MySQL connection opened by a call to connect.
  • cursor: Performs cursor operations based on the previously executed query.
  • close: Closes the connection to MySQL.
N user expression Login ID used to connect to the server
N password expression Password used to authenticate the connection to the server
N database expression Name of database to use after connecting
N query expression The query to execute
N next expression Moves the cursor to the next record

examples

mysql connect "guest" "love" "mysql"

Connect to the given MySQL server with the user ID "guest", a password of "love". The database "mysql" will be used.

mysql exec "select * from users"

Executes the query using the existing connection to the MySQL server.

mysql cursor next

Move the resultset cursor from the current record (or the beginning of the resultset) to the next record.

mysql close

Close the current connection to the MySQL server. Also closes the outstanding cursor if necessary.

nameserver

Directly connects to one or more nameservers to insure they are working properly.

You must specify one of 'soa', 'a', or 'mx' in the operation parameter.

usage: nameserver [operation] [domain] [server]

parameters:

req name type description
Y operation keyword Available operations are:
  • soa Requests the Start Of Authority record from the zone authority; checks the primary and any backup nameservers returned in the SOA. The server is not used.
  • a Get the authority record(s) from the nameserver specified in the server command.
  • mx Get the mail exchange record(s) from the nameserver specified in the server command.
Y domain expression The domain to query the nameserver(s) with.
N server expression The domain name or IP of the nameserver to check when not doing an soa check.

examples

nameserver soa "mydomain.com"

Contacts the zone authority to get the Start Of Authority record for the domain "mydomain.com" command. The primary and any backup nameservers in the SOA will be checked to insure they are working properly.

nameserver a "mydomain.com" "ns1.mydomain.com"

Connects to the nameserver "ns1.mydomain.com" directly and requests that it resolve the domain "mydomain.com"

on

The on command allows you to specify a label to jump to when an event happens.

usage: on [event] goto [label]

parameters:

req name type description
Y event literal Currently error is the only event that can be trapped.
Y label literal A valid label within the script to jump to when an event happens. If set to the literal "0", then the event handler is disabled and normal processing of the event is resumed. If set to the literal "next", then errors will no longer cause the script to end; execution will continue with the next statement.

examples

on error goto handle_errors

Sets up an event handler that will send all "error" events to the "handle_errors" script label.

on error goto 0

Removes any previously set event handler for "error" events.

on error goto next

Causes the script to continue executing even if an error is generated; execution will continue with the next statement after the one that caused the error.

parseform

Parse the given content for a specific "form" tag. Parsed form attributes are placed in local variables. Parsed form input fields are placed in variables that can be set via the form command.

form names

A single HTML page can contain multiple forms, so typically each form has its "name" property set to some unique name. If that is the case, then you can control which form "parseform" parses by supplying that name:

	parseform "login"

When the form is parsed, the form attributes are put into local variables that can be accessed from the script. For instance, parsing this form:

	<form name="login" action="login.asp">

Would result in the following variables:

NameValue
FORM_login_namelogin
FORM_login_actionlogin.asp

In some cases, usually with only one form in the HTML, the form may not have it's name property set. In this case, parseform will give it the name "alertraMAIN". Note: If your HTML has more than one form without it's name property set, you cannot use parseform.

The input fields of the form are also parsed and stored in variables. A form with two input fields, 'username' and 'password' plus a hidden field called '__VIEWSTATE', would cause the following variables to be set:

NameValue
input_login_username_value[some value]
input_login_password_value[some password]
input_login___viewstate_typehidden
input_login___viewstate_value[some value]

The parseform command will automatically copy any form input values that have a default value to the form variable collection (see: form). You only need to set those values if you want to override the default. For instance, in the example above say 'username' and 'password' don't have default values, but '__VIEWSTATE' does. In that case, after calling parseform the form variable '__VIEWSTATE' would already be set from the value parsed from the HTML.

usage: parseform [formname]

parameters:

req name type description
Y formname expression Name of the form to parse.

examples

parseform "login"

Parses the "login" form and puts the values in FORM_login_X variables.

ping

Protocol command that initiates an ICMP test of the last host passed to the dns command. If all packets fail to be returned by the host, an error will be generated.

The ping command sets the following global variables:

  • LAST_PING_DELAY - the average time response time of all ping packets.
  • LAST_PING_BADPACKETS - the number of packets that were not acknowledged by the host.

usage: ping [count] [badpercent] [maxdelayavg]

parameters:

req name type description
N count expression Number of ping packets to send to the server. Default is 15.
N badpercent expression Percentage of packets that can be bad before an error is generated.
N maxdelayavg expression Maximum average packet delay before an error is generated.

examples

ping

Performs an ICMP test of the last host passed to the dns command by sending 15 ping packets.

ping "5"

Performs an ICMP test of the last host passed to the dns command by sending 5 ping packets.

ping "30" "70"

Performs an ICMP test of the last host passed to the dns command by sending 100 ping packets. If 70% or greater of those packets are bad, then an error will be generated.

ping "10" "100" "50"

Performs an ICMP test of the last host passed to the dns command by sending 100 ping packets. If all of the packets are bad (100%) an error will be generated. If the average packet delay is greater than 50ms, an error will be generated.

pop3

Interacts with a POP3 server to perform the following functions: connect, msgcount, and clear.

usage: pop3 [operation] [user] [password] [options]

parameters:

req name type description
Y operation keyword One of:
  • connect: Initiates a connection to the POP server
  • msgcount: Returns the current number of messages in the mailbox; count is placed in $CONTENT.
  • clear: Tells the POP server to delete all the messages in the mailbox
Y user expression Login ID of user's mailbox
Y password expression Password for the user's mailbox
N options list Available options are:
  • ssl Use secure connection (SSL)

examples

pop3 connect "joe" "garage"

Establishes a connection to the server and logs in.

pop3 msgcount $USER $PASS

Assuming $USER contains "jack" and $PASS contains "beanstalk", this command will log into the POP server, query it for the the current number of messages in the inbox and place that number in $CONTENT.

pop3 clear "jill" "beanstalk"

Logs into the POP3 server and deletes all the messages in the account's inbox.

pop3 connect "joe" "garage" ssl

Establishes a secure connection to the server and logs in.

portver

Reads the header sent by the server (typically containing the service version information). The port must be previously set by a call to the tcp command. The data returned by this command can be found in the "$CONTENT" variable. The port is closed after this command.

usage: portver

examples

portver

Sets $CONTENT to the version string returned by the service.

recv

Retrieves waiting data from an open tcp or udp connection. If data is received before the timeout, it will be placed in $CONTENT. Otherwise, an error will be thrown. The default timeout is 20 seconds.

This command is typically used with the send command to interact directly with a network device.

usage: recv [timeout]

parameters:

req name type description
N timeout expression Number of seconds to wait on data if none is available.

examples

recv

Waits on the open connection until data is received or 20 seconds elapses, whichever is first.

recv 10

Waits on the open connection until data is received or 10 seconds elapses, whichever is first.

recv $TIMEOUT

Assuming TIMEOUT=25, waits on the open connection until data is received or 25 seconds elapses, whichever is first.

resume

Returns execution of the script to the next statement after the statement that generated the last error.

This command is only useful if you have an on error goto error handler in effect.

usage: resume

examples

resume

Returns execution to the statement following the one that generated the error.

return

Returns execution of the script to the next statement after the last gosub statement.

If there is no 'gosub' in effect when 'return' is called, a runtime error will result.

usage: return

examples

return

Resumes execution of the script with the statement following the last 'gosub'.

runlimit

Sets the number of seconds the script should be allowed to run before it is cancelled with a runtime error. The script might actually run longer, the runlimit is only checked before execution of each command. Maximum value is 300 seconds (five minutes). Minimum value is 5 seconds.

usage: runlimit [seconds]

parameters:

req name type description
Y seconds expression Number of seconds to allow script to run

examples

runlimit 10

This script will be allowed to run for 10 seconds before being killed.

save

Saves the contents of the given variable in a persistent store; variables stored using the save command are available the next time the script runs.

usage: save [varname]

parameters:

req name type description
Y varname variable The name of the variable to save.

examples

save HOST_NAME

Saves the current contents of HOST_NAME in the persistent storage. When the script runs again the HOST_NAME variable will be set to that value.

send

Sends data to an open tcp or udp connection. This command is typically used with the recv command to interact directly with a network device.

usage: send

examples

send "HELO

" Sends the string "HELO" followed by a carriage return and line feed to the open connection.

set

Sets the value of a local variable to the given expression. The local variable does not have to be created first; the first time you give a variable a value the variable will be created and will exist for the entire execution of the script.

usage: set [target] = [source]

parameters:

req name type description
Y target variable The variable name to set contain the value.
Y source expression The value to set the variable to.

examples

set HOST = "www.alertra.com"

Sets the "HOST" variable to the value "www.alertra.com"

set PAGE = "/orderform.asp?id=" + $ID + "&load=y"

Assuming "ID" is a variable set to "10", this example sets the "PAGE" variable to the value "/orderform.asp?id=10&load=y".

smtp

Interacts with an SMTP server to perform the following functions: connect, verify and sendmail.

You can force the connection to use TLS mode by setting the local variable smtptls to "Y", e.g.:

set smtptls="Y"

If the server doesn't doesn't support TLS, the connection will fail.

usage: smtp [sendmail [from] [to] [subject] [msg]] [verify [address]] [user] [password]

parameters:

req name type description
Y operation keyword One of:
  • connect: Connects to the SMTP server and looks for the proper greeting.
  • sendmail: Sends an email using the SMTP server to the given toAddress.
  • verify: Asks the SMTP server to verify that the given toAddress is valid on that server.
N from expression When performing a 'sendmail' operation, this is the e-mail address that should be sent in the SMTP "From:" header. This field is only required for the 'sendmail' operation.
N to expression When performing a 'sendmail' operation, this is the e-mail address that should receive the message. This field is only required for the 'sendmail' operation.
N subject expression The subject to send with the message when performing a 'sendmail' operation. This field is only required for the 'sendmail' operation.
N msg expression The text of the message to send when sending a message to the SMTP server using the 'sendmail' operation. This field is only required for the 'sendmail' operation.
N address expression The e-mail address that should be checked with the SMTP server when using the 'verify" operation. This field is only required for the 'verify' operation.
N user expression Login ID for a valid user of the SMTP server; this field is not widely used by most SMTP servers.
N password expression Password for login ID; this field is required if user is specified.

examples

smtp sendmail "joe@alertra.com" "holly@alertra.com" "Test Message" "This is a test message"

This example will send a message to holly@alertra.com from joe@alertra.com with the subject Test Message and contents of This is a test message.

smtp sendmail $FROM_ADDR "julie@alertra.com" "Test Message" $MSG_TEXT "joe" "passpass"

Send a message to julie@alertra.com from the address defined in the variable FROM_ADDRESS with the subject Test Message, the contents of MSG_TEXT as the text of the message and logging in as joe with the password passpass.

smtp verify "tom@alertra.com"

Connects to the SMTP server and verifies the address tom@alertra.com is valid.

ssh

Connects to a SSH server. If you supply a userid and password, this check will connect to the SSH and attempt to login. If the login fails, an error will be generated. If you do not supply any credentials, this check will connect to the SSH server, but not attempt to login. As long as the socket connect is made and any sort of SSH version string is sent, the check will succeed.

usage: ssh [userid] [password]

parameters:

req name type description
N userid expression The userid to use when logging into the SSH server
N password expression The password to use when logging into the SSH server

examples

ssh

Connects to the SSH server identified in the last dns command.

ssh "joe" "garage"

Connects to the SSH server identified in the last dns command. The user "joe" and password "garage" are supplied for the SSH server authentication.

tcp

Makes a quick TCP connection to the given port. Other protocol commands will use this same port. This command must be called before other protocol commands. There are several predefined constants for common ports: HTTP_PORT, HTTPS_PORT, FTP_PORT, SMTP_PORT, POP3_PORT, TELNET_PORT, SSH_PORT, IMAP4_PORT.

socket connection. Available options are:

  • noconnect Don't actually connect to the socket, just set the port required for other protocol commands.
  • ssl Use secure connection (SSL)

usage: tcp [port] [options]

parameters:

req name type description
Y port expression The port to connect to.
N list options Comma separated list of options for the

examples

tcp $HTTP_PORT

Makes a connection to port 80 on the computer identified by the last dns command.

telnet

Connects to a Telnet server. If you supply a userid and password, this check will connect to the Telnet server and attempt to login. The 'telnet' command looks for the string 'ogin:' and then sends the userid. It then looks for 'ssword:" and sends the password. There is no way of knowing whether the login actually succeeds or not from a protocol standpoint; you should check the $CONTENT variable for some known value to tell whether the login was successful.

If you don't supply a userid and password, this command will return everything up to "ogin:" in $CONTENT.

You must call dns and tcp to set the hostname and port to connect to.

usage: telnet [userid] [password]

parameters:

req name type description
N userid expression The userid to use when logging into the server
N password expression The password to use when logging into the server

examples

telnet

Connects to the Telnet server identified in the last dns command.

telnet "joe" "garage"

Connects to the Telnet server identified in the last dns command. The user "joe" and password "garage" are supplied for the Telnet server authentication.

timeout

Pauses the script for the given number of seconds.

usage: timeout [seconds]

parameters:

req name type description
Y seconds expression The number of seconds to pause execution of the script.

examples

timeout "5"

Pauses execution of the script for 5 seconds.

timeout $WAIT_SECS

If WAIT_SECS=10, then execution of the script is paused for 10 seconds.

trace

Performs a trace similar to 'traceroute' to the IP resolved by the last DNS.

gauging link performance (must be a value between 1-30).

usage: trace [cycles]

parameters:

req name type description
Y cycles variable Number of ping packets to send when

examples

trace "10"

Conducts a trace to the IP and sends 10 packets to each node in the trace to gauge performance.

traceable

If the script ends in an error, a traceroute will be completed from the current monitoring station to the last IP resolved by the dns command.

usage: traceable

examples

traceable

An error will result in a traceroute being executed.

udp

Makes a UDP connection to the given port. There are several predefined constants for common ports: HTTP_PORT, HTTPS_PORT, FTP_PORT, SMTP_PORT, POP3_PORT, TELNET_PORT, SSH_PORT, IMAP4_PORT.

usage: udp [port]

parameters:

req name type description
Y port expression The port to connect to.

examples

udp "100"

Makes a connection to port 100 on the computer identified by the last dns command.

untraceable

If the script ends in an error, a traceroute will not be completed.

usage: untraceable

examples

untraceable

An error will not result in a traceroute being executed.

wait

Pauses execution of the script for the given number of seconds.

usage: wait [seconds]

parameters:

req name type description
Y seconds expression Number of seconds to pause the script

examples

wait 10

Causes the script to pause execution for 10 seconds

warning

Causes a warning message to be sent to all eligible contacts assigned to this script. For the warning to actually be sent, you must exit the script before any other statements are executed (see goto).

usage: warning [message]

parameters:

req name type description
Y message expression Text of the message to send to the eligible contacts.

examples

warning "Website has changed"

Sends a warning message saying, "Website has changed," to all eligible contacts.

warning "Total time of " + $TOTAL_RUNTIME + " seconds outside of allowed range"

Assuming the script has been running for 10 seconds, this example sends a warning message to all eligible contacts that says, "Total time of 10 seconds outside of allowed range"

while

The while loop allows iteration an unknown number of times. Note that scripts will only execute a maximum of 5,000 commands before generating a runtime error. This is to keep any script from running out of control.

You can use the 'begin' keyword in place of the statement to execute multiple commands on each iteration. Be sure to terminate the loop with an 'end' statement:

while $N != 10 begin .... end

usage: while [expr] loop [statement] [;] [statement...]

parameters:

req name type description
Y expr expression Expression evaluated before each iteration
Y statement statement The command(s) to execute on each iteration of the loop

examples

while $N != 10 loop $N = $N + 1

Increments the variable N until its value is equal to 10.