""" Return the results of a highstate (or any other state function that returns data in a compatible format) via an HTML email or HTML file. .. versionadded:: 2017.7.0 Similar results can be achieved by using the smtp returner with a custom template, except an attempt at writing such a template for the complex data structure returned by highstate function had proven to be a challenge, not to mention that the smtp module doesn't support sending HTML mail at the moment. The main goal of this returner was to produce an easy to read email similar to the output of highstate outputter used by the CLI. This returner could be very useful during scheduled executions, but could also be useful for communicating the results of a manual execution. Returner configuration is controlled in a standard fashion either via highstate group or an alternatively named group. .. code-block:: bash salt '*' state.highstate --return highstate To use the alternative configuration, append '--return_config config-name' .. code-block:: bash salt '*' state.highstate --return highstate --return_config simple Here is an example of what the configuration might look like: .. code-block:: yaml simple.highstate: report_failures: True report_changes: True report_everything: False failure_function: pillar.items success_function: pillar.items report_format: html report_delivery: smtp smtp_success_subject: 'success minion {id} on host {host}' smtp_failure_subject: 'failure minion {id} on host {host}' smtp_server: smtp.example.com smtp_recipients: saltusers@example.com, devops@example.com smtp_sender: salt@example.com The *report_failures*, *report_changes*, and *report_everything* flags provide filtering of the results. If you want an email to be sent every time, then *report_everything* is your choice. If you want to be notified only when changes were successfully made use *report_changes*. And *report_failures* will generate an email if there were failures. The configuration allows you to run a salt module function in case of success (*success_function*) or failure (*failure_function*). Any salt function, including ones defined in the _module folder of your salt repo, could be used here and its output will be displayed under the 'extra' heading of the email. Supported values for *report_format* are html, json, and yaml. The latter two are typically used for debugging purposes, but could be used for applying a template at some later stage. The values for *report_delivery* are smtp or file. In case of file delivery the only other applicable option is *file_output*. In case of smtp delivery, smtp_* options demonstrated by the example above could be used to customize the email. As you might have noticed, the success and failure subjects contain {id} and {host} values. Any other grain name could be used. As opposed to using {{grains['id']}}, which will be rendered by the master and contain master's values at the time of pillar generation, these will contain minion values at the time of execution. """ import html import io import logging import smtplib from email.mime.text import MIMEText import salt.returners import salt.utils.files import salt.utils.json import salt.utils.stringutils import salt.utils.yaml log = logging.getLogger(__name__) __virtualname__ = "highstate" def __virtual__(): """ Return our name """ return __virtualname__ def _get_options(ret): """ Return options """ attrs = { "report_everything": "report_everything", "report_changes": "report_changes", "report_failures": "report_failures", "failure_function": "failure_function", "success_function": "success_function", "report_format": "report_format", "report_delivery": "report_delivery", "file_output": "file_output", "smtp_sender": "smtp_sender", "smtp_recipients": "smtp_recipients", "smtp_failure_subject": "smtp_failure_subject", "smtp_success_subject": "smtp_success_subject", "smtp_server": "smtp_server", } _options = salt.returners.get_returner_options( __virtualname__, ret, attrs, __salt__=__salt__, __opts__=__opts__ ) return _options # # Most email readers to not support