# salt.engines.libvirt_events

An engine that listens for libvirt events and resends them to the salt event bus.

The minimal configuration is the following and will listen to all events on the local hypervisor and send them with a tag starting with `salt/engines/libvirt_events`:

    engines:
        - libvirt_events

Note that the automatically-picked libvirt connection will depend on the value of `uri_default` in `/etc/libvirt/libvirt.conf`. To force using another connection like the local LXC libvirt driver, set the `uri` property as in the following example configuration.

    engines:
        - libvirt_events:
            uri: lxc:///
            tag_prefix: libvirt
            filters:
                - domain/lifecycle
                - domain/reboot
                - pool

Filters is a list of event types to relay to the event bus. Items in this list can be either one of the main types (`domain`, `network`, `pool`, `nodedev`, `secret`), `all` or a more precise filter. These can be done with values like <main_type>/<subtype>. The possible values are in the CALLBACK_DEFS constant. If the filters list contains `all`, all events will be relayed.

Be aware that the list of events increases with libvirt versions, for example network events have been added in libvirt 1.2.1 and storage events in 2.0.0.

## Running the engine on non-root

Running this engine as non-root requires a special attention, which is surely the case for the master running as user salt. The engine is likely to fail to connect to libvirt with an error like this one:

> [ERROR ] authentication unavailable: no polkit agent available to authenticate action 'org.libvirt.unix.monitor'

To fix this, the user running the engine, for example the salt-master, needs to have the rights to connect to libvirt in the machine polkit config. A polkit rule like the following one will allow salt user to connect to libvirt:

    polkit.addRule(function(action, subject) {
        if (action.id.indexOf("org.libvirt") == 0 &&
            subject.user == "salt") {
            return polkit.Result.YES;
        }
    });

depends:

  libvirt 1.0.0+ python binding

New in version 2019.2.0.

salt.engines.libvirt_events.start(uri=None, tag_prefix='salt/engines/libvirt_events', filters=None)

  Listen to libvirt events and forward them to salt.

  Parameters:

    - uri -- libvirt URI to listen on. Defaults to None to pick the first available local hypervisor

    - tag_prefix -- the beginning of the salt event tag to use. Defaults to 'salt/engines/libvirt_events'

    - filters -- the list of event of listen on. Defaults to 'all'