neulab/tldr huggingface dataset:
salt '*' test.ping --return nagios --return_kwargs '{"service": "service-name"}'
salt.returners.nagios_nrdp_return.returner(ret) Send a message to Nagios with the data
salt.returners.odbc Return data to an ODBC compliant server.  This driver was developed with Microsoft SQL Server in mind, but theoretically could be used to return data to any compliant ODBC database as long as there is a working ODBC driver for it on your minion platform.
R. Oldham (cr@saltstack.com)
depends unixodbc, pyodbc, freetds (for SQL Server)
To enable this returner the minion will need
On Linux: unixodbc (http://www.unixodbc.org) pyodbc (pip install pyodbc) The FreeTDS ODBC driver for SQL Server (http://www.freetds.org) or another compatible ODBC driver
On Windows: TBD
unixODBC and FreeTDS need to be configured via /etc/odbcinst.ini and /etc/odbc.ini.
/etc/odbcinst.ini:
[TDS] Description=TDS Driver=/usr/lib/x86_64-linux-gnu/odbc/libtdsodbc.so
(Note the above Driver line needs to point to the location of the FreeTDS shared library.  This example is for Ubuntu 14.04.)
/etc/odbc.ini:
[TS] Description = "Salt Returner" Driver=TDS Server = <your server ip or fqdn> Port = 1433 Database = salt Trace = No
Also you need the following values configured in the minion or master config.  Configure as you see fit:
returner.odbc.dsn: 'TS' returner.odbc.user: 'salt' returner.odbc.passwd: 'salt'
alternative.returner.odbc.dsn: 'TS' alternative.returner.odbc.user: 'salt' alternative.returner.odbc.passwd: 'salt'
Running the following commands against Microsoft SQL Server in the desired database as the appropriate user should create the database tables correctly.  Replace with equivalent SQL for other ODBC-compliant servers
-- -- Table structure for table 'jids' --
if OBJECT_ID('dbo.jids', 'U') is not null DROP TABLE dbo.jids
CREATE TABLE dbo.jids ( jid   varchar(255) PRIMARY KEY, load  varchar(MAX) NOT NULL );
-- -- Table structure for table 'salt_returns' -- IF OBJECT_ID('dbo.salt_returns', 'U') IS NOT NULL DROP TABLE dbo.salt_returns;
CREATE TABLE dbo.salt_returns ( added     datetime not null default (getdate()), fun       varchar(100) NOT NULL, jid       varchar(255) NOT NULL, retval    varchar(MAX) NOT NULL, id        varchar(255) NOT NULL, success   bit default(0) NOT NULL, full_ret  varchar(MAX) );
CREATE INDEX salt_returns_added on dbo.salt_returns(added); CREATE INDEX salt_returns_id on dbo.salt_returns(id); CREATE INDEX salt_returns_jid on dbo.salt_returns(jid); CREATE INDEX salt_returns_fun on dbo.salt_returns(fun);
To use this returner, append '--return odbc' to the salt command.
salt '*' status.diskusage --return odbc
.. versionadded:: 2015.5.0
salt '*' test.ping --return odbc --return_config alternative
salt '*' test.ping --return odbc --return_kwargs '{"dsn": "dsn-name"}'
salt.returners.odbc.get_fun(fun) Return a dict of the last function called for all minions
salt.returners.odbc.get_jid(jid) Return the information returned when the specified job id was executed
salt.returners.odbc.get_jids() Return a list of all job ids
salt.returners.odbc.get_load(jid) Return the load data that marks a specified jid
salt.returners.odbc.get_minions() Return a list of minions
salt.returners.odbc.prep_jid(nocache=False, passed_jid=None) Do any work necessary to prepare a JID, including sending a custom id
salt.returners.odbc.returner(ret) Return data to an odbc server
salt.returners.odbc.save_load(jid, load, minions=None) Save the load to the specified jid id
salt.returners.odbc.save_minions(jid, minions, syndic_id=None) Included for API consistency
salt.returners.pgjsonb Return data to a PostgreSQL server with json data stored in Pg's jsonb data type
maintainer Dave Boucha <dave@saltstack.com>, Seth House <‐ shouse@saltstack.com>, C. R. Oldham <cr@saltstack.com>
maturity Stable
depends python-psycopg2
NOTE: There are three PostgreSQL returners.  Any can function as an external master job cache. but each has different features.  SaltStack recommends returners.pgjsonb if you are working with a version of PostgreSQL that has the appropriate native binary JSON types. Otherwise, review returners.postgres and returners.postgres_local_cache to see which module best suits your particular needs.
To enable this returner, the minion will need the python client for PostgreSQL installed and the following values configured in the minion or master config. These are the defaults:
returner.pgjsonb.host: 'salt' returner.pgjsonb.user: 'salt' returner.pgjsonb.pass: 'salt' returner.pgjsonb.db: 'salt' returner.pgjsonb.port: 5432
returner.pgjsonb.sslmode: None returner.pgjsonb.sslcert: None returner.pgjsonb.sslkey: None returner.pgjsonb.sslrootcert: None returner.pgjsonb.sslcrl: None
New in version 2017.5.0.
alternative.pgjsonb.host: 'salt' alternative.pgjsonb.user: 'salt' alternative.pgjsonb.pass: 'salt' alternative.pgjsonb.db: 'salt' alternative.pgjsonb.port: 5432 alternative.pgjsonb.ssl_ca: '/etc/pki/mysql/certs/localhost.pem' alternative.pgjsonb.ssl_cert: '/etc/pki/mysql/certs/localhost.crt' alternative.pgjsonb.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 or leaving it unset will cause the data to stay in the tables.
Should you wish to archive jobs in a different table for later processing, set archive_jobs to True.  Salt will create 3 archive tables;
New in version 2019.2.0.
Use the following Pg database schema:
CREATE DATABASE  salt WITH ENCODING 'utf-8';
-- -- Table structure for table `jids` -- DROP TABLE IF EXISTS jids; CREATE TABLE jids ( jid varchar(255) NOT NULL primary key, load jsonb NOT NULL ); CREATE INDEX idx_jids_jsonb on jids USING gin (load) WITH (fastupdate=on);
DROP TABLE IF EXISTS salt_returns; CREATE TABLE salt_returns ( fun varchar(50) NOT NULL, jid varchar(255) NOT NULL, return jsonb NOT NULL, id varchar(255) NOT NULL, success varchar(10) NOT NULL, full_ret jsonb NOT NULL, alter_time TIMESTAMP WITH TIME ZONE DEFAULT NOW());
CREATE INDEX idx_salt_returns_id ON salt_returns (id); CREATE INDEX idx_salt_returns_jid ON salt_returns (jid); CREATE INDEX idx_salt_returns_fun ON salt_returns (fun); CREATE INDEX idx_salt_returns_return ON salt_returns USING gin (return) with (fastupdate=on); CREATE INDEX idx_salt_returns_full_ret ON salt_returns USING gin (full_ret) with (fastupdate=on);
DROP TABLE IF EXISTS salt_events; DROP SEQUENCE IF EXISTS seq_salt_events_id; CREATE SEQUENCE seq_salt_events_id; CREATE TABLE salt_events ( id BIGINT NOT NULL UNIQUE DEFAULT nextval('seq_salt_events_id'), tag varchar(255) NOT NULL, data jsonb NOT NULL, alter_time TIMESTAMP WITH TIME ZONE DEFAULT NOW(), master_id varchar(255) NOT NULL);
CREATE INDEX idx_salt_events_tag on salt_events (tag); CREATE INDEX idx_salt_events_data ON salt_events USING gin (data) with (fastupdate=on);
Required python modules: Psycopg2
To use this returner, append '--return pgjsonb' to the salt command.
salt '*' test.ping --return pgjsonb
salt '*' test.ping --return pgjsonb --return_config alternative
salt '*' test.ping --return pgjsonb --return_kwargs '{"db": "another-salt"}'
salt.returners.pgjsonb.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.pgjsonb.event_return(events) Return event to Pg server
salt.returners.pgjsonb.get_fun(fun) Return a dict of the last function called for all minions
salt.returners.pgjsonb.get_jid(jid) Return the information returned when the specified job id was executed
salt.returners.pgjsonb.get_jids() Return a list of all job ids
salt.returners.pgjsonb.get_load(jid) Return the load data that marks a specified jid
salt.returners.pgjsonb.get_minions() Return a list of minions
salt.returners.pgjsonb.prep_jid(nocache=False, passed_jid=None) Do any work necessary to prepare a JID, including sending a custom id
salt.returners.pgjsonb.returner(ret) Return data to a Pg server
salt.returners.pgjsonb.save_load(jid, load, minions=None) Save the load to the specified jid id
salt.returners.pgjsonb.save_minions(jid, minions, syndic_id=None) Included for API consistency
salt.returners.postgres Return data to a postgresql server
maintainer None
depends psycopg2
To enable this returner the minion will need the psycopg2 installed and the following values configured in the minion or master config:
returner.postgres.host: 'salt' returner.postgres.user: 'salt' returner.postgres.passwd: 'salt' returner.postgres.db: 'salt' returner.postgres.port: 5432
alternative.returner.postgres.host: 'salt' alternative.returner.postgres.user: 'salt' alternative.returner.postgres.passwd: 'salt' alternative.returner.postgres.db: 'salt' alternative.returner.postgres.port: 5432
Running the following commands as the postgres user should create the database correctly:
psql << EOF CREATE ROLE salt WITH PASSWORD 'salt'; CREATE DATABASE salt WITH OWNER salt; EOF
psql -h localhost -U salt << EOF -- -- Table structure for table 'jids' --
DROP TABLE IF EXISTS jids; CREATE TABLE jids ( jid   varchar(20) PRIMARY KEY, load  text NOT NULL );
-- -- 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    text NOT NULL, full_ret  text, id        varchar(255) NOT NULL, success   varchar(10) NOT NULL, alter_time   TIMESTAMP WITH TIME ZONE DEFAULT now() );
CREATE INDEX idx_salt_returns_id ON salt_returns (id); CREATE INDEX idx_salt_returns_jid ON salt_returns (jid); CREATE INDEX idx_salt_returns_fun ON salt_returns (fun); CREATE INDEX idx_salt_returns_updated ON salt_returns (alter_time);
DROP TABLE IF EXISTS salt_events; DROP SEQUENCE IF EXISTS seq_salt_events_id; CREATE SEQUENCE seq_salt_events_id; CREATE TABLE salt_events ( id BIGINT NOT NULL UNIQUE DEFAULT nextval('seq_salt_events_id'), tag varchar(255) NOT NULL, data text NOT NULL, alter_time TIMESTAMP WITH TIME ZONE DEFAULT NOW(), master_id varchar(255) NOT NULL );
CREATE INDEX idx_salt_events_tag on salt_events (tag);
Required python modules: psycopg2
To use the postgres returner, append '--return postgres' to the salt command.
salt '*' test.ping --return postgres
salt '*' test.ping --return postgres --return_config alternative
salt '*' test.ping --return postgres --return_kwargs '{"db": "another-salt"}'
salt.returners.postgres.event_return(events) Return event to Pg server
salt.returners.postgres.get_fun(fun) Return a dict of the last function called for all minions
salt.returners.postgres.get_jid(jid) Return the information returned when the specified job id was executed
salt.returners.postgres.get_jids() Return a list of all job ids
salt.returners.postgres.get_load(jid) Return the load data that marks a specified jid
salt.returners.postgres.get_minions() Return a list of minions
salt.returners.postgres.prep_jid(nocache=False, passed_jid=None) Do any work necessary to prepare a JID, including sending a custom id
salt.returners.postgres.returner(ret) Return data to a postgres server
salt.returners.postgres.save_load(jid, load, minions=None) Save the load to the specified jid id
salt.returners.postgres.save_minions(jid, minions, syndic_id=None) Included for API consistency
salt.returners.postgres_local_cache Use a postgresql server for the master job cache. This helps the job cache to cope with scale.
maintainer gjredelinghuys@gmail.com
To enable this returner the minion will need the psycopg2 installed and the following values configured in the master config:
master_job_cache: postgres_local_cache master_job_cache.postgres.host: 'salt' master_job_cache.postgres.user: 'salt' master_job_cache.postgres.passwd: 'salt' master_job_cache.postgres.db: 'salt' master_job_cache.postgres.port: 5432
Running the following command as the postgres user should create the database correctly:
In case the postgres database is a remote host, you'll need this command also:
ALTER ROLE salt WITH LOGIN;
and then:
DROP TABLE IF EXISTS jids; CREATE TABLE jids ( jid   varchar(20) PRIMARY KEY, started TIMESTAMP WITH TIME ZONE DEFAULT now(), tgt_type text NOT NULL, cmd text NOT NULL, tgt text NOT NULL, kwargs text NOT NULL, ret text NOT NULL, username text NOT NULL, arg text NOT NULL, fun text NOT NULL );
-- -- Table structure for table 'salt_returns' -- -- note that 'success' must not have NOT NULL constraint, since -- some functions don't provide it.
DROP TABLE IF EXISTS salt_returns; CREATE TABLE salt_returns ( added     TIMESTAMP WITH TIME ZONE DEFAULT now(), fun       text NOT NULL, jid       varchar(20) NOT NULL, return    text NOT NULL, id        text NOT NULL, success   boolean ); CREATE INDEX ON salt_returns (added); CREATE INDEX ON salt_returns (id); CREATE INDEX ON salt_returns (jid); CREATE INDEX ON salt_returns (fun);
DROP TABLE IF EXISTS salt_events; CREATE TABLE salt_events ( id SERIAL, tag text NOT NULL, data text NOT NULL, alter_time TIMESTAMP WITH TIME ZONE DEFAULT now(), master_id text NOT NULL ); CREATE INDEX ON salt_events (tag); CREATE INDEX ON salt_events (data); CREATE INDEX ON salt_events (id); CREATE INDEX ON salt_events (master_id); EOF
salt.returners.postgres_local_cache.clean_old_jobs() Clean out the old jobs from the job cache
salt.returners.postgres_local_cache.event_return(events) Return event to a postgres server
Require that configuration be enabled via 'event_return' option in master config.
salt.returners.postgres_local_cache.get_jid(jid) Return the information returned when the specified job id was executed
salt.returners.postgres_local_cache.get_jids() Return a list of all job ids For master job cache this also formats the output and returns a string
salt.returners.postgres_local_cache.get_load(jid) Return the load data that marks a specified jid
salt.returners.postgres_local_cache.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.postgres_local_cache.returner(load) Return data to a postgres server
salt.returners.postgres_local_cache.save_load(jid, clear_load, minions=None) Save the load to the specified jid id
salt.returners.postgres_local_cache.save_minions(jid, minions, syndic_id=None) Included for API consistency
salt.returners.pushover_returner Return salt data via pushover (http://www.pushover.net)
pushover.user (required) pushover.token (required) pushover.title (optional) pushover.device (optional) pushover.priority (optional) pushover.expire (optional) pushover.retry (optional) pushover.profile (optional)
NOTE: The user here is your user key, not the email address you use to login to pushover.net.
alternative.pushover.user alternative.pushover.token alternative.pushover.title alternative.pushover.device alternative.pushover.priority alternative.pushover.expire alternative.pushover.retry
PushOver settings may also be configured as:
pushover: user: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx title: Salt Returner device: phone priority: -1 expire: 3600 retry: 5
alternative.pushover: user: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx title: Salt Returner device: phone priority: 1 expire: 4800 retry: 2
pushover_profile: pushover.token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
pushover: user: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx profile: pushover_profile
alternative.pushover: user: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx profile: pushover_profile
To use the PushOver returner, append '--return pushover' to the salt command. ex:
salt '*' test.ping --return pushover
salt '*' test.ping --return pushover --return_config alternative
salt '*' test.ping --return pushover --return_kwargs '{"title": "Salt is awesome!"}'
salt.returners.pushover_returner.returner(ret) Send an PushOver message with the data
salt.returners.rawfile_json Take data from salt and "return" it into a raw file containing the json, with one line per event.
Add the following to the minion or master configuration file.
rawfile_json.filename: <path_to_output_file>
Default is /var/log/salt/events.
Common use is to log all events on the master. This can generate a lot of noise, so you may wish to configure batch processing and/or configure the event_return_whitelist or event_return_blacklist to restrict the events that are written.
salt.returners.rawfile_json.event_return(events) Write event data (return data and non-return data) to file on the master.
salt.returners.rawfile_json.returner(ret) Write the return data to a file on the minion.
salt.returners.redis_return Return data to a redis server
To enable this returner the minion will need the python client for redis installed and the following values configured in the minion or master config, these are the defaults:
redis.db: '0' redis.host: 'salt' redis.port: 6379
New in version 2018.3.1: Alternatively a UNIX socket can be specified by unix_socket_path:
redis.db: '0' redis.unix_socket_path: /var/run/redis/redis.sock
Cluster Mode Example:
redis.db: '0' redis.cluster_mode: true redis.cluster.skip_full_coverage_check: true redis.cluster.startup_nodes: - host: redis-member-1 port: 6379 - host: redis-member-2 port: 6379
alternative.redis.db: '0' alternative.redis.host: 'salt' alternative.redis.port: 6379
To use the redis returner, append '--return redis' to the salt command.
salt '*' test.ping --return redis
salt '*' test.ping --return redis --return_config alternative
salt '*' test.ping --return redis --return_kwargs '{"db": "another-salt"}'
Redis Cluster Mode Options:
cluster_mode: False Whether cluster_mode is enabled or not
cluster.startup_nodes: A list of host, port dictionaries pointing to cluster members. At least one is required but multiple nodes are better
redis.cluster.startup_nodes - host: redis-member-1 port: 6379 - host: redis-member-2 port: 6379
cluster.skip_full_coverage_check: False Some cluster providers restrict certain redis commands such as CONFIG for enhanced security.  Set this option to true to skip checks that required advanced privileges.
NOTE: Most cloud hosted redis clusters will require this to be set to True
salt.returners.redis_return.clean_old_jobs() Clean out minions's return data for old jobs.
Normally, hset 'ret:<jid>' are saved with a TTL, and will eventually get cleaned by redis.But for jobs with some very late minion return, the corresponding hset's TTL will be refreshed to a too late timestamp, we'll do manually cleaning here.
salt.returners.redis_return.get_fun(fun) Return a dict of the last function called for all minions
salt.returners.redis_return.get_jid(jid) Return the information returned when the specified job id was executed
salt.returners.redis_return.get_jids() Return a dict mapping all job ids to job information
salt.returners.redis_return.get_load(jid) Return the load data that marks a specified jid
salt.returners.redis_return.get_minions() Return a list of minions
salt.returners.redis_return.prep_jid(nocache=False, passed_jid=None) Do any work necessary to prepare a JID, including sending a custom id
salt.returners.redis_return.returner(ret) Return data to a redis data store
salt.returners.redis_return.save_load(jid, load, minions=None) Save the load to the specified jid
salt.returners.redis_return.save_minions(jid, minions, syndic_id=None) Included for API consistency
salt.returners.sentry_return Salt returner that reports execution results back to sentry. The returner will inspect the payload to identify errors and flag them as such.
Pillar needs something like:
raven: servers: - http://192.168.1.1 - https://sentry.example.com public_key: deadbeefdeadbeefdeadbeefdeadbeef secret_key: beefdeadbeefdeadbeefdeadbeefdead project: 1 tags: - os - master - saltversion - cpuarch
or using a dsn:
raven: dsn: https://aaaa:bbbb@app.getsentry.com/12345 tags: - os - master - saltversion - cpuarch
https://pypi.python.org/pypi/raven must be installed.
The pillar can be hidden on sentry return by setting hide_pillar: true.
The tags list (optional) specifies grains items that will be used as sentry tags, allowing tagging of events in the sentry ui.
To report only errors to sentry, set report_errors_only: true.
salt.returners.sentry_return.prep_jid(nocache=False, passed_jid=None) Do any work necessary to prepare a JID, including sending a custom id
salt.returners.sentry_return.returner(ret) Log outcome to sentry. The returner tries to identify errors and report them as such. All other messages will be reported at info level.  Failed states will be appended as separate list for convenience.
salt.returners.slack_returner Return salt data via slack
slack.channel (required) slack.api_key (required) slack.username (required) slack.as_user (required to see the profile picture of your bot) slack.profile (optional) slack.changes(optional, only show changes and failed states) slack.only_show_failed(optional, only show failed states) slack.yaml_format(optional, format the json in yaml format)
slack.channel slack.api_key slack.username slack.as_user
Slack settings may also be configured as:
slack: channel: RoomName api_key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx username: user as_user: true
alternative.slack: room_id: RoomName api_key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx from_name: user@email.com
slack_profile: slack.api_key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx slack.from_name: user@email.com
slack: profile: slack_profile channel: RoomName
alternative.slack: profile: slack_profile channel: RoomName
To use the Slack returner, append '--return slack' to the salt command.
salt '*' test.ping --return slack
salt '*' test.ping --return slack --return_config alternative
salt '*' test.ping --return slack --return_kwargs '{"channel": "#random"}'
salt.returners.slack_returner.returner(ret) Send an slack message with the data
salt.returners.slack_webhook_return Return salt data via Slack using Incoming Webhooks
codeauthor Carlos D. Álvaro <github@cdalvaro.io>
slack_webhook.webhook (required, the webhook id. Just the part after: 'https://hooks.slack.com/services/') slack_webhook.success_title (optional, short title for succeeded states. By default: '{id} | Succeeded') slack_webhook.failure_title (optional, short title for failed states. By default: '{id} | Failed') slack_webhook.author_icon (optional, a URL that with a small 16x16px image. Must be of type: GIF, JPEG, PNG, and BMP) slack_webhook.show_tasks (optional, show identifiers for changed and failed tasks. By default: False)
slack_webhook.webhook slack_webhook.success_title slack_webhook.failure_title slack_webhook.author_icon slack_webhook.show_tasks
slack_webhook: webhook: T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX success_title: '[{id}] | Success' failure_title: '[{id}] | Failure' author_icon: https://platform.slack-edge.com/img/default_application_icon.png show_tasks: true
alternative.slack_webhook: webhook: T00000000/C00000000/YYYYYYYYYYYYYYYYYYYYYYYY show_tasks: false
To use the Slack returner, append '--return slack_webhook' to the salt command.
salt '*' test.ping --return slack_webhook
salt '*' test.ping --return slack_webhook --return_config alternative
salt.returners.slack_webhook_return.event_return(events) Send event data to returner function :param events: The Salt event return :return: The result of the post
salt.returners.slack_webhook_return.returner(ret, **kwargs) Send a slack message with the data through a webhook :param ret: The Salt return :return: The result of the post
salt.returners.sms_return Return data by SMS.
maintainer Damian Myerscough
maturity new
depends twilio
To enable this returner the minion will need the python twilio library installed and the following values configured in the minion or master config:
twilio.sid: 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' twilio.token: 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' twilio.to: '+1415XXXXXXX' twilio.from: '+1650XXXXXXX'
To use the sms returner, append '--return sms' to the salt command.
salt '*' test.ping --return sms
salt.returners.sms_return.returner(ret) Return a response in an SMS message
salt.returners.smtp_return Return salt data via email
The following fields can be set in the minion conf file. Fields are optional unless noted otherwise.
• from (required) The name/address of the email sender.
to (required) The names/addresses of the email recipients; comma-delimited. For example: you@example.com,someoneelse@example.com.
• host (required) The SMTP server hostname or address.
• port The SMTP server port; defaults to 25.
username The username used to authenticate to the server. If specified a password is also required. It is recommended but not required to also use TLS with this option.
• password The password used to authenticate to the server.
• tls Whether to secure the connection using TLS; defaults to False
• subject The email subject line.
fields Which fields from the returned data to include in the subject line of the email; comma-delimited. For example: id,fun. Please note, the subject line is not encrypted.
gpgowner A user's ~/.gpg directory. This must contain a gpg public key matching the address the mail is sent to. If left unset, no encryption will be used. Requires python-gnupg to be installed.
• template The path to a file to be used as a template for the email body.
renderer A Salt renderer, or render-pipe, to use to render the email template. Default jinja.
Below is an example of the above settings in a Salt Minion configuration file:
smtp.from: me@example.net smtp.to: you@example.com smtp.host: localhost smtp.port: 1025
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. For example:
alternative.smtp.username: saltdev alternative.smtp.password: saltdev alternative.smtp.tls: True
To use the SMTP returner, append '--return smtp' to the salt command.
salt '*' test.ping --return smtp
salt '*' test.ping --return smtp --return_config alternative
salt '*' test.ping --return smtp --return_kwargs '{"to": "user@domain.com"}'
An easy way to test the SMTP returner is to use the development SMTP server built into Python. The command below will start a single-threaded SMTP server that prints any email it receives to the console.
python -m smtpd -n -c DebuggingServer localhost:1025
It is possible to send emails with selected Salt events by configuring event_return option for Salt Master. For example:
event_return: smtp
event_return_whitelist: - salt/key
smtp.from: me@example.net smtp.to: you@example.com smtp.host: localhost smtp.subject: 'Salt Master {{act}}ed key from Minion ID: {{id}}' smtp.template: /srv/salt/templates/email.j2
Also you need to create additional file /srv/salt/templates/email.j2 with email body template:
act: {{act}} id: {{id}} result: {{result}}
This configuration enables Salt Master to send an email when accepting or rejecting minions keys.
salt.returners.smtp_return.event_return(events) Return event data via SMTP
salt.returners.smtp_return.prep_jid(nocache=False, passed_jid=None) Do any work necessary to prepare a JID, including sending a custom id
salt.returners.smtp_return.returner(ret) Send an email with the data
salt.returners.splunk Send json response data to Splunk via the HTTP Event Collector Requires the following config values to be specified in config or pillar:
splunk_http_forwarder: token: <splunk_http_forwarder_token> indexer: <hostname/IP of Splunk indexer> sourcetype: <Destination sourcetype for data> index: <Destination index for data> verify_ssl: true
Run a test by using salt-call test.ping --return splunk
Written by Scott Pack (github.com/scottjpack)
class salt.returners.splunk.http_event_collector(token, http_event_server, host='', http_event_port='8088', http_event_server_ssl=True, max_bytes=100000, verify_ssl=True)
batchEvent(payload, eventtime='')
flushBatch()
sendEvent(payload, eventtime='')
salt.returners.splunk.returner(ret) Send a message to Splunk via the HTTP Event Collector
salt.returners.sqlite3 Insert minion return data into a sqlite3 database
maintainer Mickey Malone <mickey.malone@gmail.com>
depends None
platform All
Sqlite3 is a serverless database that lives in a single file.  In order to use this returner the database file must exist, have the appropriate schema defined, and be accessible to the user whom the minion process is running as. This returner requires the following values configured in the master or minion config:
sqlite3.database: /usr/lib/salt/salt.db sqlite3.timeout: 5.0
alternative.sqlite3.database: /usr/lib/salt/salt.db alternative.sqlite3.timeout: 5.0
Use the commands to create the sqlite3 database and tables:
sqlite3 /usr/lib/salt/salt.db << EOF -- -- Table structure for table 'jids' --
CREATE TABLE jids ( jid TEXT PRIMARY KEY, load TEXT NOT NULL );
CREATE TABLE salt_returns ( fun TEXT KEY, jid TEXT KEY, id TEXT KEY, fun_args TEXT, date TEXT NOT NULL, full_ret TEXT NOT NULL, success TEXT NOT NULL ); EOF
To use the sqlite returner, append '--return sqlite3' to the salt command.
salt '*' test.ping --return sqlite3
salt '*' test.ping --return sqlite3 --return_config alternative
salt '*' test.ping --return sqlite3 --return_kwargs '{"db": "/var/lib/salt/another-salt.db"}'
salt.returners.sqlite3_return.get_fun(fun) Return a dict of the last function called for all minions
salt.returners.sqlite3_return.get_jid(jid) Return the information returned from a specified jid
salt.returners.sqlite3_return.get_jids() Return a list of all job ids
salt.returners.sqlite3_return.get_load(jid) Return the load from a specified jid
salt.returners.sqlite3_return.get_minions() Return a list of minions
salt.returners.sqlite3_return.prep_jid(nocache=False, passed_jid=None) Do any work necessary to prepare a JID, including sending a custom id
salt.returners.sqlite3_return.returner(ret) Insert minion return data into the sqlite3 database
salt.returners.sqlite3_return.save_load(jid, load, minions=None) Save the load to the specified jid
salt.returners.sqlite3_return.save_minions(jid, minions, syndic_id=None) Included for API consistency
salt.returners.syslog_return Return data to the host operating system's syslog facility
To use the syslog returner, append '--return syslog' to the salt command.
salt '*' test.ping --return syslog
syslog.level (optional, Default: LOG_INFO) syslog.facility (optional, Default: LOG_USER) syslog.tag (optional, Default: salt-minion) syslog.options (list, optional, Default: [])
Available levels, facilities, and options can be found in the syslog docs for your python version.
NOTE: The default tag comes from sys.argv[0] which is usually "salt-minion" but could be different based on the specific environment.
syslog.level: 'LOG_ERR' syslog.facility: 'LOG_DAEMON' syslog.tag: 'mysalt' syslog.options: - LOG_PID
Of course you can also nest the options:
syslog: level: 'LOG_ERR' facility: 'LOG_DAEMON' tag: 'mysalt' options: - LOG_PID
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.syslog.level: 'LOG_WARN' alternative.syslog.facility: 'LOG_NEWS'
salt '*' test.ping --return syslog --return_config alternative
salt '*' test.ping --return syslog --return_kwargs '{"level": "LOG_DEBUG"}'
NOTE: Syslog server implementations may have limits on the maximum record size received by the client. This may lead to job return data being truncated in the syslog server's logs. For example, for rsyslog on RHEL-based systems, the default maximum record size is approximately 2KB (which return data can easily exceed). This is configurable in rsyslog.conf via the $MaxMessageSize config parameter. Please consult your syslog implmentation's documentation to determine how to adjust this limit.
salt.returners.syslog_return.prep_jid(nocache=False, passed_jid=None) Do any work necessary to prepare a JID, including sending a custom id
salt.returners.syslog_return.returner(ret) Return data to the local syslog
salt.returners.telegram_return Return salt data via Telegram.
telegram.chat_id (required) telegram.token (required)
Telegram settings may also be configured as:
telegram: chat_id: 000000000 token: 000000000:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
To use the Telegram return, append '--return telegram' to the salt command.
salt '*' test.ping --return telegram
salt.returners.telegram_return.returner(ret) Send a Telegram message with the data.
Parameters ret -- The data to be sent.
salt.returners.xmpp_return Return salt data via xmpp
depends sleekxmpp >= 1.3.1
xmpp.jid (required) xmpp.password (required) xmpp.recipient (required) xmpp.profile (optional)
xmpp.jid xmpp.password xmpp.recipient xmpp.profile
XMPP settings may also be configured as:
xmpp: jid: user@xmpp.domain.com/resource password: password recipient: user@xmpp.example.com
alternative.xmpp: jid: user@xmpp.domain.com/resource password: password recipient: someone@xmpp.example.com
xmpp_profile: xmpp.jid: user@xmpp.domain.com/resource xmpp.password: password
xmpp: profile: xmpp_profile recipient: user@xmpp.example.com
alternative.xmpp: profile: xmpp_profile recipient: someone-else@xmpp.example.com
To use the XMPP returner, append '--return xmpp' to the salt command.
salt '*' test.ping --return xmpp
salt '*' test.ping --return xmpp --return_config alternative
salt '*' test.ping --return xmpp --return_kwargs '{"recipient": "someone-else@xmpp.example.com"}'
class salt.returners.xmpp_return.SendMsgBot(jid, password, recipient, msg)
start(event)
salt.returners.xmpp_return.returner(ret) Send an xmpp message with the data
salt.returners.zabbix_return Return salt data to Zabbix
The following Type: "Zabbix trapper" with "Type of information" Text items are required:
Key: salt.trap.info Key: salt.trap.warning Key: salt.trap.high
To use the Zabbix returner, append '--return zabbix' to the salt command. ex:
salt '*' test.ping --return zabbix
salt.returners.zabbix_return.returner(ret)
salt.returners.zabbix_return.save_load(jid, load, minions=None) Included for API consistency
salt.returners.zabbix_return.zabbix_send(key, output)
salt.returners.zabbix_return.zbx()
Renderers The Salt state system operates by gathering information from common data types such as lists, dictionaries, and strings that would be familiar to any developer.
Salt Renderers translate input from the format in which it is written into Python data structures.
The default renderer is set in the master/minion configuration file using the renderer config option, which defaults to jinja|yaml.
Two Kinds of Renderers Renderers fall into one of two categories, based on what they output: text or data. The one exception to this would be the pure python renderer, which can be used in either capacity.
Text Renderers IMPORTANT: Jinja supports a secure, sandboxed template execution environment that Salt takes advantage of. Other text Renderers do not support this functionality, so Salt highly recommends usage of jinja / jinja|yaml.
A text renderer returns text. These include templating engines such as jinja, mako, and genshi, as well as the gpg renderer. The following are all text renderers:
• aws_kms
• cheetah
• genshi
• gpg
• jinja
• mako
• nacl
• pass
• py
• wempy
Data Renderers A data renderer returns a Python data structure (typically a dictionary). The following are all data renderers:
• dson
• hjson
• json5
• json
• pydsl
• pyobjects
• stateconf
• yamlex
• yaml
Overriding the Default Renderer It can sometimes be beneficial to write an SLS file using a renderer other than the default one. This can be done by using a "shebang"-like syntax on the first line of the SLS file:
Here is an example of using the pure python renderer to install a package:
#!py
def run(): """ Install version 1.5-1.el7 of package "python-foo" """ return { "include": ["python"], "python-foo": {"pkg.installed": [{"version": "1.5-1.el7"}]}, }
This would be equivalent to the following:
include: - python
python-foo: pkg.installed: - version: '1.5-1.el7'
Composing Renderers (a.k.a. The Render Pipeline ) A render pipeline can be composed from other renderers by connecting them in a series of "pipes" (i.e. |). The renderers will be evaluated from left to right, with each renderer receiving the result of the previous renderer's execution.
Take for example the default renderer (jinja|yaml). The file is evaluated first a jinja template, and the result of that template is evaluated as a YAML document.
Other render pipeline combinations include:
yaml   Just YAML, no templating.
mako|yaml This passes the input to the mako renderer, with its output fed into the yaml renderer.
jinja|mako|yaml This one allows you to use both jinja and mako templating syntax in the input and then parse the final rendered output as YAML.
The following is a contrived example SLS file using the jinja|mako|yaml render pipeline:
#!jinja|mako|yaml
An_Example: cmd.run: - name: | echo "Using Salt ${grains['saltversion']}" \ "from path {{grains['saltpath']}}." - cwd: /
<%doc> ${...} is Mako's notation, and so is this comment. </%doc> {#     Similarly, {{...}} is Jinja's notation, and so is this comment. #}
IMPORTANT: Keep in mind that not all renderers can be used alone or with any other renderers. For example, text renderers shouldn't be used alone as their outputs are just strings, which still need to be parsed by another renderer to turn them into Python data structures.
For example, it would not make sense to use yaml|jinja because the output of the yaml renderer is a Python data structure, and the jinja renderer only accepts text as input.
Therefore, when combining renderers, you should know what each renderer accepts as input and what it returns as output. One way of thinking about it is that you can chain together multiple text renderers, but the pipeline must end in a data renderer. Similarly, since the text renderers in Salt don't accept data structures as input, a text renderer should usually not come after a data renderer. It's technically possible to write a renderer that takes a data structure as input and returns a string, but no such renderer is distributed with Salt.
Writing Renderers A custom renderer must be a Python module which implements a render function. This function must implement three positional arguments:
1. data - Can be called whatever you like. This is the input to be rendered.
2. saltenv
3. sls
The first is the important one, and the 2nd and 3rd must be included since Salt needs to pass this info to each render, even though it is only used by template renderers.
Renderers should be written so that the data argument can accept either strings or file-like objects as input. For example:
import mycoolmodule from salt.ext import six
def render(data, saltenv="base", sls="", **kwargs): if not isinstance(data, six.string_types): # Read from file-like object data = data.read()
return mycoolmodule.do_something(data)
Custom renderers should be placed within salt://_renderers/, so that they can be synced to minions. They are synced when any of the following are run:
• saltutil.sync_renderers
Any custom renderers which have been synced to a minion, that are named the same as one of Salt's default set of renderers, will take the place of the default renderer with the same name.
NOTE: Renderers can also be synced from salt://_renderers/ to the Master using either the saltutil.sync_renderers or saltutil.sync_all runner function.
Examples The best place to find examples of renderers is in the Salt source code.
Documentation for renderers included with Salt can be found here:
https://github.com/saltstack/salt/blob/master/salt/renderers
Here is a simple YAML renderer example:
import salt.utils.yaml from salt.utils.yamlloader import SaltYamlSafeLoader from salt.ext import six
def render(yaml_data, saltenv="", sls="", **kws): if not isinstance(yaml_data, six.string_types): yaml_data = yaml_data.read() data = salt.utils.yaml.safe_load(yaml_data) return data if data else {}
Full List of Renderers renderer modules IMPORTANT: Jinja supports a secure, sandboxed template execution environment that Salt takes advantage of. Other text renderers do not support this functionality, so Salt highly recommends usage of jinja / jinja|yaml.
┌──────────┬─────────────────────────────┐ │aws_kms   │                             │ └──────────┴─────────────────────────────┘
│cheetah   │ Cheetah Renderer for Salt   │ ├──────────┼─────────────────────────────┤ │dson      │ DSON Renderer for Salt      │ ├──────────┼─────────────────────────────┤ │genshi    │ Genshi Renderer for Salt    │ ├──────────┼─────────────────────────────┤ │gpg       │ Renderer that will decrypt  │ │          │ GPG ciphers                 │ ├──────────┼─────────────────────────────┤ │hjson     │ hjson renderer for Salt     │ ├──────────┼─────────────────────────────┤ │jinja     │ Jinja loading utils to      │ │          │ enable a more powerful      │ │          │ backend for jinja templates │ ├──────────┼─────────────────────────────┤ │json      │ JSON Renderer for Salt      │ ├──────────┼─────────────────────────────┤ │json5     │ JSON5 Renderer for Salt     │ ├──────────┼─────────────────────────────┤ │mako      │ Mako Renderer for Salt      │ ├──────────┼─────────────────────────────┤ │msgpack   │                             │ ├──────────┼─────────────────────────────┤ │nacl      │ Renderer that will decrypt  │ │          │ NACL ciphers                │ ├──────────┼─────────────────────────────┤ │pass      │ Pass Renderer for Salt      │ ├──────────┼─────────────────────────────┤ │py        │ Pure python state renderer  │ ├──────────┼─────────────────────────────┤ │pydsl     │ A Python-based DSL          │ ├──────────┼─────────────────────────────┤ │pyobjects │ Python renderer that        │ │          │ includes a Pythonic Object  │ │          │ based interface             │ ├──────────┼─────────────────────────────┤ │stateconf │ A flexible renderer that    │ │          │ takes a templating engine   │ │          │ and a data format           │ ├──────────┼─────────────────────────────┤ │tomlmod   │                             │ ├──────────┼─────────────────────────────┤ │wempy     │                             │ ├──────────┼─────────────────────────────┤ │yaml      │ YAML Renderer for Salt      │ ├──────────┼─────────────────────────────┤ │yamlex    │                             │ └──────────┴─────────────────────────────┘
salt.renderers.aws_kms Renderer that will decrypt ciphers encrypted using AWS KMS Envelope Encryption.
Any key in the data to be rendered can be a urlsafe_b64encoded string, and this renderer will attempt to decrypt it before passing it off to Salt. This allows you to safely store secrets in source control, in such a way that only your Salt master can decrypt them and distribute them only to the minions that need them.
The typical use-case would be to use ciphers in your pillar data, and keep the encrypted data key on your master. This way developers with appropriate AWS IAM privileges can add new secrets quickly and easily.
This renderer requires the boto3 Python library.
Setup First, set up your AWS client. For complete instructions on configuration the AWS client, please read the boto3 configuration documentation. By default, this renderer will use the default AWS profile. You can override the profile name in salt configuration.  For example, if you have a profile in your aws client configuration named "salt", you can add the following salt configuration:
aws_kms: profile_name: salt
The rest of these instructions assume that you will use the default profile for key generation and setup. If not, export AWS_PROFILE and set it to the desired value.
Once the aws client is configured, generate a KMS customer master key and use that to generate a local data key.
# data_key=$(aws kms generate-data-key --key-id your-key-id --key-spec AES_256 --query 'CiphertextBlob' --output text) # echo 'aws_kms:' # echo '  data_key: !!binary "%s"\n' "$data_key" >> config/master
To apply the renderer on a file-by-file basis add the following line to the top of any pillar with gpg data in it:
#!yaml|aws_kms
Now with your renderer configured, you can include your ciphers in your pillar data like so:
a-secret: gAAAAABaj5uzShPI3PEz6nL5Vhk2eEHxGXSZj8g71B84CZsVjAAtDFY1mfjNRl-1Su9YVvkUzNjI4lHCJJfXqdcTvwczBYtKy0Pa7Ri02s10Wn1tF0tbRwk=
salt.renderers.aws_kms.render(data, saltenv='base', sls='', argline='', **kwargs) Decrypt the data to be rendered that was encrypted using AWS KMS envelope encryption.
salt.renderers.cheetah Cheetah Renderer for Salt
salt.renderers.cheetah.render(cheetah_data, saltenv='base', sls='', method='xml', **kws) Render a Cheetah template.
Return type A Python data structure
salt.renderers.dson DSON Renderer for Salt
This renderer is intended for demonstration purposes. Information on the DSON spec can be found here.
This renderer requires Dogeon (installable via pip)
salt.renderers.dson.render(dson_input, saltenv='base', sls='', **kwargs) Accepts DSON data as a string or as a file object and runs it through the JSON parser.
salt.renderers.genshi Genshi Renderer for Salt
salt.renderers.genshi.render(genshi_data, saltenv='base', sls='', method='xml', **kws) Render a Genshi template. A method should be passed in as part of the kwargs. If no method is passed in, xml is assumed. Valid methods are:
Note that the text method will call NewTextTemplate. If oldtext is desired, it must be called explicitly
salt.renderers.gpg Renderer that will decrypt GPG ciphers
Any key in the SLS file can be a GPG cipher, and this renderer will decrypt it before passing it off to Salt. This allows you to safely store secrets in source control, in such a way that only your Salt master can decrypt them and distribute them only to the minions that need them.
The typical use-case would be to use ciphers in your pillar data, and keep a secret key on your master. You can put the public key in source control so that developers can add new secrets quickly and easily.
This renderer requires the gpg binary. No python libraries are required as of the 2015.8.0 release.
GPG Homedir When running gpg commands, it is important to run commands as the user that owns the keys directory. If salt-master runs as user salt, then su salt before running any gpg commands.
To avoid compatibility and upgrade problems and to provide a standardized location for keys, salt uses /etc/salt/gpgkeys. In order to make the gpg command use this directory, use gpg --homedir /etc/salt/gpgkeys with gpg commands or set the homedir for that user using echo 'homedir /etc/salt/gpgkeys' >> ~/.gnupg.
Setup To set things up, first generate a keypair. On the master, run the following:
# mkdir -p /etc/salt/gpgkeys # chmod 0700 /etc/salt/gpgkeys # gpg --gen-key --homedir /etc/salt/gpgkeys
Do not supply a password for the keypair, and use a name that makes sense for your application. Be sure to back up the gpgkeys directory someplace safe!
NOTE: Unfortunately, there are some scenarios - for example, on virtual machines which don’t have real hardware - where insufficient entropy causes key generation to be extremely slow. In these cases, there are usually means of increasing the system entropy. On virtualised Linux systems, this can often be achieved by installing the rng-tools package.
Import keys to a master If the keys already exist and need to be imported to the salt master, run the following to import them.
gpg --homedir /etc/salt/gpgkeys --import /path/to/private.key gpg --homedir /etc/salt/gpgkeys --import /path/to/pubkey.gpg
Note: The default GPG Homedir <gpg-homedir> is ~/.gnupg and needs to be set using --homedir.
Adjust trust level of imported keys In some cases, importing existing keys may not be enough and the trust level of the key needs to be adjusted. This can be done by editing the key. The key_id and the actual trust level of the key can be seen by listing the already imported keys.
gpg --homedir /etc/salt/gpgkeys --list-keys gpg --homedir /etc/salt/gpgkeys --list-secret-keys
If the trust-level is not ultimate it needs to be changed by running
gpg --homedir /etc/salt/gpgkeys --edit-key <key_id>
This will open an interactive shell for the management of the GPG encryption key.  Type trust to be able to set the trust level for the key and then select 5 (I trust ultimately). Then quit the shell by typing save.
Different GPG Location In some cases, it's preferable to have gpg keys stored on removable media or other non-standard locations. This can be done using the gpg_keydir option on the salt master. This will also require using a different path to --homedir, as mentioned in the GPG Homedir <gpg-homedir> section.
gpg_keydir: <path/to/homedir>
Export the Public Key # gpg --homedir /etc/salt/gpgkeys --armor --export <KEY-NAME> > exported_pubkey.gpg
Import the Public Key To encrypt secrets, copy the public key to your local machine and run:
$ gpg --import exported_pubkey.gpg