doc: Add doc for zebra hook calls

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

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
+https://www.lua.org/manual/5.3/
-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.
 
-These scripts live in :file:`/etc/frr/scripts/` by default. This is
+http://www.lua.org/pil/contents.html
-configurable at compile time via ``--with-scriptdir``. It may be
+
-overriden at runtime with the ``--scriptdir`` daemon option.
+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`

doc/user/zebra.rst

@@ -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 {}