Events control the handling of "events" in Untangle.
Within Untangle and the apps, when noteworthy actions occur an "event" is logged. An event is an object that describes an action. For example, an HttpRequestEvent is logged when a client on the network makes an HTTP Request. A SessionEvent is logged when a PC creates a network connection.
The platform and all apps log events through the Event Manager. The Event Manager will do several things with each event:
- Evaluate Alert Rules and create, log, and send an alert if necessary.
- Evaluate Trigger Rules and take an action if necessary.
- Evaluate Syslog Rules and send a syslog message if necessary.
- Send the event to Reports, if installed, for saving in the reports database.
Alert rules are evaluated on all events logged and will log and/or alert the administrator when interesting or noteworthy events occur.
Each logged event is represented by a JSON object. As each event is logged to the database the alert rules are evaluated. The Event Definitions page details all of the events. If all of an alert rule's conditions match the logged event the action(s) configured in the alert rule is performed.
Enable determine if the alert rule is enabled.
Class is the type of event this rule matches. Selecting the Class will determine what Fields are available in the conditions.
Conditions lists the fields within the event object to be checked. If all of the conditions match then the rule will match.
Enable Thresholds limits the alert from firing until it reaches a certain frequency threshold.
Exceeds Threshold Limit is the frequency limit for which this condition will match. If the frequency is greater than this value, then the threshold conditions matches.
Over Timeframe defines the time range, in seconds, to use to compute the frequency.
Grouping Field defines how to group thresholds by an attribute field in the events. This field is optional.
If Exceeds Threshold Limit is 100 and Over Timeframe is 60, then the threshold condition will only match when this rules other conditions match approximately 100 times over any 60 second period. If Group Field is set to "CClientAddr" then the threshold load is grouped by "CClientAddr" value in the event objects. Using the above example this would mean that the alert would only fire when a specific "CClientAddr" like "192.168.1.100" does something over 100 times within 60 seconds. The threshold value for other clients like "192.168.1.150" is tracked separately.
Log Alert logs the event to the Alert Event Log
Send Alert sends an email to all administrators' emails describing the event.
Limit Send Frequency limits the number of times a rule can send an alert email To once per the configured amount of minutes. For some cases, like a low disk space alert, this is useful to limit the number of alerts sent so that an alert is not sent every minute.
Adding Alert Rules
Writing and designing alert rules can be a bit of an art.
Start by finding an event that describes the action that you want to be alerted about. The Event Definitions describes all the event objects and the associated attributes on each object.
Set the Class to the event you want to alert about, then add conditions that check the fields to look for the events you are interested in.
As an example, lets say we want to setup an alert for when a specific website is visited by a specific user. As a Class select HttpRequestEvent and then as a field add domain = example.com and sessionEvent.username = example_user
We want to know if this user visits this website a single time, so we don't want to add a threshold. We want it to log this alert so we want to check Log and we want to send an email so we're going to check Send Email
However, in reality when a user visits a website it does a lot of separate HTTP requests to load all of the components. We don't want to receive 20 emails each time a user visits a single page on that website. As we want to check Limit Send Frequency to 20 minutes so that we aren't flooded with emails.
There are many other alert rules that are not enabled by default that can provide some common examples.