Adding upstream version 9.1.upstream/9.1

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 85 insertions, 0 deletions

diff --git a/doc/user/scripting.rst b/doc/user/scripting.rst
new file mode 100644
index 0000000..42855de
--- /dev/null
+++ b/doc/user/scripting.rst
@@ -0,0 +1,85 @@
+.. _scripting-user:
+
+*********
+Scripting
+*********
+
+The behavior of FRR may be extended or customized using its built-in scripting
+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).
+
+https://www.lua.org/manual/5.3/
+
+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``.
+
+.. note::
+
+   Scripts are typically loaded just-in-time. This means you can change the
+   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 overridden 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`