doc: Add doc for zebra hook calls

Signed-off-by: Donald Lee <dlqs@gmx.com>
This commit is contained in:
Donald Lee 2021-08-23 01:40:36 +08:00
parent 310dd2b362
commit 30085ba550
2 changed files with 264 additions and 11 deletions

View File

@ -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`

View File

@ -1416,3 +1416,199 @@ Debugging
Nexthop and nexthop-group events.
Scripting
=========
.. clicmd:: zebra on-rib-process script SCRIPT
Set a Lua script for :ref:`on-rib-process-dplane-results` hook call.
SCRIPT is the basename of the script, without `.lua`.
Data structures
---------------
.. _const-struct-zebra-dplane-ctx:
const struct zebra_dplane_ctx
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: console
* integer zd_op
* integer zd_status
* integer zd_provider
* integer zd_vrf_id
* integer zd_table_id
* integer zd_ifname
* integer zd_ifindex
* table rinfo (if zd_op is DPLANE_OP_ROUTE*, DPLANE_NH_*)
* prefix zd_dest
* prefix zd_src
* integer zd_afi
* integer zd_safi
* integer zd_type
* integer zd_old_type
* integer zd_tag
* integer zd_old_tag
* integer zd_metric
* integer zd_old_metric
* integer zd_instance
* integer zd_old_instance
* integer zd_distance
* integer zd_old_distance
* integer zd_mtu
* integer zd_nexthop_mtu
* table nhe
* integer id
* integer old_id
* integer afi
* integer vrf_id
* integer type
* nexthop_group ng
* nh_grp
* integer nh_grp_count
* integer zd_nhg_id
* nexthop_group zd_ng
* nexthop_group backup_ng
* nexthop_group zd_old_ng
* nexthop_group old_backup_ng
* integer label (if zd_op is DPLANE_OP_LSP_*)
* table pw (if zd_op is DPLANE_OP_PW_*)
* integer type
* integer af
* integer status
* integer flags
* integer local_label
* integer remote_label
* table macinfo (if zd_op is DPLANE_OP_MAC_*)
* integer vid
* integer br_ifindex
* ethaddr mac
* integer vtep_ip
* integer is_sticky
* integer nhg_id
* integer update_flags
* table rule (if zd_op is DPLANE_OP_RULE_*)
* integer sock
* integer unique
* integer seq
* string ifname
* integer priority
* integer old_priority
* integer table
* integer old_table
* integer filter_bm
* integer old_filter_bm
* integer fwmark
* integer old_fwmark
* integer dsfield
* integer old_dsfield
* integer ip_proto
* integer old_ip_proto
* prefix src_ip
* prefix old_src_ip
* prefix dst_ip
* prefix old_dst_ip
* table iptable (if zd_op is DPLANE_OP_IPTABLE_*)
* integer sock
* integer vrf_id
* integer unique
* integer type
* integer filter_bm
* integer fwmark
* integer action
* integer pkt_len_min
* integer pkt_len_max
* integer tcp_flags
* integer dscp_value
* integer fragment
* integer protocol
* integer nb_interface
* integer flow_label
* integer family
* string ipset_name
* table ipset (if zd_op is DPLANE_OP_IPSET_*)
* integer sock
* integer vrf_id
* integer unique
* integer type
* integer family
* string ipset_name
* table neigh (if zd_op is DPLANE_OP_NEIGH_*)
* ipaddr ip_addr
* table link
* ethaddr mac
* ipaddr ip_addr
* integer flags
* integer state
* integer update_flags
* table br_port (if zd_op is DPLANE_OP_BR_PORT_UPDATE)
* integer sph_filter_cnt
* integer flags
* integer backup_nhg_id
* table neightable (if zd_op is DPLANE_OP_NEIGH_TABLE_UPDATE)
* integer family
* integer app_probes
* integer ucast_probes
* integer mcast_probes
* table gre (if zd_op is DPLANE_OP_GRE_SET)**
* integer link_ifindex
* integer mtu
.. _const-struct-nh-grp:
const struct nh_grp
^^^^^^^^^^^^^^^^^^^
.. code-block:: console
* integer id
* integer weight
.. _zebra-hook-calls:
Zebra Hook calls
----------------
.. _on-rib-process-dplane-results:
on_rib_process_dplane_results
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Called when RIB processes dataplane events.
Set script location with the ``zebra on-rib-process script SCRIPT`` command.
**Arguments**
* :ref:`const struct zebra_dplane_ctx<const-struct-zebra-dplane-ctx>` ctx
.. code-block:: lua
function on_rib_process_dplane_results(ctx)
log.info(ctx.rinfo.zd_dest.network)
return {}