New content added to beacon docs.

conf/master

@@ -551,7 +551,7 @@
 # master config file that can then be used on minions.
 #pillar_opts: False
 
-# The pillar_safe_render_error option prevents the master from passing piller
+# The pillar_safe_render_error option prevents the master from passing pillar
 # render errors to the minion. This is set on by default because the error could
 # contain templating data which would give that minion information it shouldn't
 # have, like a password! When set true the error message will only show:

doc/topics/beacons/index.rst

@@ -4,20 +4,35 @@
 Beacons
 =======
 
-The beacon system allows the minion to hook into system processes and
-continually translate external events into the salt event bus. The
-primary example of this is the :py:mod:`~salt.beacons.inotify` beacon. This
-beacon uses inotify to watch configured files or directories on the minion for
-changes, creation, deletion etc.
+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 :ref:`reactor <reactor>`.
 
-This allows for the changes to be sent up to the master where the
-reactor can respond to changes.
+Salt beacons can currently monitor and send Salt events for many system
+activities, including:
 
-Configuring The Beacons
-=======================
+- file system changes
+- system load
+- service status
+- shell activity, such as user login
+- network and disk usage
 
-The beacon system, like many others in Salt, can be configured via the
-minion pillar, grains, or local config file:
+See :ref:`beacon modules <all-salt.beacons>` for a current list.
+
+.. note::
+    Salt beacons are an event generation mechanism. Beacons leverage the Salt
+    :ref:`reactor <reactor>` system to make changes when beacon events occur.
+
+
+Configuring Beacons
+===================
+
+Salt beacons does 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:
 
 .. code-block:: yaml
 
@@ -26,11 +41,15 @@ minion pillar, grains, or local config file:
         /etc/httpd/conf.d: {}
         /opt: {}
 
-Optionally, a beacon can be run on an interval other than the default 
-``loop_interval``, which is typically set to 1 second.
+The beacon system, like many others in Salt, can also be configured via the
+minion pillar, grains, or local config file.
 
-To run a beacon every 5 seconds, for example, provide an ``interval`` argument
-to a beacon.
+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:
 
 .. code-block:: yaml
 
@@ -51,6 +70,123 @@ to a beacon.
           - 1.0
         - interval: 10
 
+Beacon Example
+==============
+
+This example demonstrates configuring the :py:mod:`~salt.beacons.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``:
+
+.. code-block:: yaml
+
+   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:
+
+.. code-block:: bash
+
+   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:
+
+.. code-block:: json
+
+   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``:
+
+.. code-block:: yaml
+
+   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``:
+
+.. code-block:: yaml
+
+   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 :py:mod:`~salt.beacons.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 :ref:`Understanding
+    the Structure of Reactor Formulas <reactor-structure>` 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:
+
+.. code-block:: yaml
+
+   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
 ======================

doc/topics/reactor/index.rst

@@ -32,6 +32,8 @@ The event system fires events with a very specific criteria. Every event has a
 addition to the tag, each event has a data structure. This data structure is a
 dict, which contains information about the event.
 
+.. _reactor-mapping-events:
+
 Mapping Events to Reactor SLS Files
 ===================================
 
@@ -183,6 +185,8 @@ rendered SLS file (or any errors generated while rendering the SLS file).
     view the result of referencing Jinja variables. If the result is empty then
     Jinja produced an empty result and the Reactor will ignore it.
 
+.. _reactor-structure:
+
 Understanding the Structure of Reactor Formulas
 ===============================================