# Returners

By default the return values of the commands sent to the Salt minions are returned to the salt-master. But since the commands executed on the Salt minions are detached from the call on the Salt master, anything at all can be done with the results data.

This is where the returner interface comes in. Returners are modules called in addition to returning the data to the Salt master.

The returner interface allows the return data to be sent to any system that can receive data. This means that return data can be sent to a Redis server, a MongoDB server, a MySQL server, or any system!

See also

Full list of builtin returners

## Using Returners

All commands will return the command data back to the master. Adding more returners will ensure that the data is also sent to the specified returner interfaces.

Specifying what returners to use is done when the command is invoked:

    salt '*' test.ping --return redis_return

This command will ensure that the redis_return returner is used.

It is also possible to specify multiple returners:

    salt '*' test.ping --return mongo_return,redis_return,cassandra_return

In this scenario all three returners will be called and the data from the test.ping command will be sent out to the three named returners.

## Writing a Returner

A returner is a module which contains a returner function, the returner function must accept a single argument. this argument is the return data from the called minion function. So if the minion function `test.ping` is called the value of the argument will be `True`.

A simple returner is implemented here:

    import redis
    import json

    def returner(ret):
        '''
        Return information to a redis server
        '''
        # Get a redis connection
        serv = redis.Redis(
                    host='redis-serv.example.com',
                    port=6379,
                    db='0')
        serv.sadd("%(id)s:jobs" % ret, ret['jid'])
        serv.set("%(jid)s:%(id)s" % ret, json.dumps(ret['return']))
        serv.sadd('jobs', ret['jid'])
        serv.sadd(ret['jid'], ret['id'])

This simple example of a returner set to send the data to a redis server serializes the data as json and sets it in redis.

You can place your custom returners in a `_returners` directory within the `file_roots` specified by the master config file. These custom returners are distributed when `state.highstate` is run, or by executing the `saltutil.sync_returners` or `saltutil.sync_all` functions.

Any custom returners which have been synced to a minion, that are named the same as one of Salt's default set of returners, will take the place of the default returner with the same name. Note that a returner's default name is its filename (i.e. `foo.py` becomes returner `foo`), but that its name can be overridden by using a __virtual__ function. A good example of this can be found in the redis returner, which is named `redis_return.py` but is loaded as simply `redis`:

    try:
        import redis
        HAS_REDIS = True
    except ImportError:
        HAS_REDIS = False

    def __virtual__():
        if not HAS_REDIS:
            return False
        return 'redis'

### Examples

The collection of built-in Salt returners can be found here: https://github.com/saltstack/salt/blob/develop/salt/returners

Current Salt release: 0.17.1

### Table Of Contents

- Returners
  - Using Returners
  - Writing a Returner
    - Examples

#### Previous topic

salt.modules.zypper

#### Next topic

Full list of builtin returner modules

### Quick search

Enter search terms or a module, class or function name.

### Upcoming SaltStack Events

My conferences on Lanyrd