Events
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 Event Definitions page details all of the events and the attributes.
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.
Unlike most rules, all Alert rules are evaluated even beyond the first matching rule.
Each logged event is represented by a JSON object. As each event is logged to the database the alert rules are evaluated. 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.
- 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.
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.
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 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.
Unlike most rules, all Trigger rules are evaluated even beyond the first matching rule.
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.
- 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.
- 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.
Syslog
Syslog sends events via syslog messages to a remote syslog server. To use syslog simply install a syslog receiver on another server, then enable syslog and configure as necessary.. Some syslog products are easier to set up than others. Kiwi, a third-party syslog daemon, is a favorite of many Untanglers using Windows, while those on *nix can use rsyslog.
- Host: The host name or IP address of the Syslog daemon that is authorized to receive syslog messages from the Untangle Server. Do not set the Host to the Untangle box itself - this will result in the hard drive filling up very quickly and most likely crashing the box.
- Port: The UDP port to send syslog messages to the syslog daemon. 514 is the default as this is the default syslog port.
- Protocol: The protocol to use to send syslog messages. The default is UDP.
Syslog Rules
WARNING: Syslog can be a very expensive operation. If configured to send all (or most) events it can seriously negatively impact the performance of the server.
Syslog Rules determine which events are sent via syslog.
Unlike most rules, all Syslog rules are evaluated even beyond the first matching rule.
- 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.
- Remote Syslog determines if the event is sent via syslog.
To send all events via syslog simply create one rule where Class = All and no conditions.
To send specific events to a syslog server configure the Syslog Rules to send the specific events to the syslog server.
Email Template
You can customize the content of email alerts by editing the email template. Items surrounded by the percent symbol represent system variables. You can use these throughout the Subject or Body of the message. The table below describes each variable.
| Variable | Information |
|---|---|
| System.company | Your company name defined in Branding Manager. |
| Alert.description | The event description of the associated alert rule. |
| System.host | The name of your NG Firewall system. |
| Event.class | The event class of the associated alert rule. |
| Event.summary | The event summary of the associated alert rule. |
| Event.values.keyvalue | The extended event details of the associated alert rule. |
The preview window shows in real time how your changes to the Subject or Body will appear in the email message content.
