Beacons¶

The beacon system allows the minion to hook into a variety of system processes and continually monitor these processes. When monitored activity occurs in a system process, an event is sent on the Salt event bus that can be used to trigger a reactor.

Salt beacons can currently monitor and send Salt events for many system activities, including:

file system changes
system load
service status
shell activity, such as user login
network and disk usage

See beacon modules for a current list.

Note

Salt beacons are an event generation mechanism. Beacons leverage the Salt reactor system to make changes when beacon events occur.

Configuring Beacons¶

Salt beacons do not require any changes to the system process that is being monitored, everything is configured using Salt.

Beacons are typically enabled by placing a beacons: top level block in the minion configuration file:

beacons:
  inotify:
    /etc/httpd/conf.d: {}
    /opt: {}

The beacon system, like many others in Salt, can also be configured via the minion pillar, grains, or local config file.

Beacon Monitoring Interval¶

Beacons monitor on a 1-second interval by default. To set a different interval, provide an interval argument to a beacon. The following beacons run on 5- and 10-second intervals:

beacons:
  inotify:
    /etc/httpd/conf.d: {}
    /opt: {}
    interval: 5
  load:
    - 1m:
      - 0.0
      - 2.0
    - 5m:
      - 0.0
      - 1.5
    - 15m:
      - 0.1
      - 1.0
    - interval: 10

Beacon Example¶

This example demonstrates configuring the inotify beacon to monitor a file for changes, and then create a backup each time a change is detected.

Note

The inotify beacon requires Pyinotify on the minion, install it using salt myminion pkg.install python-inotify.

First, on the Salt minion, add the following beacon configuration to /ect/salt/minion:

beacons:
  inotify:
    home/user/importantfile:
      mask:
        - modify

Replace user in the previous example with the name of your user account, and then save the configuration file and restart the minion service.

Next, create a file in your home directory named importantfile and add some simple content. The beacon is now set up to monitor this file for modifications.

View Events on the Master¶

On your Salt master, start the event runner using the following command:

salt-run state.event pretty=true

This runner displays events as they are received on the Salt event bus. To test the beacon you set up in the previous section, make and save a modification to the importantfile you created. You'll see an event similar to the following on the event bus:

salt/beacon/minion1/inotify/home/user/importantfile  {
 "_stamp": "2015-09-09T15:59:37.972753",
 "data": {
     "change": "IN_IGNORED",
     "id": "minion1",
     "path": "/home/user/importantfile"
 },
 "tag": "salt/beacon/minion1/inotify/home/user/importantfile"
}

This indicates that the event is being captured and sent correctly. Now you can create a reactor to take action when this event occurs.

Create a Reactor¶

On your Salt master, create a file named srv/reactor/backup.sls. If the reactor directory doesn't exist, create it. Add the following to backup.sls:

backup file:
 cmd.file.copy:
   - tgt: {{ data['data']['id'] }}
   - arg:
     - {{ data['data']['path'] }}
     - {{ data['data']['path'] }}.bak

Next, add the code to trigger the reactor to ect/salt/master:

reactor:
  - salt/beacon/*/inotify/*/importantfile:
    - /srv/reactor/backup.sls

This reactor creates a backup each time a file named importantfile is modified on a minion that has the inotify beacon configured as previously shown.

Note

You can have only one top level reactor section, so if one already exists, add this code to the existing section. See Understanding the Structure of Reactor Formulas to learn more about reactor SLS syntax.

Start the Salt Master in Debug Mode¶

To help with troubleshooting, start the Salt master in debug mode:

service salt-master stop
salt-master -l debug

When debug logging is enabled, event and reactor data are displayed so you can discover syntax and other issues.

Trigger the Reactor¶

On your minion, make and save another change to importantfile. On the Salt master, you'll see debug messages that indicate the event was received and the file.copy job was sent. When you list the directory on the minion, you'll now see importantfile.bak.

All beacons are configured using a similar process of enabling the beacon, writing a reactor SLS, and mapping a beacon event to the reactor SLS.

Writing Beacon Plugins¶

Beacon plugins use the standard Salt loader system, meaning that many of the constructs from other plugin systems holds true, such as the __virtual__ function.

The important function in the Beacon Plugin is the beacon function. When the beacon is configured to run, this function will be executed repeatedly by the minion. The beacon function therefore cannot block and should be as lightweight as possible. The beacon also must return a list of dicts, each dict in the list will be translated into an event on the master.

Please see the inotify beacon as an example.