450 lines
20 KiB
Plaintext
450 lines
20 KiB
Plaintext
[[actions-email]]
|
|
=== Email Action
|
|
|
|
Use the `email` action to send email notifications. To send email, you must
|
|
<<configuring-email, configure at least one email account>> in
|
|
`elasticsearch.yml`.
|
|
|
|
Email notifications can be plain text or styled using HTML. You can include
|
|
information from the watch execution payload using <<templates, templates>>
|
|
and attach the entire watch payload to the message.
|
|
|
|
See <<email-action-attributes>> for the supported attributes. Any attributes that
|
|
are missing from the email action definition are looked up in the email
|
|
account configuration. The required attributes must either be set in the email
|
|
action definition or the account's `email_defaults`.
|
|
|
|
[[configuring-email-actions]]
|
|
==== Configuring Email Actions
|
|
|
|
You configure email actions in the `actions` array. Action-specific attributes
|
|
are specified using the `email` keyword.
|
|
|
|
For example, the following email action uses a template to include data from
|
|
the watch payload in the email body:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
"actions" : {
|
|
"send_email" : { <1>
|
|
"email" : { <2>
|
|
"to" : "<username>@<domainname>", <3>
|
|
"subject" : "Watcher Notification", <4>
|
|
"body" : "{{ctx.payload.hits.total}} error logs found" <5>
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
<1> The id of the action.
|
|
<2> The action type is set to `email`.
|
|
<3> One or more addresses to send the email to. Must be specified in the
|
|
action definition or in the email account configuration.
|
|
<4> The subject of the email can contain static text and Mustache <<templates,
|
|
templates>>.
|
|
<5> The body of the email can contain static text and Mustache <<templates,
|
|
templates>>. Must be specified in the action definition or in the email
|
|
account configuration.
|
|
|
|
[[configuring-email-attachments]]
|
|
==== Configuring Email Attachments
|
|
|
|
You can attach the execution context payload or data from an any HTTP service to
|
|
the email notification. There is no limit on the number of attachments you can
|
|
configure.
|
|
|
|
To configure attachments, specify a name for the attached file and the type of
|
|
attachment: `data`, `http` or `reporting`. The `data` attachment type attaches the execution
|
|
context payload to the email message. The `http` attachment type enables
|
|
you to issue an HTTP request and attach the response to the email message. When
|
|
configuring the `http` attachment type, you must specify the request URL. The
|
|
`reporting` attachment type is a special type to include PDF rendered dashboards
|
|
from kibana. This type is consistently polling the kibana app if the dashboard
|
|
rendering is done, preventing long running HTTP connections, that are potentially
|
|
killed by firewalls or load balancers inbetween.
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
"actions" : {
|
|
"email_admin" : {
|
|
"email": {
|
|
"to": "'John Doe <john.doe@example.com>'",
|
|
"attachments" : {
|
|
"my_image.png" : { <1>
|
|
"http" : { <2>
|
|
"content_type" : "image.png",
|
|
"request" : {
|
|
"url": "http://example.org/foo/my-image.png" <3>
|
|
}
|
|
}
|
|
},
|
|
"dashboard.pdf" : {
|
|
"reporting" : {
|
|
"url": "http://example.org:5601/api/reporting/generate/dashboard/Error-Monitoring"
|
|
}
|
|
},
|
|
"data.yml" : {
|
|
"data" : {
|
|
"format" : "yaml" <4>
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
<1> The ID of the attachment, which is used as the file name in the email
|
|
attachment.
|
|
<2> The type of the attachment and its specific configuration.
|
|
<3> The URL from which to retrieve the attachment.
|
|
<4> Data attachments default to JSON if you don't specify the format.
|
|
|
|
.`http` attachment type attributes
|
|
[options="header"]
|
|
|=====
|
|
| Name | Description
|
|
| `content_type` | Sets the content type for the email attachment. By default,
|
|
the content type is extracted from the response sent by the
|
|
HTTP service. You can explicitly specify the content type to
|
|
ensure that the type is set correctly in the email in case
|
|
the response does not specify the content type or it's specified
|
|
incorrectly. Optional.
|
|
| `inline` | Configures as an attachment to sent with disposition `inline`. This
|
|
allows the use of embedded images in HTML bodies, which are displayed
|
|
in certain email clients. Optional. Defaults to `false`.
|
|
| `request` | Contains the HTTP request attributes. At a minimum, you must
|
|
specify the `url` attribute to configure the host and path to
|
|
the service endpoint. See <<webhook-action-attributes>> for
|
|
the full list of HTTP request attributes. Required.
|
|
|======
|
|
|
|
.`data` attachment type attributes
|
|
[options="header"]
|
|
|=====
|
|
| Name | Description
|
|
| `format` | Attaches the watch data, equivalent to specifying `attach_data`
|
|
in the watch configuration. Possible values are `json` or `yaml`.
|
|
Defaults to `json` if not specified.
|
|
|======
|
|
|
|
|
|
.`reporting` attachment type attributes
|
|
[options="header"]
|
|
|=====
|
|
| Name | Description
|
|
| `url` | The URL to trigger the dashboard creation
|
|
| `inline` | Configures as an attachment to sent with disposition `inline`. This
|
|
allows the use of embedded images in HTML bodies, which are displayed
|
|
in certain email clients. Optional. Defaults to `false`.
|
|
| `retries` | The reporting attachment type tries to poll regularly to receive the
|
|
created PDF. This configures the number of retries. Defaults to `40`.
|
|
The setting `xpack.notification.reporting.retries` can be configured
|
|
globally to change the default.
|
|
| `interval` | The time to wait between two polling tries. Defaults to `15s` (this
|
|
means, by default watcher tries to download a dashboard for 10 minutes,
|
|
forty times fifteen seconds). The setting `xpack.notification.reporting.interval`
|
|
can be configured globally to change the default.
|
|
| `request.auth` | Additional auth configuration for the request
|
|
| `request.proxy` | Additional proxy configuration for the request
|
|
|======
|
|
|
|
|
|
[[email-action-reports]]
|
|
===== Attaching Reports to an Email
|
|
|
|
You can use the `http` attachment type in an `email` action to automatically
|
|
generate a Kibana report and distribute it via email.
|
|
|
|
include::{xkb-repo-dir}/reporting/watch-example.asciidoc[]
|
|
|
|
include::{xkb-repo-dir}/reporting/report-intervals.asciidoc[]
|
|
|
|
//TODO: RE-ADD LINK:
|
|
//For more information, see
|
|
//{kibana-ref}/automating-report-generation.html[Automating Report Generation].
|
|
|
|
[[email-action-attributes]]
|
|
==== Email Action Attributes
|
|
|
|
[cols=",^,,", options="header"]
|
|
|======
|
|
| Name |Required | Default | Description
|
|
|
|
| `account` | no | the default account | The <<configuring-email, email account>> to use to send the email.
|
|
|
|
| `from` | no | - | The email <<email-address,address>> from which the email
|
|
will be sent. The `from` field can contain Mustache
|
|
<<templates, templates>> as long as it resolves to a
|
|
valid email address.
|
|
|
|
| `to` | yes | - | The email <<email-address,addresses>> of the `to` recipients.
|
|
The `to` field can contain Mustache <<templates, templates>>
|
|
as long as it resolves to a valid email address.
|
|
|
|
| `cc` | no | - | The email <<email-address,addresses>> of the `cc` recipients.
|
|
The `cc` field can contain Mustache <<templates, templates>>
|
|
as long as it resolves to a valid email address.
|
|
|
|
| `bcc` | no | - | The email <<email-address,addresses>> of the `bcc` recipients.
|
|
The `bcc` field can contain Mustache <<templates, templates>>
|
|
as long as it resolves to a valid email address.
|
|
|
|
| `reply_to` | no | - | The email <<email-address,addresses>> that will be set on the
|
|
message's `Reply-To` header. The `reply_to` field can contain
|
|
Mustache <<templates, templates>> as long as it resolves to
|
|
a valid email address.
|
|
|
|
| `subject` | no | - | The subject of the email. The subject can be static text or
|
|
contain Mustache <<templates, templates>>.
|
|
|
|
| `body` | no | - | The body of the email. When this field holds a string, it
|
|
will default to the text body of the email. Set as an object
|
|
to specify either the text or the html body or both (using
|
|
the fields below)
|
|
|
|
| `body.text` | yes | - | The plain text body of the email. The body can be static text
|
|
or contain Mustache <<templates, templates>>. The email `body`
|
|
must contain at least one `text` or `html` field.
|
|
|
|
| `body.html` | yes | - | The html body of the email. The body can be static text or
|
|
contain Mustache <<templates, templates>>. This body will be
|
|
sanitized to remove dangerous content such as scripts. This
|
|
behavior can be disabled by setting
|
|
`xpack.notification.email.html.sanitization.enabled: false` in
|
|
`elasticsearch.yaml`. The email `body` must contain at least
|
|
one `text` or `html` field.
|
|
|
|
| `priority` | no | - | The priority of this email. Valid values are: `lowest`, `low`,
|
|
`normal`, `high` and `highest`. The priority can contain a
|
|
Mustache <<templates, template>> as long as it resolves to
|
|
one of the valid values.
|
|
|
|
| `attachments` | no | - | Attaches the watch payload (`data` attachment) or a file
|
|
retrieved from an HTTP service (`http` attachment) to the
|
|
email. For more information, see
|
|
<<configuring-email-attachments, Configuring Email Attachments>>.
|
|
|
|
| `attach_data` | no | false | Indicates whether the watch execution data should be attached
|
|
to the email. You can specify a Boolean value or an object.
|
|
If `attach_data` is set to `true`, the data is attached as a
|
|
YAML file. This attribute is deprecated, use the `attachments`
|
|
attribute to add a `data` attachment to attach the watch payload.
|
|
|
|
| `attach_data.format` | no | yaml | When `attach_data` is specified as an object, this field
|
|
controls the format of the attached data. The supported formats
|
|
are `json` and `yaml`. This attribute is deprecated, use the
|
|
`attachments` attribute to add a `data` attachment to attach
|
|
the watch payload.
|
|
|======
|
|
|
|
[[email-address]]
|
|
Email Address::
|
|
An email address can contain two possible parts--the address itself and an
|
|
optional personal name as described in http://www.ietf.org/rfc/rfc822.txt[RFC 822].
|
|
The address can be represented either as a string of the form `user@host.domain`
|
|
or `Personal Name <user@host.domain>`. You can also specify an email address as
|
|
an object that contains `name` and `address` fields.
|
|
|
|
[[address-list]]
|
|
Address List::
|
|
A list of addresses can be specified as a an
|
|
array: `[ 'Personal Name <user1@host.domain>', 'user2@host.domain' ]`.
|
|
|
|
[[configuring-email]]
|
|
==== Configuring Email Accounts
|
|
|
|
{watcher} can send email using any SMTP email service. Email
|
|
messages can contain basic HTML tags. You can control which groups of tags are
|
|
allowed by <<email-html-sanitization, Configuring HTML Sanitization Options>>.
|
|
|
|
You configure the accounts {watcher} can use to send email in the
|
|
`xpack.notification.email` namespace in `elasticsearch.yml`.
|
|
|
|
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.
|
|
|
|
IMPORTANT: Currently, neither Watcher nor Shield provide a mechanism to encrypt
|
|
settings in `elasticsearch.yml`. Because the email account credentials appear
|
|
in plain text, you should limit access to `elasticsearch.yml` to the user that
|
|
you use to run Elasticsearch.
|
|
|
|
[[email-profile]]
|
|
{watcher} provides three email profiles that control how MIME messages are
|
|
structured: `standard` (default), `gmail`, and `outlook`. These profiles
|
|
accommodate differences in how various email systems interpret the MIME
|
|
standard. If you are using Gmail or Outlook, we recommend using the
|
|
corresponding profile. Use the `standard` profile if you are using another
|
|
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>>
|
|
|
|
If you configure multiple email accounts, you must either configure a default
|
|
account or specify which account the email should be sent with in the
|
|
<<actions-email, `email`>> action.
|
|
|
|
[source,yaml]
|
|
--------------------------------------------------
|
|
xpack.notification.email:
|
|
default_account: team1
|
|
account:
|
|
team1:
|
|
...
|
|
team2:
|
|
...
|
|
--------------------------------------------------
|
|
|
|
[float]
|
|
[[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]
|
|
--------------------------------------------------
|
|
xpack.notification.email.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.
|
|
|
|
[float]
|
|
[[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]
|
|
--------------------------------------------------
|
|
xpack.notification.email.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.
|
|
|
|
[float]
|
|
[[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]
|
|
--------------------------------------------------
|
|
xpack.notification.email.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]. You might also need to verify
|
|
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/verify-email-addresses.html[your email address]
|
|
or https://docs.aws.amazon.com/ses/latest/DeveloperGuide/verify-domains.html[your whole domain]
|
|
at AWS.
|
|
|
|
[float]
|
|
[[exchange]]
|
|
===== Sending Email from Microsoft Exchange
|
|
|
|
Use the following email account settings to send email action from Microsoft
|
|
Exchange:
|
|
|
|
[source,yaml]
|
|
--------------------------------------------------
|
|
xpack.notification.email.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.
|
|
|
|
|
|
[float]
|
|
[[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
|
|
`xpack.notification.email.html.sanitization.allow` and
|
|
`xpack.notification.email.html.sanitization.disallow` settings in
|
|
`elasticsearch.yml`. You can specify individual HTML elements and
|
|
<<html-feature-groups, HTML feature groups>>. By default, {watcher} allows the following
|
|
features: `body`, `head`, `_tables`, `_links`, `_blocks`, `_formatting` and
|
|
`img:embedded`.
|
|
|
|
For example, the following settings allow the HTML to contain tables and block
|
|
elements, but disallow `<h4>`, `<h5>` and `<h6>` tags.
|
|
|
|
[source,yaml]
|
|
--------------------------------------------------
|
|
xpack.notification.email.html.sanitization:
|
|
allow: _tables, _blocks
|
|
disallow: h4, h5, h6
|
|
--------------------------------------------------
|
|
|
|
To disable sanitization entirely, add the following setting to
|
|
`elasticsearch.yml`:
|
|
|
|
[source,yaml]
|
|
--------------------------------------------------
|
|
xpack.notification.email.html.sanitization.enabled: false
|
|
--------------------------------------------------
|