neulab/tldr huggingface dataset:
ret = {}
# cassandra_cql.cql_query may raise a CommandExecutionError try: data = __salt__["cassandra_cql.cql_query"](query) if data: load = data[0].get("load") if load: ret = json.loads(load) except CommandExecutionError: log.critical("Could not get load from jids table.") raise except Exception as e: log.critical( """Unexpected error while getting load from jids: {0}""".format( str(e) ) ) raise
External Job Cache Support Salt's external-job-cache extends the master_job_cache. External Job Cache support requires the following functions in addition to what is required for Master Job Cache support:
get_jid Return a dictionary containing the information (load) returned by each minion when the specified job id was executed.
Sample:
{ "local": { "master_minion": { "fun_args": [], "jid": "20150330121011408195", "return": "2018.3.4", "retcode": 0, "success": true, "cmd": "_return", "_stamp": "2015-03-30T12:10:12.708663", "fun": "test.version", "id": "master_minion" } } }
get_fun Return a dictionary of minions that called a given Salt function as their last function call.
{ "local": { "minion1": "test.version", "minion3": "test.version", "minion2": "test.version" } }
get_jids Return a list of all job ids.
{ "local": [ "20150330121011408195", "20150330195922139916" ] }
get_minions Returns a list of minions
{ "local": [ "minion3", "minion2", "minion1", "master_minion" ] }
Please refer to one or more of the existing returners (i.e. mysql, cassandra_cql) if you need further clarification.
Event Support An event_return function must be added to the returner module to allow events to be logged from a master via the returner. A list of events are passed to the function by the master.
The following example was taken from the MySQL returner. In this example, each event is inserted into the salt_events table keyed on the event tag. The tag contains the jid and therefore is guaranteed to be unique.
def event_return(events): """ Return event to mysql server
Requires that configuration be enabled via 'event_return' option in master config. """ with _get_serv(events, commit=True) as cur: for event in events: tag = event.get("tag", "") data = event.get("data", "") sql = """INSERT INTO `salt_events` (`tag`, `data`, `master_id` ) VALUES (%s, %s, %s)""" cur.execute(sql, (tag, salt.utils.json.dumps(data), __opts__["id"]))
Testing the Returner The returner, prep_jid, save_load, get_load, and event_return functions can be tested by configuring the master_job_cache and Event Returners in the master config file and submitting a job to test.version each minion from the master.
Once you have successfully exercised the Master Job Cache functions, test the External Job Cache functions using the ret execution module.
salt-call ret.get_jids cassandra_cql --output=json salt-call ret.get_fun cassandra_cql test.version --output=json salt-call ret.get_minions cassandra_cql --output=json salt-call ret.get_jid cassandra_cql 20150330121011408195 --output=json
Event Returners For maximum visibility into the history of events across a Salt infrastructure, all events seen by a salt master may be logged to one or more returners.
To enable event logging, set the event_return configuration option in the master config to the returner(s) which should be designated as the handler for event returns.
NOTE: Not all returners support event returns. Verify a returner has an event_return() function before using.
NOTE: On larger installations, many hundreds of events may be generated on a busy master every second. Be certain to closely monitor the storage of a given returner as Salt can easily overwhelm an underpowered server with thousands of returns.
│postgres_local_cache │ Use a postgresql server for │ │                     │ the master job cache.       │ ├─────────────────────┼─────────────────────────────┤ │pushover_returner    │ Return salt data via        │ │                     │ pushover (‐                 │ │                     │ http://www.pushover.net)    │ ├─────────────────────┼─────────────────────────────┤ │rawfile_json         │ Take data from salt and     │ │                     │ "return" it into a raw file │ │                     │ containing the json, with   │ │                     │ one line per event.         │ ├─────────────────────┼─────────────────────────────┤ │redis_return         │ Return data to a redis      │ │                     │ server                      │ ├─────────────────────┼─────────────────────────────┤ │sentry_return        │ Salt returner that reports  │ │                     │ execution results back to   │ │                     │ sentry.                     │ ├─────────────────────┼─────────────────────────────┤ │slack_returner       │ Return salt data via slack  │ ├─────────────────────┼─────────────────────────────┤ │slack_webhook_return │ Return salt data via Slack  │ │                     │ using Incoming Webhooks     │ ├─────────────────────┼─────────────────────────────┤ │sms_return           │ Return data by SMS.         │ ├─────────────────────┼─────────────────────────────┤ │smtp_return          │ Return salt data via email  │ ├─────────────────────┼─────────────────────────────┤ │splunk               │ Send json response data to  │ │                     │ Splunk via the HTTP Event   │ │                     │ Collector Requires the      │ │                     │ following config values to  │ │                     │ be specified in config or   │ │                     │ pillar:                     │ ├─────────────────────┼─────────────────────────────┤ │sqlite3_return       │ Insert minion return data   │ │                     │ into a sqlite3 database     │ ├─────────────────────┼─────────────────────────────┤ │syslog_return        │ Return data to the host     │ │                     │ operating system's syslog   │ │                     │ facility                    │ ├─────────────────────┼─────────────────────────────┤ │telegram_return      │ Return salt data via        │ │                     │ Telegram.                   │ ├─────────────────────┼─────────────────────────────┤ │xmpp_return          │ Return salt data via xmpp   │ ├─────────────────────┼─────────────────────────────┤ │zabbix_return        │ Return salt data to Zabbix  │ └─────────────────────┴─────────────────────────────┘
salt.returners.appoptics_return Salt returner to return highstate stats to AppOptics Metrics
To enable this returner the minion will need the AppOptics Metrics client importable on the Python path and the following values configured in the minion or master config.
The AppOptics python client can be found at:
https://github.com/appoptics/python-appoptics-metrics
appoptics.api_token: abc12345def
An example configuration that returns the total number of successes and failures for your salt highstate runs (the default) would look like this:
return: appoptics appoptics.api_token: <token string here>
The returner publishes the following metrics to AppOptics:
• saltstack.failed
• saltstack.passed
• saltstack.retcode
• saltstack.runtime
• saltstack.total
You can add a tags section to specify which tags should be attached to all metrics created by the returner.
appoptics.tags: host_hostname_alias: <the minion ID - matches @host> tier: <the tier/etc. of this node> cluster: <the cluster name, etc.>
If no tags are explicitly configured, then the tag key host_hostname_alias will be set, with the minion's id grain being the value.
In addition to the requested tags, for a highstate run each of these will be tagged with the key:value of state_type: highstate.
In order to return metrics for state.sls runs (distinct from highstates), you can specify a list of state names to the key appoptics.sls_states like so:
appoptics.sls_states: - role_salt_master.netapi - role_redis.config - role_smarty.dummy
This will report success and failure counts on runs of the role_salt_master.netapi, role_redis.config, and role_smarty.dummy states in addition to highstates.
This will report the same metrics as above, but for these runs the metrics will be tagged with state_type: sls and state_name set to the name of the state that was invoked, e.g. role_salt_master.netapi.
salt.returners.appoptics_return.returner(ret) Parse the return data and return metrics to AppOptics.
For each state that's provided in the configuration, return tagged metrics for the result of that state if it's present.
salt.returners.carbon_return Take data from salt and "return" it into a carbon receiver
Add the following configuration to the minion configuration file:
carbon.host: <server ip address> carbon.port: 2003
Errors when trying to convert data to numbers may be ignored by setting carbon.skip_on_error to True:
carbon.skip_on_error: True
By default, data will be sent to carbon using the plaintext protocol. To use the pickle protocol, set carbon.mode to pickle:
carbon.mode: pickle
You can also specify the pattern used for the metric base path (except for virt modules metrics): carbon.metric_base_pattern: carbon.[minion_id].[module].[function]
These tokens can used : [module]: salt module [function]: salt function [minion_id]: minion id
Default is : carbon.metric_base_pattern: [module].[function].[minion_id]
Carbon settings may also be configured as:
carbon: host: <server IP or hostname> port: <carbon port> skip_on_error: True mode: (pickle|text) metric_base_pattern: <pattern> | [module].[function].[minion_id]
Alternative configuration values can be used by prefacing the configuration.  Any values not found in the alternative configuration will be pulled from the default location:
alternative.carbon: host: <server IP or hostname> port: <carbon port> skip_on_error: True mode: (pickle|text)
To use the carbon returner, append '--return carbon' to the salt command.
salt '*' test.ping --return carbon
To use the alternative configuration, append '--return_config alternative' to the salt command.
New in version 2015.5.0.
salt '*' test.ping --return carbon --return_config alternative
To override individual configuration items, append --return_kwargs '{"key:": "value"}' to the salt command.
salt '*' test.ping --return carbon --return_kwargs '{"skip_on_error": False}'
salt.returners.carbon_return.event_return(events) Return event data to remote carbon server
Provide a list of events to be stored in carbon
salt.returners.carbon_return.prep_jid(nocache=False, passed_jid=None) Do any work necessary to prepare a JID, including sending a custom id
salt.returners.carbon_return.returner(ret) Return data to a remote carbon server using the text metric protocol
Each metric will look like:
[module].[function].[minion_id].[metric path [...]].[metric name]
salt.returners.cassandra_cql_return Return data to a cassandra server
maintainer Corin Kochenower<ckochenower@saltstack.com>
maturity new as of 2015.2
depends salt.modules.cassandra_cql
depends DataStax Python Driver for Apache Cassandra https://github.com/datastax/python-driver pip install cassandra-driver
platform all
configuration To enable this returner, the minion will need the DataStax Python Driver for Apache Cassandra ( https://github.com/datastax/python-driver ) installed and the following values configured in the minion or master config. The list of cluster IPs must include at least one cassandra node IP address. No assumption or default will be used for the cluster IPs.  The cluster IPs will be tried in the order listed. The port, username, and password values shown below will be the assumed defaults if you do not provide values.:
cassandra: cluster: - 192.168.50.11 - 192.168.50.12 - 192.168.50.13 port: 9042 username: salt password: salt
Use the following cassandra database schema:
CREATE KEYSPACE IF NOT EXISTS salt WITH replication = {'class': 'SimpleStrategy', 'replication_factor' : 1};
CREATE USER IF NOT EXISTS salt WITH PASSWORD 'salt' NOSUPERUSER;
GRANT ALL ON KEYSPACE salt TO salt;
USE salt;
CREATE TABLE IF NOT EXISTS salt.salt_returns ( jid text, minion_id text, fun text, alter_time timestamp, full_ret text, return text, success boolean, PRIMARY KEY (jid, minion_id, fun) ) WITH CLUSTERING ORDER BY (minion_id ASC, fun ASC); CREATE INDEX IF NOT EXISTS salt_returns_minion_id ON salt.salt_returns (minion_id); CREATE INDEX IF NOT EXISTS salt_returns_fun ON salt.salt_returns (fun);
CREATE TABLE IF NOT EXISTS salt.jids ( jid text PRIMARY KEY, load text );
CREATE TABLE IF NOT EXISTS salt.minions ( minion_id text PRIMARY KEY, last_fun text ); CREATE INDEX IF NOT EXISTS minions_last_fun ON salt.minions (last_fun);
CREATE TABLE IF NOT EXISTS salt.salt_events ( id timeuuid, tag text, alter_time timestamp, data text, master_id text, PRIMARY KEY (id, tag) ) WITH CLUSTERING ORDER BY (tag ASC); CREATE INDEX tag ON salt.salt_events (tag);
Required python modules: cassandra-driver
To use the cassandra returner, append '--return cassandra_cql' to the salt command. ex:
salt '*' test.ping --return_cql cassandra
Note: if your Cassandra instance has not been tuned much you may benefit from altering some timeouts in cassandra.yaml like so:
# How long the coordinator should wait for read operations to complete read_request_timeout_in_ms: 5000 # How long the coordinator should wait for seq or index scans to complete range_request_timeout_in_ms: 20000 # How long the coordinator should wait for writes to complete write_request_timeout_in_ms: 20000 # How long the coordinator should wait for counter writes to complete counter_write_request_timeout_in_ms: 10000 # How long a coordinator should continue to retry a CAS operation # that contends with other proposals for the same row cas_contention_timeout_in_ms: 5000 # How long the coordinator should wait for truncates to complete # (This can be much longer, because unless auto_snapshot is disabled # we need to flush first so we can snapshot before removing the data.) truncate_request_timeout_in_ms: 60000 # The default timeout for other, miscellaneous operations request_timeout_in_ms: 20000
As always, your mileage may vary and your Cassandra cluster may have different needs.  SaltStack has seen situations where these timeouts can resolve some stacktraces that appear to come from the Datastax Python driver.
salt.returners.cassandra_cql_return.event_return(events) Return event to one of potentially many clustered cassandra nodes
Requires that configuration be enabled via 'event_return' option in master config.
Cassandra does not support an auto-increment feature due to the highly inefficient nature of creating a monotonically increasing number across all nodes in a distributed database. Each event will be assigned a uuid by the connecting client.
salt.returners.cassandra_cql_return.get_fun(fun) Return a dict of the last function called for all minions
salt.returners.cassandra_cql_return.get_jid(jid) Return the information returned when the specified job id was executed
salt.returners.cassandra_cql_return.get_jids() Return a list of all job ids
salt.returners.cassandra_cql_return.get_load(jid) Return the load data that marks a specified jid
salt.returners.cassandra_cql_return.get_minions() Return a list of minions
salt.returners.cassandra_cql_return.prep_jid(nocache, passed_jid=None) Do any work necessary to prepare a JID, including sending a custom id
salt.returners.cassandra_cql_return.returner(ret) Return data to one of potentially many clustered cassandra nodes
salt.returners.cassandra_cql_return.save_load(jid, load, minions=None) Save the load to the specified jid id
salt.returners.cassandra_cql_return.save_minions(jid, minions, syndic_id=None) Included for API consistency
salt.returners.cassandra_return Return data to a Cassandra ColumnFamily
Here's an example Keyspace / ColumnFamily setup that works with this returner:
create keyspace salt; use salt; create column family returns with key_validation_class='UTF8Type' and comparator='UTF8Type' and default_validation_class='UTF8Type';
Required python modules: pycassa To use the cassandra returner, append '--return cassandra' to the salt command. ex: salt '*' test.ping --return cassandra
salt.returners.cassandra_return.prep_jid(nocache=False, passed_jid=None) Do any work necessary to prepare a JID, including sending a custom id
salt.returners.cassandra_return.returner(ret) Return data to a Cassandra ColumnFamily
salt.returners.couchbase_return Simple returner for Couchbase. Optional configuration settings are listed below, along with sane defaults.
couchbase.host:   'salt' couchbase.port:   8091 couchbase.bucket: 'salt' couchbase.ttl: 24 couchbase.password: 'password' couchbase.skip_verify_views: False
To use the couchbase returner, append '--return couchbase' to the salt command. ex:
salt '*' test.ping --return couchbase
salt '*' test.ping --return couchbase --return_config alternative
salt '*' test.ping --return couchbase --return_kwargs '{"bucket": "another-salt"}'
All of the return data will be stored in documents as follows:
JID load: load obj tgt_minions: list of minions targeted nocache: should we not cache the return data
JID/MINION_ID return: return_data full_ret: full load of job return
salt.returners.couchbase_return.get_jid(jid) Return the information returned when the specified job id was executed
salt.returners.couchbase_return.get_jids() Return a list of all job ids
salt.returners.couchbase_return.get_load(jid) Return the load data that marks a specified jid
salt.returners.couchbase_return.prep_jid(nocache=False, passed_jid=None) Return a job id and prepare the job id directory This is the function responsible for making sure jids don't collide (unless its passed a jid) So do what you have to do to make sure that stays the case
salt.returners.couchbase_return.returner(load) Return data to couchbase bucket
salt.returners.couchbase_return.save_load(jid, clear_load, minion=None) Save the load to the specified jid
salt.returners.couchbase_return.save_minions(jid, minions, syndic_id=None) Save/update the minion list for a given jid. The syndic_id argument is included for API compatibility only.
salt.returners.couchdb_return Simple returner for CouchDB. Optional configuration settings are listed below, along with sane defaults:
couchdb.db: 'salt' couchdb.url: 'http://salt:5984/'
alternative.couchdb.db: 'salt' alternative.couchdb.url: 'http://salt:5984/'
To use the couchdb returner, append --return couchdb to the salt command. Example:
salt '*' test.ping --return couchdb
To use the alternative configuration, append --return_config alternative to the salt command.
salt '*' test.ping --return couchdb --return_config alternative
salt '*' test.ping --return couchdb --return_kwargs '{"db": "another-salt"}'
On concurrent database access As this returner creates a couchdb document with the salt job id as document id and as only one document with a given id can exist in a given couchdb database, it is advised for most setups that every minion be configured to write to it own database (the value of couchdb.db may be suffixed with the minion id), otherwise multi-minion targeting can lead to losing output:
• the first returning minion is able to create a document in the database
• other minions fail with {'error': 'HTTP Error 409: Conflict'}
salt.returners.couchdb_return.ensure_views() This function makes sure that all the views that should exist in the design document do exist.
salt.returners.couchdb_return.get_fun(fun) Return a dict with key being minion and value being the job details of the last run of function 'fun'.
salt.returners.couchdb_return.get_jid(jid) Get the document with a given JID.
salt.returners.couchdb_return.get_jids() List all the jobs that we have..
salt.returners.couchdb_return.get_minions() Return a list of minion identifiers from a request of the view.
salt.returners.couchdb_return.get_valid_salt_views() Returns a dict object of views that should be part of the salt design document.
salt.returners.couchdb_return.prep_jid(nocache=False, passed_jid=None) Do any work necessary to prepare a JID, including sending a custom id
salt.returners.couchdb_return.returner(ret) Take in the return and shove it into the couchdb database.
salt.returners.couchdb_return.save_minions(jid, minions, syndic_id=None) Included for API consistency
salt.returners.couchdb_return.set_salt_view() Helper function that sets the salt design document. Uses get_valid_salt_views and some hardcoded values.
salt.returners.django_return A returner that will inform a Django system that returns are available using Django's signal system.
https://docs.djangoproject.com/en/dev/topics/signals/
It is up to the Django developer to register necessary handlers with the signals provided by this returner and process returns as necessary.
The easiest way to use signals is to import them from this returner directly and then use a decorator to register them.
An example Django module that registers a function called 'returner_callback' with this module's 'returner' function:
import salt.returners.django_return from django.dispatch import receiver
@receiver(salt.returners.django_return, sender=returner) def returner_callback(sender, ret): print('I received {0} from {1}'.format(ret, sender))
salt.returners.django_return.prep_jid(nocache=False, passed_jid=None) Do any work necessary to prepare a JID, including sending a custom ID
salt.returners.django_return.returner(ret) Signal a Django server that a return is available
salt.returners.django_return.save_load(jid, load, minions=None) Save the load to the specified jid
salt.returners.elasticsearch_return Return data to an elasticsearch server for indexing.
maintainer Jurnell Cockhren <jurnell.cockhren@sophicware.com>, Arnold Bechtoldt <mail@arnoldbechtoldt.com>
maturity New
depends elasticsearch-py
To enable this returner the elasticsearch python client must be installed on the desired minions (all or some subset).
Please see documentation of elasticsearch execution module for a valid connection configuration.
WARNING: The index that you wish to store documents will be created by Elasticsearch automatically if doesn't exist yet. It is highly recommended to create predefined index templates with appropriate mapping(s) that will be used by Elasticsearch upon index creation. Otherwise you will have problems as described in #20826.
To use the returner per salt call:
salt '*' test.ping --return elasticsearch
In order to have the returner apply to all minions:
ext_job_cache: elasticsearch
Minion configuration:
debug_returner_payload': False Output the payload being posted to the log file in debug mode
doc_type: 'default' Document type to use for normal return messages
functions_blacklist Optional list of functions that should not be returned to elasticsearch
index_date: False Use a dated index (e.g. <index>-2016.11.29)
master_event_index: 'salt-master-event-cache' Index to use when returning master events
master_event_doc_type: 'efault' Document type to use got master events
master_job_cache_index: 'salt-master-job-cache' Index to use for master job cache
master_job_cache_doc_type: 'default' Document type to use for master job cache
number_of_shards: 1 Number of shards to use for the indexes
number_of_replicas: 0 Number of replicas to use for the indexes
NOTE: The following options are valid for 'state.apply', 'state.sls' and 'state.highstate' functions only.
states_count: False Count the number of states which succeeded or failed and return it in top-level item called 'counts'.  States reporting None (i.e. changes would be made but it ran in test mode) are counted as successes.
states_order_output: False Prefix the state UID (e.g. file_|-yum_configured_|-/etc/yum.conf_|-managed) with a zero-padded version of the '__run_num__' value to allow for easier sorting. Also store the state function (i.e. file.managed) into a new key '_func'. Change the index to be '<index>-ordered' (e.g. salt-state_apply-ordered).
states_single_index: False Store results for state.apply, state.sls and state.highstate in the salt-state_apply index (or -ordered/-<date>) indexes if enabled
elasticsearch: hosts: - "10.10.10.10:9200" - "10.10.10.11:9200" - "10.10.10.12:9200" index_date: True number_of_shards: 5 number_of_replicas: 1 debug_returner_payload: True states_count: True states_order_output: True states_single_index: True functions_blacklist: - test.ping - saltutil.find_job
salt.returners.elasticsearch_return.event_return(events) Return events to Elasticsearch
Requires that the event_return configuration be set in master config.
salt.returners.elasticsearch_return.get_load(jid) Return the load data that marks a specified jid
New in version 2015.8.1.
salt.returners.elasticsearch_return.prep_jid(nocache=False, passed_jid=None) Do any work necessary to prepare a JID, including sending a custom id
salt.returners.elasticsearch_return.returner(ret) Process the return from Salt
salt.returners.elasticsearch_return.save_load(jid, load, minions=None) Save the load to the specified jid id
salt.returners.etcd_return Return data to an etcd server or cluster
• python-etcd
In order to return to an etcd server, a profile should be created in the master configuration file:
my_etcd_config: etcd.host: 127.0.0.1 etcd.port: 2379
It is technically possible to configure etcd without using a profile, but this is not considered to be a best practice, especially when multiple etcd servers or clusters are available.
etcd.host: 127.0.0.1 etcd.port: 2379
Additionally, two more options must be specified in the top-level configuration in order to use the etcd returner:
etcd.returner: my_etcd_config etcd.returner_root: /salt/return
The etcd.returner option specifies which configuration profile to use. The etcd.returner_root option specifies the path inside etcd to use as the root of the returner system.
Once the etcd options are configured, the returner may be used:
CLI Example: salt '*' test.ping --return etcd
A username and password can be set:
etcd.username: larry  # Optional; requires etcd.password to be set etcd.password: 123pass  # Optional; requires etcd.username to be set
You can also set a TTL (time to live) value for the returner:
etcd.ttl: 5
Authentication with username and password, and ttl, currently requires the master branch of python-etcd.
You may also specify different roles for read and write operations. First, create the profiles as specified above. Then add:
etcd.returner_read_profile: my_etcd_read etcd.returner_write_profile: my_etcd_write
salt.returners.etcd_return.clean_old_jobs() Included for API consistency
salt.returners.etcd_return.get_fun(fun) Return a dict of the last function called for all minions
salt.returners.etcd_return.get_jid(jid) Return the information returned when the specified job id was executed
salt.returners.etcd_return.get_jids() Return a list of all job ids
salt.returners.etcd_return.get_load(jid) Return the load data that marks a specified jid
salt.returners.etcd_return.get_minions() Return a list of minions
salt.returners.etcd_return.prep_jid(nocache=False, passed_jid=None) Do any work necessary to prepare a JID, including sending a custom id
salt.returners.etcd_return.returner(ret) Return data to an etcd server or cluster
salt.returners.etcd_return.save_load(jid, load, minions=None) Save the load to the specified jid
salt.returners.etcd_return.save_minions(jid, minions, syndic_id=None) Included for API consistency
salt.returners.highstate_return 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.
New in version 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.
salt '*' state.highstate --return highstate
To use the alternative configuration, append '--return_config config-name'
salt '*' state.highstate --return highstate --return_config simple
Here is an example of what the configuration might look like:
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.
salt.returners.highstate_return.returner(ret) Check highstate return information and possibly fire off an email or save a file.
salt.returners.influxdb_return Return data to an influxdb server.
To enable this returner the minion will need the python client for influxdb installed and the following values configured in the minion or master config, these are the defaults:
influxdb.db: 'salt' influxdb.user: 'salt' influxdb.password: 'salt' influxdb.host: 'localhost' influxdb.port: 8086
alternative.influxdb.db: 'salt' alternative.influxdb.user: 'salt' alternative.influxdb.password: 'salt' alternative.influxdb.host: 'localhost' alternative.influxdb.port: 6379
To use the influxdb returner, append '--return influxdb' to the salt command.
salt '*' test.ping --return influxdb
salt '*' test.ping --return influxdb --return_config alternative
salt '*' test.ping --return influxdb --return_kwargs '{"db": "another-salt"}'
salt.returners.influxdb_return.get_fun(fun) Return a dict of the last function called for all minions
salt.returners.influxdb_return.get_jid(jid) Return the information returned when the specified job id was executed
salt.returners.influxdb_return.get_jids() Return a list of all job ids
salt.returners.influxdb_return.get_load(jid) Return the load data that marks a specified jid
salt.returners.influxdb_return.get_minions() Return a list of minions
salt.returners.influxdb_return.prep_jid(nocache=False, passed_jid=None) Do any work necessary to prepare a JID, including sending a custom id
salt.returners.influxdb_return.returner(ret) Return data to a influxdb data store
salt.returners.influxdb_return.save_load(jid, load, minions=None) Save the load to the specified jid
salt.returners.influxdb_return.save_minions(jid, minions, syndic_id=None) Included for API consistency
salt.returners.kafka_return Return data to a Kafka topic
maintainer Justin Desilets (justin.desilets@gmail.com)
maturity 20181119
depends confluent-kafka
To enable this returner install confluent-kafka and enable the following settings in the minion config:
returner.kafka.bootstrap:
• "server1:9092"
• "server2:9092"
• "server3:9092"
returner.kafka.topic: 'topic'
To use the kafka returner, append --return kafka to the Salt command, eg; salt '*' test.ping --return kafka
salt.returners.kafka_return.returner(ret) Return information to a Kafka server
salt.returners.librato_return Salt returner to return highstate stats to Librato
To enable this returner the minion will need the Librato client importable on the Python path and the following values configured in the minion or master config.
The Librato python client can be found at: https://github.com/librato/python-librato
librato.email: example@librato.com librato.api_token: abc12345def
This return supports multi-dimension metrics for Librato. To enable support for more metrics, the tags JSON object can be modified to include other tags.
Adding EC2 Tags example: If ec2_tags:region were desired within the tags for multi-dimension. The tags could be modified to include the ec2 tags. Multiple dimensions are added simply by adding more tags to the submission.
pillar_data = __salt__['pillar.raw']() q.add(metric.name, value, tags={'Name': ret['id'],'Region': pillar_data['ec2_tags']['Name']})
salt.returners.librato_return.returner(ret) Parse the return data and return metrics to Librato.
salt.returners.local The local returner is used to test the returner interface, it just prints the return data to the console to verify that it is being passed properly
To use the local returner, append '--return local' to the salt command. ex:
salt '*' test.ping --return local
salt.returners.local.event_return(event) Print event return data to the terminal to verify functionality
salt.returners.local.returner(ret) Print the return data to the terminal to verify functionality
salt.returners.local_cache Return data to local job cache
salt.returners.local_cache.clean_old_jobs() Clean out the old jobs from the job cache
salt.returners.local_cache.get_endtime(jid) Retrieve the stored endtime for a given job
Returns False if no endtime is present
salt.returners.local_cache.get_jid(jid) Return the information returned when the specified job id was executed
salt.returners.local_cache.get_jids() Return a dict mapping all job ids to job information
salt.returners.local_cache.get_jids_filter(count, filter_find_job=True) Return a list of all jobs information filtered by the given criteria.  :param int count: show not more than the count of most recent jobs :param bool filter_find_jobs: filter out 'saltutil.find_job' jobs
salt.returners.local_cache.get_load(jid) Return the load data that marks a specified jid
salt.returners.local_cache.load_reg() Load the register from msgpack files
salt.returners.local_cache.prep_jid(nocache=False, passed_jid=None, recurse_count=0) Return a job id and prepare the job id directory.
This is the function responsible for making sure jids don't collide (unless it is passed a jid).  So do what you have to do to make sure that stays the case
salt.returners.local_cache.returner(load) Return data to the local job cache
salt.returners.local_cache.save_load(jid, clear_load, minions=None, recurse_count=0) Save the load to the specified jid
minions argument is to provide a pre-computed list of matched minions for the job, for cases when this function can't compute that list itself (such as for salt-ssh)
salt.returners.local_cache.save_minions(jid, minions, syndic_id=None) Save/update the serialized list of minions for a given job
salt.returners.local_cache.save_reg(data) Save the register to msgpack files
salt.returners.local_cache.update_endtime(jid, time) Update (or store) the end time for a given job
Endtime is stored as a plain text string
salt.returners.mattermost_returner Return salt data via mattermost
The following fields can be set in the minion conf file:
mattermost.hook (required) mattermost.username (optional) mattermost.channel (optional)
mattermost.channel mattermost.hook mattermost.username
mattermost settings may also be configured as:
mattermost: channel: RoomName hook: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx username: user
To use the mattermost returner, append '--return mattermost' to the salt command.
salt '*' test.ping --return mattermost
To override individual configuration items, append --return_kwargs '{'key:': 'value'}' to the salt command.
salt '*' test.ping --return mattermost --return_kwargs '{'channel': '#random'}'
salt.returners.mattermost_returner.event_return(events) Send the events to a mattermost room.
Parameters events -- List of events
Returns Boolean if messages were sent successfully.
salt.returners.mattermost_returner.post_message(channel, message, username, api_url, hook) Send a message to a mattermost room.
• channel -- The room name.
• message -- The message to send to the mattermost room.
• username -- Specify who the message is from.
• hook -- The mattermost hook, if not specified in the configuration.
Returns Boolean if message was sent successfully.
salt.returners.mattermost_returner.returner(ret) Send an mattermost message with the data
salt.returners.memcache_return Return data to a memcache server
To enable this returner the minion will need the python client for memcache installed and the following values configured in the minion or master config, these are the defaults.
memcache.host: 'localhost' memcache.port: '11211'
Alternative configuration values can be used by prefacing the configuration.  Any values not found in the alternative configuration will be pulled from the default location.
alternative.memcache.host: 'localhost' alternative.memcache.port: '11211'
python2-memcache uses 'localhost' and '11211' as syntax on connection.
To use the memcache returner, append '--return memcache' to the salt command.
salt '*' test.ping --return memcache
salt '*' test.ping --return memcache --return_config alternative
salt '*' test.ping --return memcache --return_kwargs '{"host": "hostname.domain.com"}'
salt.returners.memcache_return.get_fun(fun) Return a dict of the last function called for all minions
salt.returners.memcache_return.get_jid(jid) Return the information returned when the specified job id was executed
salt.returners.memcache_return.get_jids() Return a list of all job ids
salt.returners.memcache_return.get_load(jid) Return the load data that marks a specified jid
salt.returners.memcache_return.get_minions() Return a list of minions
salt.returners.memcache_return.prep_jid(nocache=False, passed_jid=None) Do any work necessary to prepare a JID, including sending a custom id
salt.returners.memcache_return.returner(ret) Return data to a memcache data store
salt.returners.memcache_return.save_load(jid, load, minions=None) Save the load to the specified jid
salt.returners.memcache_return.save_minions(jid, minions, syndic_id=None) Included for API consistency
salt.returners.mongo_future_return Return data to a mongodb server
Required python modules: pymongo
This returner will send data from the minions to a MongoDB server. MongoDB server can be configured by using host, port, db, user and password settings or by connection string URI (for pymongo > 2.3). To configure the settings for your MongoDB server, add the following lines to the minion config files:
mongo.db: <database name> mongo.host: <server ip address> mongo.user: <MongoDB username> mongo.password: <MongoDB user password> mongo.port: 27017
Or single URI:
mongo.uri: URI
where uri is in the format:
mongodb://[username:password@]host1[:port1][,host2[:port2],...[,hostN[:portN]]][/[database][?options]]
mongodb://db1.example.net:27017/mydatabase mongodb://db1.example.net:27017,db2.example.net:2500/?replicaSet=test mongodb://db1.example.net:27017,db2.example.net:2500/?replicaSet=test&connectTimeoutMS=300000
More information on URI format can be found in https://docs.mongodb.com/manual/reference/connection-string/
You can also ask for indexes creation on the most common used fields, which should greatly improve performance. Indexes are not created by default.
mongo.indexes: true
alternative.mongo.db: <database name> alternative.mongo.host: <server ip address> alternative.mongo.user: <MongoDB username> alternative.mongo.password: <MongoDB user password> alternative.mongo.port: 27017
alternative.mongo.uri: URI
This mongo returner is being developed to replace the default mongodb returner in the future and should not be considered API stable yet.
To use the mongo returner, append '--return mongo' to the salt command.
salt '*' test.ping --return mongo
salt '*' test.ping --return mongo --return_config alternative
salt '*' test.ping --return mongo --return_kwargs '{"db": "another-salt"}'
salt.returners.mongo_future_return.event_return(events) Return events to Mongodb server
salt.returners.mongo_future_return.get_fun(fun) Return the most recent jobs that have executed the named function
salt.returners.mongo_future_return.get_jid(jid) Return the return information associated with a jid
salt.returners.mongo_future_return.get_jids() Return a list of job ids
salt.returners.mongo_future_return.get_load(jid) Return the load associated with a given job id
salt.returners.mongo_future_return.get_minions() Return a list of minions
salt.returners.mongo_future_return.prep_jid(nocache=False, passed_jid=None) Do any work necessary to prepare a JID, including sending a custom id
salt.returners.mongo_future_return.returner(ret) Return data to a mongodb server
salt.returners.mongo_future_return.save_load(jid, load, minions=None) Save the load for a given job id
salt.returners.mongo_future_return.save_minions(jid, minions, syndic_id=None) Included for API consistency
salt.returners.mongo_return Return data to a mongodb server
This returner will send data from the minions to a MongoDB server. To configure the settings for your MongoDB server, add the following lines to the minion config files.
salt '*' test.ping --return mongo_return
salt '*' test.ping --return mongo_return --return_config alternative
salt.returners.mongo_return.get_fun(fun) Return the most recent jobs that have executed the named function
salt.returners.mongo_return.get_jid(jid) Return the return information associated with a jid
salt.returners.mongo_return.prep_jid(nocache=False, passed_jid=None) Do any work necessary to prepare a JID, including sending a custom id
salt.returners.mongo_return.returner(ret) Return data to a mongodb server
salt.returners.mongo_return.save_minions(jid, minions, syndic_id=None) Included for API consistency
salt.returners.multi_returner Read/Write multiple returners
salt.returners.multi_returner.clean_old_jobs() Clean out the old jobs from all returners (if you have it)
salt.returners.multi_returner.get_jid(jid) Merge the return data from all returners
salt.returners.multi_returner.get_jids() Return all job data from all returners
salt.returners.multi_returner.get_load(jid) Merge the load data from all returners
salt.returners.multi_returner.prep_jid(nocache=False, passed_jid=None) Call both with prep_jid on all returners in multi_returner
TODO: finish this, what do do when you get different jids from 2 returners...  since our jids are time based, this make this problem hard, because they aren't unique, meaning that we have to make sure that no one else got the jid and if they did we spin to get a new one, which means "locking" the jid in 2 returners is non-trivial
salt.returners.multi_returner.returner(load) Write return to all returners in multi_returner
salt.returners.multi_returner.save_load(jid, clear_load, minions=None) Write load to all returners in multi_returner
salt.returners.multi_returner.save_minions(jid, minions, syndic_id=None) Included for API consistency
salt.returners.mysql Return data to a mysql server
maintainer Dave Boucha <dave@saltstack.com>, Seth House <‐ shouse@saltstack.com>
maturity mature
depends python-mysqldb
To enable this returner, the minion will need the python client for mysql installed and the following values configured in the minion or master config. These are the defaults:
SSL is optional. The defaults are set to None. If you do not want to use SSL, either exclude these options or set them to None.
mysql.ssl_ca: None mysql.ssl_cert: None mysql.ssl_key: None
Alternative configuration values can be used by prefacing the configuration with alternative.. Any values not found in the alternative configuration will be pulled from the default location. As stated above, SSL configuration is optional. The following ssl options are simply for illustration purposes:
alternative.mysql.host: 'salt' alternative.mysql.user: 'salt' alternative.mysql.pass: 'salt' alternative.mysql.db: 'salt' alternative.mysql.port: 3306 alternative.mysql.ssl_ca: '/etc/pki/mysql/certs/localhost.pem' alternative.mysql.ssl_cert: '/etc/pki/mysql/certs/localhost.crt' alternative.mysql.ssl_key: '/etc/pki/mysql/certs/localhost.key'
Should you wish the returner data to be cleaned out every so often, set keep_jobs to the number of hours for the jobs to live in the tables. Setting it to 0 will cause the data to stay in the tables. The default setting for keep_jobs is set to 24.
Should you wish to archive jobs in a different table for later processing, set archive_jobs to True.  Salt will create 3 archive tables
• jids_archive
• salt_returns_archive
• salt_events_archive
and move the contents of jids, salt_returns, and salt_events that are more than keep_jobs hours old to these tables.
Use the following mysql database schema:
CREATE DATABASE  `salt` DEFAULT CHARACTER SET utf8 DEFAULT COLLATE utf8_general_ci;
USE `salt`;
-- -- Table structure for table `jids` --
DROP TABLE IF EXISTS `jids`; CREATE TABLE `jids` ( `jid` varchar(255) NOT NULL, `load` mediumtext NOT NULL, UNIQUE KEY `jid` (`jid`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8;
-- -- Table structure for table `salt_returns` --
DROP TABLE IF EXISTS `salt_returns`; CREATE TABLE `salt_returns` ( `fun` varchar(50) NOT NULL, `jid` varchar(255) NOT NULL, `return` mediumtext NOT NULL, `id` varchar(255) NOT NULL, `success` varchar(10) NOT NULL, `full_ret` mediumtext NOT NULL, `alter_time` TIMESTAMP DEFAULT CURRENT_TIMESTAMP, KEY `id` (`id`), KEY `jid` (`jid`), KEY `fun` (`fun`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8;
-- -- Table structure for table `salt_events` --
DROP TABLE IF EXISTS `salt_events`; CREATE TABLE `salt_events` ( `id` BIGINT NOT NULL AUTO_INCREMENT, `tag` varchar(255) NOT NULL, `data` mediumtext NOT NULL, `alter_time` TIMESTAMP DEFAULT CURRENT_TIMESTAMP, `master_id` varchar(255) NOT NULL, PRIMARY KEY (`id`), KEY `tag` (`tag`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8;
Required python modules: MySQLdb
To use the mysql returner, append '--return mysql' to the salt command.
salt '*' test.ping --return mysql
salt '*' test.ping --return mysql --return_config alternative
salt '*' test.ping --return mysql --return_kwargs '{"db": "another-salt"}'
salt.returners.mysql.clean_old_jobs() Called in the master's event loop every loop_interval.  Archives and/or deletes the events and job details from the database. :return:
salt.returners.mysql.event_return(events) Return event to mysql server
salt.returners.mysql.get_fun(fun) Return a dict of the last function called for all minions
salt.returners.mysql.get_jid(jid) Return the information returned when the specified job id was executed
salt.returners.mysql.get_jids() Return a list of all job ids
salt.returners.mysql.get_jids_filter(count, filter_find_job=True) Return a list of all job ids :param int count: show not more than the count of most recent jobs :param bool filter_find_jobs: filter out 'saltutil.find_job' jobs
salt.returners.mysql.get_load(jid) Return the load data that marks a specified jid
salt.returners.mysql.get_minions() Return a list of minions
salt.returners.mysql.prep_jid(nocache=False, passed_jid=None) Do any work necessary to prepare a JID, including sending a custom id
salt.returners.mysql.returner(ret) Return data to a mysql server
salt.returners.mysql.save_load(jid, load, minions=None) Save the load to the specified jid id
salt.returners.mysql.save_minions(jid, minions, syndic_id=None) Included for API consistency
salt.returners.nagios_nrdp_return Return salt data to Nagios
nagios.url (required) nagios.token (required) nagios.service (optional) nagios.check_type (optional)
nagios.url nagios.token nagios.service
Nagios settings may also be configured as:
nagios: url: http://localhost/nrdp token: r4nd0mt0k3n service: service-check
alternative.nagios: url: http://localhost/nrdp token: r4nd0mt0k3n service: another-service-check
To use the Nagios returner, append '--return nagios' to the salt command. ex:
.. code-block:: bash
salt '*' test.ping --return nagios
To use the alternative configuration, append '--return_config alternative' to the salt command. ex:
salt '*' test.ping --return nagios --return_config alternative