85 lines
2.4 KiB
ReStructuredText
85 lines
2.4 KiB
ReStructuredText
.. _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`
|