# 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

platform:

  all

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:

    mysql.host: 'salt'
    mysql.user: 'salt'
    mysql.pass: 'salt'
    mysql.db: 'salt'
    mysql.port: 3306

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

To use the alternative configuration, append '--return_config alternative' to the salt command.

New in version 2015.5.0.

    salt '*' test.ping --return mysql --return_config alternative

To override individual configuration items, append --return_kwargs '{"key:": "value"}' to the salt command.

New in version 2016.3.0.

    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

  Requires that configuration be enabled via 'event_return' option in master config.

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