Beacons¶

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

Avoiding Event Loops¶

It is important to carefully consider the possibility of creating a loop between a reactor and a beacon. For example, one might set up a beacon which monitors whether a file is read which in turn fires a reactor to run a state which in turn reads the file and re-fires the beacon.

To avoid these types of scenarios, the disable_during_state_run argument may be set. If a state run is in progress, the beacon will not be run on its regular interval until the minion detects that the state run has completed, at which point the normal beacon interval will resume.

beacons:
  inotify:
    /etc/passwd: {}
    disable_during_state_run: True

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.

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.

The beacon Function¶

The beacons system will look for a function named beacon in the module. If this function is not present then the beacon will not be fired. This function is called on a regular basis and defaults to being called on every iteration of the minion, which can be tens to hundreds of times a second. This means that the beacon function cannot block and should not be CPU or IO intensive.

The beacon function will be passed in the configuration for the executed beacon. This makes it easy to establish a flexible configuration for each called beacon. This is also the preferred way to ingest the beacon's configuration as it allows for the configuration to be dynamically updated while the minion is running by configuring the beacon in the minion's pillar.

The Beacon Return¶

The information returned from the beacon is expected to follow a predefined structure. The returned value needs to be a list of dictionaries (standard python dictionaries are preferred, no ordered dicts are needed).

The dictionaries represent individual events to be fired on the minion and master event buses. Each dict is a single event. The dict can contain any arbitrary keys but the 'tag' key will be extracted and added to the tag of the fired event.

The return data structure would look something like this:

[{'changes': ['/foo/bar'], 'tag': 'foo'},
 {'changes': ['/foo/baz'], 'tag': 'bar'}]

Calling Execution Modules¶

Execution modules are still the preferred location for all work and system interaction to happen in Salt. For this reason the __salt__ variable is available inside the beacon.

Please be careful when calling functions in __salt__, while this is the preferred means of executing complicated routines in Salt not all of the execution modules have been written with beacons in mind. Watch out for execution modules that may be CPU intense or IO bound. Please feel free to add new execution modules and functions to back specific beacons.

Distributing Custom Beacons¶

Custom beacons can be distributed to minions using saltutil, see Dynamic Module Distribution.