.. _events:

.. index:: ! Event, event bus, event system
    see: Reactor; Event

=================
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.

Event types
===========

.. toctree::
    :maxdepth: 2

    master_events

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:

.. code-block:: python

    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
default all events will be returned. If only authentication events are
desired, then pass the tag "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.

.. code-block:: python

    import salt.utils.event

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

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

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:

.. code-block:: python

    import salt.utils.event

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

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


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:

.. code-block:: bash

    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:

.. code-block:: bash

    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:

.. code-block:: bash

    salt minionname event.fire '{"data": "message for the minion"}' 'tag'


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:

.. code-block:: python

    # 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.

.. code-block:: python

    # Import the proper library
    import salt.utils.event
    # 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)
    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:

.. code-block:: python

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

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

.. code-block:: python

    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.