doc: Add doc for zebra hook calls

Signed-off-by: Donald Lee <dlqs@gmx.com>

1 files changed, 68 insertions, 11 deletions

diff --git a/doc/user/scripting.rst b/doc/user/scripting.rst
index b0295e570..badc82c50 100644
--- a/doc/user/scripting.rst
+++ b/doc/user/scripting.rst
@@ -1,22 +1,31 @@
-.. _scripting:
+.. _scripting-user:
 
 *********
 Scripting
 *********
 
 The behavior of FRR may be extended or customized using its built-in scripting
-capabilities.
+capabilities. The scripting language is Lua 5.3. This guide assumes Lua
+knowledge. For more information on Lua, consult the Lua 5.3 reference manual, or
+*Programming in Lua* (note that the free version covers only Lua 5.0).
 
-Some configuration commands accept the name of a Lua script to call to perform
-some task or make some decision. These scripts have their environments
-populated with some set of inputs, and are expected to populate some set of
-output variables, which are read by FRR after the script completes. The names
-and expected contents of these scripts are documented alongside the commands
-that support them.
+https://www.lua.org/manual/5.3/
 
-These scripts live in :file:`/etc/frr/scripts/` by default. This is
-configurable at compile time via ``--with-scriptdir``. It may be
-overriden at runtime with the ``--scriptdir`` daemon option.
+http://www.lua.org/pil/contents.html
+
+Scripting
+=========
+
+.. seealso:: Developer docs for scripting
+
+How to use
+----------
+
+1. Identify the Lua function name. See :ref:`lua-hook-calls`.
+
+2. Write the Lua script
+
+3. Configure FRR to use the Lua script
 
 In order to use scripting, FRR must be built with ``--enable-scripting``.
 
@@ -26,3 +35,51 @@ In order to use scripting, FRR must be built with ``--enable-scripting``.
    contents of a script that is in use without restarting FRR. Not all
    scripting locations may behave this way; refer to the documentation for the
    particular location.
+
+
+Example: on_rib_process_dplane_results
+--------------------------------------
+
+This example shows how to write a Lua script that logs changes when a route is
+added.
+
+First, identify the Lua hook call to attach a Lua function to: this will be the
+name of the Lua function. In this case, since the hook call is
+`on_rib_process_dplane_results`:
+
+.. code-block:: lua
+
+   function on_rib_process_dplane_results(ctx)
+      log.info(ctx.rinfo.zd_dest.network)
+      return {}
+
+
+The documentation for :ref:`on-rib-process-dplane-results` tells us its
+arguments. Here, the destination prefix for a route is being logged out.
+
+Scripts live in :file:`/etc/frr/scripts/` by default. This is configurable at
+compile time via ``--with-scriptdir``. It may be overriden at runtime with the
+``--scriptdir`` daemon option.
+
+The documentation for :ref:`on-rib-process-dplane-results` indicates that the
+``script`` command should be used to set the script. Assuming that the above
+function was created in :file:`/etc/frr/scripts/my_dplane_script.lua`, the
+following vtysh command sets the script for the hook call:
+
+.. code-block:: console
+
+   script on_rib_process_dplane_results my_dplane_script
+
+
+After the script is set, when the hook call is hit, FRR will look for a
+*on_rib_process_dplane_results* function in
+:file:`/etc/frr/scripts/my_dplane_script.lua` and run it with the ``ctx`` object
+as its argument.
+
+
+.. _lua-hook-calls:
+
+Available Lua hook calls
+========================
+
+:ref:`on-rib-process-dplane-results`