-.. _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``.
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`
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 {}
projects / mirror / frr.git / commitdiff