Tests

Server-Side Tests

This section of the documentation refers to server-side tests done from the FreeNATS server to a remote node (for example opening an IMAP connection or requesting a web page). These are also sometimes (confusingly) referred to as "local" tests (the test itself is run locally on the FreeNATS server). For nodeside monitoring (deploying scripts/programs/agents on the node to gather and report data) see the nodeside monitoring section of the documentation.

You can add, edit and delete tests through the node edit 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 test evaluators.

Test Types

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 Connect

Opens a TCP connection to the node's hostname on the port passed as the parameter, returns negative on failure or the elapsed time in seconds (minus DNS lookup) on success.

UDP Connect

Opens a UDP connection to the node's hostname on the port passed as the parameter, returns negative on failure or the elapsed time in seconds (minus DNS lookup) on success.

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.

MySQL Data

Opens a MySQL connection using the host/user/pass/database specified and performs the query given. Returns the contents of the column specified (defaults to 0 - first) of the first row of data returned. Returns a negative value on any sort of failure or if no data is returned by the query.

Using this test it is possible to monitor and alert on (through custom evaluators) data stored within any MySQL database.

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.

SMB Connect

Connects to an SMB Share (Windows/CIFS) wrapping the Linux smbclient command.

Enter a share with a full path using forward-slashes e.g. //server/share

If the username is blank anonymous (guest) authentication is attempted or the username is used.

Please note any special characters in the share, username or password will need to be escaped with backslashes for use as parameters.

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).

Passing/Failing

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

You can configure your own custom evaluators (for example fail if takes longer than 10 seconds etc)

Test Options

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).

Test Interval

Setting this interval will mean the test will be run with a that minimum interval (in minutes). Please note that any tests are only due to be performed when the node itself is due for testing so if for example you have set the node interval to 15 minutes and the test interval to 1 (or 0 which means run every time possible) then the test would still only be performed every fifteen minutes when the node was due. See the test intervals document for more information.

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.