173 lines
5.2 KiB
Markdown
173 lines
5.2 KiB
Markdown
Mailer Integration
|
|
==================
|
|
|
|
Send emails for alerts received by Alerta.
|
|
|
|
For help, join [](https://slack.alerta.dev)
|
|
|
|
Overview
|
|
--------
|
|
|
|
It is specifically designed to reduce the number of unnecessary emails by
|
|
ensuring that alerts meet the following criteria:
|
|
|
|
* must not be a duplicate alert (ie. ``repeat != True``)
|
|
* must have status of ``open`` or ``closed``
|
|
* must have a current severity *OR* previous severity of ``critical`` or ``major`` by default
|
|
* must not have been cleared down within 30 seconds (to prevent flapping alerts spamming)
|
|
|
|
To achieve the above, alerts are actually held for a minimum of 30 seconds
|
|
before they generate emails.
|
|
|
|
Installation
|
|
------------
|
|
|
|
Clone the GitHub repo and run:
|
|
|
|
$ python setup.py install
|
|
|
|
Or, to install remotely from GitHub run:
|
|
|
|
$ pip install git+https://github.com/alerta/alerta-contrib.git#subdirectory=integrations/mailer
|
|
|
|
Configuration
|
|
-------------
|
|
|
|
Settings are changed using an ini-style configuration file that is also
|
|
used for the ``alerta`` cli.
|
|
|
|
A section called ``[alerta-mailer]`` is used to clearly define which
|
|
settings apply to the mailer script.
|
|
|
|
```
|
|
[alerta-mailer]
|
|
key = demo-key ; must have "write:heartbeats" scope
|
|
mail_to = john.doe@gmail.com,jane.doe@gmail.com
|
|
mail_from = your.email@gmail.com
|
|
amqp_url = redis://localhost:6379/
|
|
dashboard_url = http://localhost:8000
|
|
smtp_username = alt.email@gmail.com
|
|
smtp_password = okvqhitqomebufyv
|
|
smtp_use_ssl = False
|
|
debug = True
|
|
skip_mta = False
|
|
email_type = text
|
|
```
|
|
|
|
If you are using Google Gmail as the SMTP server. You will need to create
|
|
an application-specific password.
|
|
|
|
You can skip the use of an SMTP server using the option 'skip_mta'. Note
|
|
that in most cases is recommended to use an SMTP outbound server as the
|
|
MTA, but if you know what you're doing you can use skip_mta and then
|
|
``alerta-mailer`` will resolve the proper destination MX DNS record for
|
|
each address and attempt to deliver the email directly. Some email
|
|
systems may detect certain email patterns to black-list you, such as
|
|
sending email using a hostname such as 'localhost'. You may need to
|
|
set the 'mail_localhost' option or set a proper FQDN in your server to
|
|
avoid this.
|
|
|
|
You can also use IP-authentication in your own SMTP server (by only
|
|
white-listing the alerta server IP), in such cases you should not
|
|
set the 'smtp_password' option to skip authentication altogether.
|
|
|
|
You can also set an alternate SMTP username for authenticating against
|
|
the email server if it differs from the 'mail_from' address. This is
|
|
required when using an email delivery service like sendgrid.
|
|
|
|
Application-specific passwords
|
|
https://support.google.com/accounts/answer/185833?hl=en
|
|
|
|
|
|
Rules File
|
|
----------
|
|
|
|
Notifications to other emails according regexp criteria can be enabled,
|
|
creating a JSON formatted file under ```alerta.rules.d/``` with the
|
|
following format:
|
|
|
|
```
|
|
[
|
|
{
|
|
"name": "foo",
|
|
"fields": [
|
|
{"field": "resource", "regex": "db-\w+"}
|
|
],
|
|
"contacts": ["dba@lists.mycompany.com", "dev@lists.mycompany.com"]
|
|
},
|
|
{
|
|
"name": "bar",
|
|
"fields": [
|
|
{"field": "resource", "regex": "web-\w+"}
|
|
],
|
|
"contacts": ["dev@lists.mycompany.com"],
|
|
"exclude" : true
|
|
}
|
|
]
|
|
```
|
|
|
|
``field`` is a reference to the alert object, regex is a valid python
|
|
regexp and contacts are a list of mails who will receive an e-mail if
|
|
the regular expression matches.
|
|
|
|
Multiple ``field`` dictionary can be supplied and all ``regex`` must
|
|
match for the email to be sent.
|
|
|
|
If the ``exclude`` parameter is set, contact list will be cleared and
|
|
replaced with only the contacts of the current matched rule.
|
|
|
|
Environment Variables
|
|
---------------------
|
|
|
|
``SMTP_USERNAME`` - can be used instead of smtp_username in the configuration file,
|
|
defaults to the value set for the mail_from field.
|
|
``SMTP_PASSWORD`` - can be used instead of smtp_password in the configuration file.
|
|
|
|
Email Format
|
|
------------
|
|
|
|
The format for emails uses a templating engine called Jinja2.
|
|
|
|
The variable email_type can have 2 possible values:
|
|
|
|
- html: for just html emails, will fallback to text for text clients (mutt, etc)
|
|
- text: for just plain text emails
|
|
|
|
Multiple files config support
|
|
-----------------------------
|
|
|
|
Multiple configs files are supported for alerta-mailer you just need
|
|
to create a directory with the name of the config file with the ``.d``
|
|
suffix, i.e: (assuming you have a config file called ``mailer.conf``
|
|
on ``/etc/alerta/`` you will need to create the directory ``mailer.conf.d``
|
|
at the same level of your config file (mailer.conf in this example),
|
|
and place all your configs there.
|
|
|
|
Multiple email rules files can be supplied as well and rules are
|
|
going to be applied top-down as they appear on the filesystem and
|
|
on the files themselves.
|
|
|
|
Deployment
|
|
----------
|
|
|
|
$ export SMTP_PASSWORD=okvqhitqomebufyv
|
|
$ alerta-mailer
|
|
|
|
Dependencies
|
|
------------
|
|
|
|
The Alerta server *MUST* have the AMQP plugin enabled and configured.
|
|
See [AMQP](plugins/amqp) for more info.
|
|
|
|
Testing
|
|
-------
|
|
|
|
To execute unit-tests run:
|
|
|
|
$ python setup.py test
|
|
|
|
License
|
|
-------
|
|
|
|
Copyright (c) 2015-2016 Nick Satterly and [AUTHORS](/AUTHORS). Available under the MIT License.
|