What is an Alert
When a node on which "alerts active" is set fails a test (or generates a warning) an alert is created. This alert is displayed in a box to the right of all FreeNATS pages.
If a node has a current alert this is also shown in the node status display where you can also view the history of that and any previous alerts.
Alert actions are actions to perform when an alert is generated. Email and URL actions are supported (there is a third type of action - a message queue but this is only used for custom event handlers or API data use). Actions are created and modified in the Configuration -> System Settings page (under Alert Actions).
For each alert action you can specify a name, a type (email, url or disabled) and select whether to include warnings and decreases.
You can also set the action limit (and view/update the action counter). The action limit is the number of times in a calendar day the alert action can be called before it just ignores input (and logs what has happened). Setting this to zero means unlimited. The counter shows the count and the last day on which the count was updated (the next time the alert action is called on a different day it will reset the counter). For debug purposes you can change the counter in here manually. Action tests are counted.
If warnings are not included only outright failure alerts are reported by this alert action. If decreases are selected then further alerts are sent when the alert decreases from failed to warning (not if warnings is not checked) or is closed (the test has passed).
An alert action can also be set a schedule (or "At all times" - the default) which determines when the alert action will and won't be executed. The schedule does not affect test alerts from the interface. For example, to have alerts sent differently daytime (0700-1900) and nighttime (1900-0700) you could:
- create a daytime schedule to run from 0700 to 1900
- create a nighttime schedule to run at all times except 0700 to 1900
- create a daytime alert action set to the daytime schedule
- create a nighttime alert action set to the nighttime schedule
- assign nodes to both alert actions
In this way, when an alert is generated both actions are tried but only one will be within the schedule to be executed and actually send any messages.
For email alerts you can specify a from address, subject and type format as well as a list of recipients (one on each line of the email to box without commas or any other punctuation). Long format subjects include some extra details. You can configure a custom short and long subject as well as a long-format email header and footer through some system variables.
By default mail is delivered using the inbuilt PHP mail() function but you can specify a specific SMTP relay etc through the email settings.
If you wish to set up specific mail settings (such as an SMTP relay host) then please see the mail settings section of the documentation.
For URL alerts you enter each URL you wish called on each line of the URL box. This should be a fully-qualified URL (include http). The message is URL encoded onto the end. So you can for example put something like "http://somehost/script.php?action=freenats&message=" and that script will be called with the message URL encoded into the message parameter.
Messages and Testing
The long message type includes some padding and other information around the alert text wheras short just sends the absolute minimum alert text (useful for email/URL to SMS messages).
Selecting test action will do just that and fire off test alerts to everyone/every URL on the list.
Linking to Nodes
Nodes are assigned to and removed from alert actions in the node edit page and can be a member of any number of alert actions.
In this way for example it is possible to have all node alerts emailed to a normal email address but only alerts on one or two critical nodes also sent via email to SMS.
A Note About Threaded Testing
Very early versions of FreeNATS relied entirely on the tester.sh script which tests one or all nodes in series (one after the other). For a variety of reasons threading is a much better solution (where the test-threaded.sh script spawns background processes of tester.sh for every node to be tested at the same time).
The tester.sh script flushes the alert queues when it finishes. In a single run of tester this means the alert queues contain new information for all nodes by the time tester finished resulting in a single email (for each alert action).
In the threaded model the tester.sh script finishes the single node it has been called for, alerts as required and flushes the alert queue. This results in a single email for each node that is handled by an alert action.
Possible steps are afoot to consider a workaround for this if required.