2. Salt Event System

The Salt Event System is used to fire off events enabling third party applications or external processes to react to behavior within Salt.

The event system is comprised of a two primary components:

  • The event sockets which publishes events.
  • The event library which can listen to events and send events into the salt system.

2.2. Listening for Events

The event system is accessed via the event library and can only be accessed by the same system user that Salt is running as. To listen to events a SaltEvent object needs to be created and then the get_event function needs to be run. The SaltEvent object needs to know the location that the Salt Unix sockets are kept. In the configuration this is the sock_dir option. The sock_dir option defaults to "/var/run/salt/master" on most systems.

The following code will check for a single event:

import salt.utils.event

event = salt.utils.event.MasterEvent('/var/run/salt/master')

data = event.get_event()

Events will also use a "tag". Tags allow for events to be filtered by prefix. By default all events will be returned. If only authentication events are desired, then pass the tag "salt/auth".

The get_event method has a default poll time assigned of 5 seconds. To change this time set the "wait" option.

The following example will only listen for auth events and will wait for 10 seconds instead of the default 5.

import salt.utils.event

event = salt.utils.event.MasterEvent('/var/run/salt/master')

data = event.get_event(wait=10, tag='salt/auth')

To retrieve the tag as well as the event data, pass full=True:

import salt.utils.event

event = salt.utils.event.MasterEvent('/var/run/salt/master')

evdata = event.get_event(wait=10, tag='salt/job', full=True)

tag, data = evdata['tag'], evdata['data']

# tag == 'salt/job/JOBID/ret/MINIONNAME

Instead of looking for a single event, the iter_events method can be used to make a generator which will continually yield salt events.

The iter_events method also accepts a tag but not a wait time:

import salt.utils.event

event = salt.utils.event.MasterEvent('/var/run/salt/master')

for data in event.iter_events(tag='salt/auth'):

2.3. Firing Events

It is possible to fire events on either the minion's local bus or to fire events intended for the master.

To fire a local event from the minion, on the command line:

salt-call event.fire '{"data": "message to be sent in the event"}' 'tag'

To fire an event to be sent to the master, from the minion:

salt-call event.fire_master '{"data": "message for the master"}' 'tag'

If a process is listening on the minion, it may be useful for a user on the master to fire an event to it:

# Job on minion
import salt.utils.event

event = salt.utils.event.MinionEvent(**__opts__)

for evdata in event.iter_events(tag='customtag/'):
    return evdata # do your processing here...
salt minionname event.fire '{"data": "message for the minion"}' 'customtag/african/unladen'

2.4. Firing Events From Code

Events can be very useful when writing execution modules, in order to inform various processes on the master when a certain task has taken place. In Salt versions previous to 0.17.0, the basic code looks like:

# Import the proper library
import salt.utils.event
# Fire deploy action
sock_dir = '/var/run/salt/minion'
event = salt.utils.event.SaltEvent('master', sock_dir)
event.fire_event('Message to be sent', 'tag')

In Salt version 0.17.0, the ability to send a payload with a more complex data structure than a string was added. When using this interface, a Python dictionary should be sent instead.

# Import the proper library
import salt.utils.event
# bring in the system configuration
import salt.config
cfg = salt.config.minion_config("/etc/salt/minion")
# Fire deploy action
sock_dir = '/var/run/salt/minion'
payload = {'sample-msg': 'this is a test',
           'example': 'this is the same test'}
event = salt.utils.event.SaltEvent('master', sock_dir, opts=cfg)
event.fire_event(payload, 'tag')

It should be noted that this code can be used in 3rd party applications as well. So long as the salt-minion process is running, the minion socket can be used:

sock_dir = '/var/run/salt/minion'

So long as the salt-master process is running, the master socket can be used:

sock_dir = '/var/run/salt/master'

This allows 3rd party applications to harness the power of the Salt event bus programmatically, without having to make other calls to Salt.

A 3rd party process can listen to the event bus on the master and another 3rd party process can fire events to the process on the master, which Salt will happily pass along.

To fire an event to be sent to the master, from the minion, from code:

import salt.utils.event
import salt.config
cfg = salt.config.minion_config("/etc/salt/minion")
sock_dir = '/var/run/salt/minion'
tag = "tag"
payload = {'sample-msg": "this is a test'}
# The message wrapper
# Create an event interface
event = salt.utils.event.SaltEvent("minion", sock_dir, opts=cfg)
# Fire the event across
event.fire_master(payload, tag)

These docs are for Salt's development version: 2ee0118.

Docs for previous releases are available on readthedocs.org.

Latest Salt release: 2014.7.1

Table Of Contents

Previous topic

1.8.1. States

Next topic

2.1.1. Salt Master Events


Call for speakers now open. Early-bird and group discounts.

SaltStack training

Now offering remote attendee training!