# Runners

Salt runners are convenience applications executed with the salt-run command.

Salt runners work similarly to Salt execution modules however they execute on the Salt master itself instead of remote Salt minions.

A Salt runner can be a simple client call or a complex application.

See also

The full list of runners

## Writing Salt Runners

A Salt runner is written in a similar manner to a Salt execution module. Both are Python modules which contain functions and each public function is a runner which may be executed via the salt-run command.

For example, if a Python module named `test.py` is created in the runners directory and contains a function called `foo`, the `test` runner could be invoked with the following command:

    # salt-run test.foo

Runners have several options for controlling output.

Any `print` statement in a runner is automatically also fired onto the master event bus where. For example:

    def a_runner(outputter=None, display_progress=False):
        print("Hello world")
        ...

The above would result in an event fired as follows:

    Event fired at Tue Jan 13 15:26:45 2015
    *************************
    Tag: salt/run/20150113152644070246/print
    Data:
    {'_stamp': '2015-01-13T15:26:45.078707',
     'data': 'hello',
      'outputter': 'pprint'}

A runner may also send a progress event, which is displayed to the user during runner execution and is also passed across the event bus if the `display_progress` argument to a runner is set to True.

A custom runner may send its own progress event by using the `__jid_event_.fire_event()` method as shown here:

    if display_progress:
        __jid_event__.fire_event({"message": "A progress message"}, "progress")

The above would produce output on the console reading: `A progress message` as well as an event on the event similar to:

    Event fired at Tue Jan 13 15:21:20 2015
    *************************
    Tag: salt/run/20150113152118341421/progress
    Data:
    {'_stamp': '2015-01-13T15:21:20.390053',
     'message': "A progress message"}

A runner could use the same approach to send an event with a customized tag onto the event bus by replacing the second argument (`progress`) with whatever tag is desired. However, this will not be shown on the command-line and will only be fired onto the event bus.

## Synchronous vs. Asynchronous

A runner may be fired asynchronously which will immediately return control. In this case, no output will be display to the user if `salt-run` is being used from the command-line. If used programmatically, no results will be returned. If results are desired, they must be gathered either by firing events on the bus from the runner and then watching for them or by some other means.

Note

When running a runner in asynchronous mode, the `--progress` flag will not deliver output to the salt-run CLI. However, progress events will still be fired on the bus.

In synchronous mode, which is the default, control will not be returned until the runner has finished executing.

To add custom runners, put them in a directory and add it to `runner_dirs` in the master configuration file.

## Examples

Examples of runners can be found in the Salt distribution:

salt/runners

A simple runner that returns a well-formatted list of the minions that are responding to Salt calls could look like this:

    # Import salt modules
    import salt.client

    def up():
        """
        Print a list of all of the minions that are up
        """
        client = salt.client.LocalClient(__opts__["conf_file"])
        minions = client.cmd("*", "test.version", timeout=1)
        for minion in sorted(minions):
            print(minion)