Events
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.
Alerts
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.
Triggers
Triggers are similar to Alert rules, however instead of alerting when something interesting happens, trigger rules can "tag" a specific host, device, or user for a specific period of time.
This allows the system to keep state on the different hosts on the network, which can serve several purposes. For example, you can tag a specific host/device/user as using a specific application when the application is used.
There are several rules that are included but not enabled to provide some examples.
Action Type determines the action taken
# Tag Host will tag the specified host with the specified tag. # Untag Host will remove the specified tag from the specified host. # Tag User will tag the specified user with the specified tag. # Untag User will remove the specified tag from the specified user. # Tag Device will tag the specified device with the specified tag. # Untag Device will remove the specified tag from the specified device.
Target identifies the specific host/device/user. If its a single attribute name for example 'cClientAddr' it will look up to 3 layers deep within an object for any attribute named cClientAddr. If it is a fully qualified name like 'sessionEvent.cClientAddr' it will look at that specific attribute within the specified subobject.
Tag Name specified the string (name) of the tag to be given or removed.
Tag Lifetime specifies the lifetime of the tag when adding a tag. After the lifetime expires the tag will disappear.
