270 lines
12 KiB
Plaintext
270 lines
12 KiB
Plaintext
[[email-services]]
|
|
=== Configuring Watcher to Send Email
|
|
You can configure Watcher to send email from any SMTP email service. Email messages can contain
|
|
basic HTML tags. You can control which tags are allowed by
|
|
<<email-html-sanitization, Configuring HTML Sanitization Options>>.
|
|
|
|
[[email-account]]
|
|
==== Configuring Email Accounts
|
|
You configure the accounts Watcher can use to send email in your `elasticsearch.yml` configuration file.
|
|
Each account configuration has a unique name and specifies all of the SMTP information needed
|
|
to send email from that account. You can also specify defaults for all emails that are sent through
|
|
the account. For example, you can set defaults for the `from` and `bcc` fields to ensure that all
|
|
emails are sent from the same address and always blind copied to the same address.
|
|
|
|
IMPORTANT: If your email account is configured to require two step verification,
|
|
you need to generate and use a unique App Password to send email from
|
|
Watcher. Authentication will fail if you use your primary password.
|
|
|
|
If you configure multiple email accounts, you specify which account the email should be sent
|
|
with in the <<actions-email, email>> action. If there is only one account configured, you
|
|
do not have to specify the `account` attribute in the action definition. However, if you configure
|
|
multiple accounts and omit the `account` attribute, there is no guarantee which account will be
|
|
used to send the email.
|
|
|
|
To add an email account, set the `watcher.actions.email.service.account` property in
|
|
`elasticsearch.yml`. See <<email-account-attributes, Email Account Attributes>> for the
|
|
supported attributes.
|
|
|
|
For example, the following snippet configures a single Gmail account named `work`.
|
|
|
|
[source,yaml]
|
|
--------------------------------------------------
|
|
watcher.actions.email.service.account:
|
|
work:
|
|
profile: gmail
|
|
email_defaults:
|
|
from: 'John Doe <john.doe@host.domain>'
|
|
bcc: archive@host.domain
|
|
smtp:
|
|
auth: true
|
|
starttls.enable: true
|
|
host: smtp.gmail.com
|
|
port: 587
|
|
user: <username>
|
|
password: <password>
|
|
--------------------------------------------------
|
|
|
|
[[email-profile]]
|
|
The _email profile_ defines a strategy for building a MIME message. As with almost every standard
|
|
out there, different email systems interpret the MIME standard differently and have slightly
|
|
different ways of structuring MIME messages. Watcher provides three email profiles: `standard`
|
|
(default), `gmail`, and `outlook`.
|
|
|
|
If you are using Gmail or Outlook, we recommend using the corresponding profile. Use the `standard`
|
|
profile if you are using some other email system. For more information about configuring Watcher
|
|
to work with different email systems, see:
|
|
|
|
* <<gmail, Sending Email from Gmail>>
|
|
* <<outlook, Sending Email from Outlook>>
|
|
* <<exchange, Sending Email from Exchange>>
|
|
* <<amazon-ses, Sending Email from Amazon SES>>
|
|
|
|
[[email-account-attributes]]
|
|
.Email Account Attributes
|
|
[options="header"]
|
|
|======
|
|
| Name | Required | Default | Description
|
|
| `profile` | no | standard | The <<email-profile, profile>> to use to
|
|
build the MIME messages that are sent from
|
|
the account. Valid values: `standard`
|
|
(default), `gmail` and `outlook`.
|
|
| `email_defaults.*` | no | - | An optional set of email attributes to use
|
|
as defaults for the emails sent from the
|
|
account. See <<email-action-attributes,
|
|
Email Action Attributes>> for the supported
|
|
attributes. for the possible email
|
|
attributes)
|
|
| `smtp.auth` | no | false | When `true`, attempt to authenticate the
|
|
user using the AUTH command.
|
|
| `smtp.host` | yes | - | The SMTP server to connect to.
|
|
| `smtp.port` | no | 25 | The SMTP server port to connect to.
|
|
| `smtp.user` | yes | - | The user name for SMTP.
|
|
| `smtp.password` | no | - | The password for the specified SMTP user.
|
|
| `smtp.starttls.enable` | no | false | When `true`, enables the use of the
|
|
`STARTTLS` command (if supported by
|
|
the server) to switch the connection to a
|
|
TLS-protected connection before issuing any
|
|
login commands. Note that an appropriate
|
|
trust store must configured so that the
|
|
client will trust the server's certificate.
|
|
Defaults to `false`.
|
|
| `smtp.*` | no | - | SMTP attributes that enable fine control
|
|
over the SMTP protocol when sending messages.
|
|
See https://javamail.java.net/nonav/docs/api/com/sun/mail/smtp/package-summary.html[com.sun.mail.smtp]
|
|
for the full list of SMTP properties you can
|
|
set.
|
|
|======
|
|
|
|
[[gmail]]
|
|
===== Sending Email From Gmail
|
|
|
|
Use the following email account settings to send email from the https://mail.google.com[Gmail]
|
|
SMTP service:
|
|
|
|
[source,yaml]
|
|
--------------------------------------------------
|
|
watcher.actions.email.service.account:
|
|
gmail_account:
|
|
profile: gmail
|
|
smtp:
|
|
auth: true
|
|
starttls.enable: true
|
|
host: smtp.gmail.com
|
|
port: 587
|
|
user: <username>
|
|
password: <password>
|
|
--------------------------------------------------
|
|
|
|
If you get an authentication error that indicates that you need to continue the
|
|
sign-in process from a web browser when Watcher attempts to send email, you need
|
|
to configure Gmail to https://support.google.com/accounts/answer/6010255?hl=en[Allow Less
|
|
Secure Apps to access your account].
|
|
|
|
If two-step verification is enabled for your account, you must generate and use
|
|
a unique App Password to send email from Watcher.See
|
|
https://support.google.com/accounts/answer/185833?hl=en[Sign in using App Passwords]
|
|
for more information.
|
|
|
|
[[outlook]]
|
|
===== Sending Email from Outlook.com
|
|
|
|
Use the following email account settings to send email action from the
|
|
https://www.outlook.com/[Outlook.com] SMTP service:
|
|
|
|
[source,yaml]
|
|
--------------------------------------------------
|
|
watcher.actions.email.service.account:
|
|
outlook_account:
|
|
profile: outlook
|
|
smtp:
|
|
auth: true
|
|
starttls.enable: true
|
|
host: smtp-mail.outlook.com
|
|
port: 587
|
|
user: <username>
|
|
password: <password>
|
|
--------------------------------------------------
|
|
|
|
NOTE: You need to use a unique App Password if two-step verification is enabled.
|
|
See http://windows.microsoft.com/en-us/windows/app-passwords-two-step-verification[App
|
|
passwords and two-step verification] for more information.
|
|
|
|
[[amazon-ses]]
|
|
===== Sending Email from Amazon SES (Simple Email Service)
|
|
|
|
Use the following email account settings to send email from the
|
|
http://aws.amazon.com/ses[Amazon Simple Email Service] (SES) SMTP service:
|
|
|
|
[source,yaml]
|
|
--------------------------------------------------
|
|
watcher.actions.email.service.account:
|
|
ses_account:
|
|
smtp:
|
|
auth: true
|
|
starttls.enable: true
|
|
starttls.required: true
|
|
host: email-smtp.us-east-1.amazonaws.com <1>
|
|
port: 587
|
|
user: <username>
|
|
password: <password>
|
|
--------------------------------------------------
|
|
|
|
<1> `smtp.host` varies depending on the region
|
|
|
|
NOTE: You need to use your Amazon SES SMTP credentials to send email through
|
|
Amazon SES. For more information, see http://docs.aws.amazon.com/ses/latest/DeveloperGuide/smtp-credentials.html[Obtaining Your Amazon SES SMTP Credentials].
|
|
|
|
[[exchange]]
|
|
===== Sending Email from Microsoft Exchange
|
|
|
|
Use the following email account settings to send email action from Microsoft Exchange:
|
|
|
|
[source,yaml]
|
|
--------------------------------------------------
|
|
watcher.actions.email.service.account:
|
|
exchange_account:
|
|
profile: outlook
|
|
email_defaults:
|
|
from: <email address of service account> <1>
|
|
smtp:
|
|
auth: true
|
|
starttls.enable: true
|
|
host: <your exchange server>
|
|
port: 587
|
|
user: <email address of service account> <2>
|
|
password: <password>
|
|
--------------------------------------------------
|
|
|
|
<1> Some organizations configure Exchange to validate that the `from` field is a
|
|
valid local email account.
|
|
<2> Many organizations support use of your email address as your username, though
|
|
it is a good idea to check with your system administrator if you receive
|
|
authentication-related failures.
|
|
|
|
|
|
// [[postfix]]
|
|
// ===== Sending Email from Postfix
|
|
|
|
// Use the following email account settings to send email from the http://www.postfix.org[Postfix] SMTP service:
|
|
|
|
// [source,yaml]
|
|
// --------------------------------------------------
|
|
// TODO
|
|
// --------------------------------------------------
|
|
|
|
[[email-html-sanitization]]
|
|
==== Configuring HTML Sanitization Options
|
|
|
|
The `email` action supports sending messages with an HTML body. However, for security reasons,
|
|
Watcher https://en.wikipedia.org/wiki/HTML_sanitization[sanitizes] the HTML.
|
|
|
|
You can control which HTML features are allowed or disallowed by configuring the
|
|
`watcher.actions.email.html.sanitization.allow` and
|
|
`watcher.actions.email.html.sanitization.disallow` settings in `elasticsearch.yml`. You can specify
|
|
individual HTML elements and the feature groups described in the following table. By default,
|
|
Watcher allows the following features: `body`, `head`, `_tables`, `_links`, `_blocks`, `_formatting`
|
|
and `img:embedded`.
|
|
|
|
|
|
[options="header"]
|
|
|======
|
|
| Name | Description
|
|
|
|
| `_tables` | All table related elements: `<table>`, `<th>`, `<tr>` and `<td>`.
|
|
|
|
| `_blocks` | The following block elements: `<p>`, `<div>`, `<h1>`, `<h2>`, `<h3>`,
|
|
`<h4>`, `<h5>`, `<h6>`, `<ul>`, `<ol>`, `<li>` and `<blockquote>`.
|
|
|
|
| `_formatting` | The following inline formatting elements: `<b>`, `<i>`, `<s>`, `<u>`,
|
|
`<o>`, `<sup>`, `<sub>`, `<ins>`, `<del>`, `<strong>`, `<strike>`,
|
|
`<tt>`, `<code>`, `<big>`, `<small>`, `<br>`, `<span>` and `<em>`.
|
|
|
|
| `_links` | The `<a>` element with an `href` attribute that points to a URL using
|
|
the following protocols: `http`, `https` and `mailto`.
|
|
|
|
| `_styles` | The `style` attribute on all elements. Note that CSS attributes
|
|
are also sanitized to prevent XSS attacks.
|
|
|
|
| `img` or `img:all` | All images (external and embedded).
|
|
|
|
| `img:embedded` | Only embedded images. Embedded images can only use the `cid:` URL
|
|
protocol in their `src` attribute.
|
|
|======
|
|
|
|
For example, the following settings allow the HTML to contain tables and block elements, but
|
|
disallow `<h4>`, `<h5>` and `<h6>` tags.
|
|
|
|
[source,yaml]
|
|
--------------------------------------------------
|
|
watcher.actions.email.html.sanitization:
|
|
allow: _tables, _blocks
|
|
disallow: h4, h5, h6
|
|
--------------------------------------------------
|
|
|
|
To disable sanitization entirely, add the following setting to `elasticsearch.yml`:
|
|
|
|
[source,yaml]
|
|
--------------------------------------------------
|
|
watcher.actions.email.html.sanitization.enabled: false
|
|
-------------------------------------------------- |