Outdated Resource Warning!

This is documentation for legacy version 0.x releases. If you are using 1.x see the wiki.

Setting Up Tests

You can add, edit and delete tests through the node edit page (clicking edit in the node list on the main page).

By default tests use simple evaluation where their result is evaluated by FreeNATS to determine if they have passed or failed. You can configure your own evaluators (see below).

There are the following user-configurable test types (in addition to the ping test which can be selected within the node settings):

Web Time	Returns the time in seconds required to open and fetch a URL, 0 if no data was returned at all and a negative value on total failure
Web Size	Returns the time size of data from a URL (0 indicates an empty document and will fail simple evaluation) and a negative number on failure.
TCP Port	Opens a TCP connection to the node's hostname on the port passed as the parameter
Remote Ping	Does a ping test to the host or IP specified (ignores the test.icmp.attempts flag though and only tries once unless otherwise specified) unlike the standard node ping test which pings the node hostname (useful for multi-ping or multi-interface tests). Returns a negative value or 0 on failure and the time taken for a response on success. The time returned is in seconds unless the system variable test.icmp.returnms is set to 1 in which case time is returned in milliseconds (1/1000ths of a second).
SMTP	Opens a SMTP connection to the host specified (on default port of 25 or custom port if specified). Waits for a welcome message, sends back a HELO, waits for a 220 response and sends back a QUIT. Time is returned if successful or 0 (or below) if the test fails for some reason. Returns the time in seconds the transaction took if successful or a negative value on failure.
IMAP	Opens a connection to the default mailbox for the host/user/password given using IMAP/POP3 and optionally SSL. Will connect to the default port for the options chosen (i.e. non-SSL IMAP 143) or use the port given if specified. Returns the time in seconds taken for the connection to complete if successful or a negative value on failure.
MySQL (Time and Rows)	Opens a MySQL connection using the host/user/pass specified. Connects to the database if one is specified and performs the query (again only if specified). Note the query will only execute if a database to perform the query on is specified. The rows test returns the number of rows returned or affected by the query whereas the time test returns the total time in seconds to perform the transaction. Returns a zero (no rows) or a negative value (connect/query error) on failure.
DNS Host	Attempts a simple DNS resolution on the provided hostname (IP / A record lookup) or reverse lookup if an IP address is specified (PTR lookup) using the inbuilt environment gethostbyX() functionality (determines if a host or IP has been provided automatically). This checks that the host/IP is resolveable on the local FreeNATS server using its cache and (usually DHCP provided) configured DNS server. Returns the time taken in seconds if successful or a negative result on failure.
DNS Query	Does a DNS lookup of the query/type specified (for example www.purplepixie.org type A does an A record IP address lookup for www.purplepixie.org) using the DNS network protocol against a specific nameserver. If the nameserver is unspecified in the test the node hostname will be used. The port (default 53) and timeout (default 60s) can be optionally specified or use their defaults if blank. Selecting TCP will perform the lookup using the stateful TCP protocol otherwise stateless UDP will be used. The time in seconds the query took (total time including packing of query and unpacking/parsing of answer) is returned if one or more answers is returned for the query otherwise a negative value is returned indicating query failure or no answer records.
Test Loop	Test functionality - returns a value of whatever is passed as the parameter. Used for testing evaluations.
Test Random	Test functionality - returns a random whole number between 0 and the parameter (or 100 if blank).

In default (simple evaluation) the tests are deemed to fail if they timeout or cannot connect and otherwise pass.

When creating or editing a test you will be able to specify custom parameters such as the URL or hostname. All URLs should be fully-qualified (such as http://www.google.co.uk/), ports and query strings can be passed in the normal URL fashion.

Other options available for all test types are:

Enabled	If the test is set as enabled it will be tested when the node is. Disabled tests are not run and no data is recorded for them (unlike tests skipped by the node owing to a schedule which are recorded but as -1 [untested] status).
Recorded	If you select Recorded in the test settings the results will be historically recorded. A history link will then appear for the test in the node status display and you can view result data (the "actual" result as well as the resultant alert status) - see the historic data and availability report section of the documentation for more information.
Custom Name	Setting a custom name for the test will display the given name in alerts and in system displays. If this is blank then an automatically generated name will be used of "Test Name (Parameter)" (this will be truncated for most displays and alerts).
Timeout	You can also set a custom timeout value (supported by most test types) in seconds. This will override the FreeNATS site-wide default (set through variables in the admin page) and system environment (used if no site-wide default is set). This can be useful for upping the http or ping timeout for a distant node for example. Your PHP environment must allow socket timeout setting for this to work on web-type tests.
Attempts	The number of attempts (if greater than 1 - the test will always be tried at least once if it "should be" i.e. the ping test has passed or is not required) sets how many times to try the test (if it fails) before giving up and reporting the failure.

Complex Evaluation / "Custom Evaluators"

Ok so it's not really very complex at all.

You can add your own custom evaluators which test the result against values you specify by selecting if the return value is equal to, less than or above a specified value. This results in an alert level.

When a rest result is returned it is tested against all the evaluators and the worst result taken of any it has matched. Please note that many tests return a 0 or negative number on failure so it should be accounted for.

You must uncheck the Simple Evaluation option (and save test settings) for your complex evaluators to be used.

If we had a web time test we could add the following evaluators:

Equal To 0 - Failed
Less Than 0 - Failed
Greater Than 5 - Warning
Greater Than 10 - Failed

This would cause a failure if the test totally failed, a warning if it took longer than five seconds and a failure if longer than ten (the test would pass with a test return of between zero and five seconds).

When tests fail they generate alerts which are discussed in more detail in the alerts and alert actions section of the documentation.