Events from Email

SL1 can generate events based on emails that the system receives from external devices. Before configuring SL1 to generate events from email, you must follow the steps listed in the General Inbound and Outbound Email Settings section.

This section describes how to perform the following configuration tasks that are required before SL1 can generate events from email:

An email originator. An email originator is a policy that defines how an inbound email should be processed to generate a log message for a device in the system.
An email event policy. An email event policy defines how log messages generated from emails should generate events.
Correctly formatted inbound emails.

Use the following menu options to navigate the SL1 user interface:

To view a pop-out list of menu options, click the menu icon ().
To view a page containing all of the menu options, click the Advanced menu icon ().

System Settings that Affect Events from Email

The Behavior Settings page (System > Settings > Behavior) allows you to define global parameters. The following parameter affects Event from Email policies:

Strip FQDN From Inbound Email Device Name. This field in the Behavior Settings page specifies how SL1 will match the regular expression for the device name in an Event from Email policy. Choices are:

Enabled. SL1 will search the text string in the incoming email and match all characters up to the first period that appears in the text string. If multiple devices in SL1 match the characters up to the first period (for example, my_device.1 and my_device.2), SL1 will align the event with the matching device with the highest Device ID.
Disabled. SL1 will search the text string in the incoming email for a match for the device name. The text string must include an exact match to the regular expression (defined in the Events from Email policy), including any text following a period in the device name. If SL1 does not find an exact match in the incoming email, SL1 creates an entry in the system log.

Inbound Email Alert Message. In each event policy, the First Match String and Second Match String fields specify the string or regular expression used to correlate the event with a log message. To trigger an event, the text of a log message must match the value in the First Match String and Second Match String fields in that event's policy. For Events from Email policies, this field specifies whether only the email message body will be written to the device log or whether both the email message subject and email message body will be written to the device log. Choices are:

Email Message Body Only. Only the email message body is written to the device log. The First Match String and Second Match String fields can examine and match only the email message body.
Email Message Subject and Body. Both the email message body and the email message subject are written to the device log. The First Match String and Second Match String fields can examine and match against both the email message body.

The global setting Inbound Email Alert Message affects how events are triggered. This field does not affect the Regex Pattern field in the Event from Email policy. The Regex Pattern field in an Event from Email policy specifies the device log to which the alert should be written.

Viewing the List of Event From Email Policies

To sort the list of policies, click on a column heading. The list will be sorted by the column value, in ascending order. To sort by descending order, click the column heading again. The Edit Date column sorts by descending order on the first click; to sort by ascending order, click the column heading again.

The Emailer Redirection page (Registry > Events > Inbound Email) displays the following information about each Event from Email policy:

Originator Address. Fully-qualified email address from which SL1 will accept event messages. If an incoming email message comes from the same email address as specified in this field, SL1 will process that email message as an event. The originator address is usually the address of another monitoring system that is escalating events through SL1. When used in this way, SL1 becomes a "manager of managers."

Alignment Type. Specifies how SL1 should handle inbound email messages that do not include a match with the Regex Pattern. The Regex Pattern tells SL1 which element to align with the resulting event. Choices are:

If device not found, discard unmatched email. If the inbound email does not include text that matches the Regex Pattern, discard the email. No event will be created from this instance of the inbound email.

If device not found, align unmatched email with default element. If the inbound email does not include text that matches the Regex Pattern, align the email with the element specified in the Default Element field. The resulting event will be aligned with the Default Element.
Override device search, align email with default element. Do not try to match the email with the Regex Pattern. Instead, automatically align the email with the element specified in the Default Element field. The resulting event will be aligned with the Default Element.

Regex Type. Part of the email message where the Regex Pattern will appear. Choices are:

Subject
Body

Regex Pattern. A specific string that appears directly before the name or IP address of the device to associate with the event message. SL1 will then find the device name or IP address in the email message and associate the message with the appropriate device. If the Regex Type is Body, and the email body is in HTML format, SL1 will strip out the HTML constructs before searching for the regex pattern.

NOTE: This string does not trigger the event; this string only informs SL1 which device to associate with the event message. SL1 will search all event definitions with a source of Email and then compare the entire email message to the Match String field in each event definition.

Default Element. If in the Alignment Type field, one of the following options is selected:

If device not found, align unmatched email with default element.
Override device search, align email with default element.

then the Default Element field specifies the default element to use. The default element can be an Organization, Device, Asset, Interface, Vendor, User Account, or Virtual interface.

NOTE: If the Default Element is not associated with the current user's organization, this field will display the value Restricted.

ID. Unique, numeric ID associated with the Event from Email policy. SL1 automatically assigns this ID to the policy.
Edit User. The user who created or last edited the Event from Email policy.
Edit Date. Date the Event from Email policy was created or last edited.

Filtering the List of Event From Email Policies

The Emailer Redirection page includes six filters, in the top row in the list of policies. You can specify one or more parameters to filter the display of Event from Email policies. Only Event from Email policies that meet all the filter criteria will be displayed in the Emailer Redirection page.

You can filter by one or more of the following parameters. The list of Event from Email policies is dynamically updated as you select each filter.

For each filter except Edit Date, you must enter text to match against. SL1 will search for Event from Email policies that match the text, including partial matches. Text matches are not case-sensitive. You can use the following special characters in each filter:

, (comma). Specifies an "or" operation. For example:

"dell, micro" would match all values that contain the string "dell" OR the string "micro".

& (ampersand). Specifies an "and" operation. For example:

"dell & micro" would match all values that contain the string "dell" AND the string "micro".

! (exclamation mark). Specifies a "not" operation. For example:

"!dell" would match all values that do not contain the string "dell".

Originator Address. You can enter text to match, including special characters (comma, ampersand, and exclamation mark), and the Emailer Redirection page will display only Event from Email policies that have a matching originator email address.
Alignment Type. You can enter text to match, including special characters (comma, ampersand, and exclamation mark), and the Emailer Redirection page will display only Event from Email policies that have a matching alignment type.
Regex Type. You can enter text to match, including special characters (comma, ampersand, and exclamation mark), and the Emailer Redirection page will display only Event from Email policies that are associated with a matching regex type (either Body or Subject).
Regex Pattern. You can enter text to match, including special characters (comma, ampersand, and exclamation mark), and the Emailer Redirection page will display only Event from Email policies that include a matching regex pattern.
Default Element. You can enter text to match, including special characters (comma, ampersand, and exclamation mark), and the Emailer Redirection page will display only Event from Email policies that include a matching default element.
ID. You can enter text to match, including special characters (comma, ampersand, and exclamation mark), and the Emailer Redirection page will display only Event from Email policies that include a matching ID.
Edit User. You can enter text to match, including special characters (comma, ampersand, and exclamation mark), and the Emailer Redirection page will display only Event from Email policies that have a matching "created by" or "edited by" value.

Edit Date. You can select from a list of time periods. The Emailer Redirection page will display only Event from Email policies that have been created or edited within that time period. Choices are:

All. Display all policies that match the other filters.

Last Minute. Display only policies that have been created within the last minute.
Last Hour. Display only policies that have been created within the last hour.
Last Day. Display only policies that have been created within the last day.
Last Week. Display only policies that have been created within the last week.
Last Month. Display only policies that have been created within the last month.
Last Year. Display only policies that have been created within the last year.

Configuring an Event from Email Policy

SL1 uses each Event from Email policy to determine whether an incoming email comes from a source that is authorized to trigger events. Perform the following steps to configure an email originator:

Go to the Emailer Redirection page (Registry > Events > Inbound Email):

In the Emailer Redirection page, click the Create button. The Add Policy modal page appears.

To define the Event from Email policy, supply values in the following fields:

Originator Address. Enter the fully-qualified email address from which SL1 will accept event messages. If an incoming email message comes from the same email address as specified in this field, SL1 will process that email message as an event. The originator address is usually the address of another monitoring system that is escalating events through SL1. When used in this way, SL1 becomes a "manager of managers."

Alignment Type. Specifies how SL1 should handle inbound email messages that do not include a match with the Regex Pattern. The Regex Pattern tells SL1 which element to align with the resulting event. Choices are:

If device not found, discard unmatched email. If the inbound email does not include text that matches the Regex Pattern, discard the email. No event will be created from this instance of the inbound email.

If device not found, align unmatched email with default element. If the inbound email does not include text that matches the Regex Pattern, align the email with the element specified in the Default Element field. The resulting event will be aligned with the Default Element.
Override device search, align email with default element. Do not try to match the email with the Regex Pattern. Instead, automatically align the email with the element specified in the Default Element field. The resulting event will be aligned with the Default Element.

Regex Pattern. Enter a specific string that appears directly before the name or IP address of the device to associate with the event message. SL1 will then find the device name or IP address in the email message and associate the message with the appropriate device. See the Formatting Inbound Emails section for more information.
Regex Pattern Type Specify if you want advanced control over the regex behavior. Choices are:

Classic. Select this option if you want the SL1 to use simple text matching to search for the Regex Pattern.
Advanced. Select this option if you want the SL1 to search for the Regex Pattern using advanced regex. Advanced regex patterns can be up to 255 character in length and support all of the special characters supported by Python regex.

NOTE: The Regex Pattern string does not trigger the event; this string only informs SL1 which device to associate with the event message. To trigger an event, SL1 will search all event definitions with a source of Email and then compare the entire email message to the Match String field in each event definition.

Regex Type. Select either Body or Subject from the drop-down list. This is the part of the email message where the Regex Pattern will appear.
Default Element. If you selected If device not found, align unmatched email with default element or Override device search, align email with default element in the Alignment Type field, then the Default Element field specifies the default element to use. Clicking on the binoculars icon () opens the Element Alignment modal page, where you can search for and select a default element. The default element can be an Organization, Device, Asset, Interface, Vendor, User Account, or Virtual Interface.

NOTE: If the Default Element is not associated with the current user's organization, this field will display the value Restricted.

Click the Save button.
An email originator must be created for each address/regex combination that you will use to create events from email.

Creating an Event Policy of Type "Email"

When SL1 receives an inbound email message that is authorized to trigger events and successfully matches the email to a device, SL1 compares the email message against all event policies with a source of Email. If the email message does not match one or more event policies, SL1 will not generate an event but will add the email message to the device logs of the matched device.

This section will describe how to create an event policy of type "email" and how to define matching criteria based on the contents of the email. For information on additional event options, such as occurrence count/time, detection weight, identifier patterns/formatting, auto-clearing, and expiry delays, see the section on Events.

To create an event policy of type "email", perform the following steps:

Go to the Event Policy Manager page (Registry > Events > Event Manager):

Click the Create button. The Event Policy Editor page appears:

To define an event policy based on an incoming email message, supply values in the following fields:

Event Source. Select Email from the drop-down list.
Policy Name. Enter a name for the policy.
Event Message. Enter the message associated with this event. To use the body of the email as the event message, leave the default value of "%M" in this field. For more information on Event Message formatting, see the section on Events.
Event Severity. Select a severity for this event from the drop-down list.
Policy Description. Enter a description of the event. This field is optional.

Click the Save button.
The event policy will now match every valid email message received from authorized external devices. To configure the event policy to match only against emails containing specific text, perform the following steps.

Click the Advanced tab:

Provide values in each of the following fields:

Match Logic. Select either Text Search or Regex Match from the drop-down list. If you select Text Search, the SL1 system will use simple text matching to compare strings. If you select Regex Match, the SL1 system will use regular expressions to compare strings.
First Match String. Enter the text string or regular expression that SL1 will compare to the text in the email subject or body.
Second Match String. Optionally, enter a second text string or regular expression. If you enter a value in this field, the email must match both the contents of the First Match String field and the Second Match String field for the event to trigger.

Match Strings are compared to the subject and body of received emails.

Click the Save button.

Formatting Inbound Email

For SL1 to process events from inbound emails, you must configure your external devices to send email using certain formatting rules. Inbound emails must meet the following requirements to be processed as events by SL1:

The email must be sent to the following address:

notify@domain-name-of-SL1

Where "domain-name-of-SL1" is one of the fully qualified domain names of the Database Server or All-In-One Appliance, i.e., one of the domain names you entered in the Authorized Email Domains field in the Email Settings page.

The "from" address used by the external device must match an address defined in the Originator Address field in an email originator policy.
The email message must contain a string that matches the regular expression defined in the Regex Pattern field in the email originator policy. If the email originator has the Regex Type set to Body, the string must be included in the email body. If the email originator has the Regex Type set to Subject, the string must be included in the email subject.

The Regex Pattern string must be followed by the IP address, hostname, or device ID of a device monitored by the SL1 system. If an event is created, it will be associated with the specified device. For example, if the email originator has the Regex Pattern field set as "Event," the Regex Type set to Subject, and a device with an IP address of 192.168.1.1 is monitored in the system, a valid email subject would be:

Event 192.168.1.1

NOTE: There must be a space between the regex pattern and the IP address, hostname, or device ID.

If you are using the "%M" substitution in your email event policies, ensure the message you wish to substitute is contained within the body of the email.
If you are using Match Strings in your email event policies, ensure that matching text is contained within the body of the email.

NOTE: You can specify how an Event from Email policy will match a regular expression to a device name in the Behavior Settings page (System > Settings > Behavior).

How SL1 Processes Events from Email Policies

When SL1 receives an email from an Events from Email policy, SL1 examines all the Events from Email policies and executes the first policy that matches the incoming email.

SL1 will log debug messages for each policy that did not match the incoming email message. After SL1 finds the first matching policy, SL1 does not examine any other policies and does not generate any more debug messages.

If SL1 does not find any Events from Email policies that match the incoming email, SL1 generates the error message "E701 Could not match device to email...".