doc/user/scripting.rst

   1 .. _scripting-user:
   2
   3 *********
   4 Scripting
   5 *********
   6
   7 The behavior of FRR may be extended or customized using its built-in scripting
   8 capabilities. The scripting language is Lua 5.3. This guide assumes Lua
   9 knowledge. For more information on Lua, consult the Lua 5.3 reference manual, or
  10 *Programming in Lua* (note that the free version covers only Lua 5.0).
  11
  12 https://www.lua.org/manual/5.3/
  13
  14 http://www.lua.org/pil/contents.html
  15
  16 Scripting
  17 =========
  18
  19 .. seealso:: Developer docs for scripting
  20
  21 How to use
  22 ----------
  23
  24 1. Identify the Lua function name. See :ref:`lua-hook-calls`.
  25
  26 2. Write the Lua script
  27
  28 3. Configure FRR to use the Lua script
  29
  30 In order to use scripting, FRR must be built with ``--enable-scripting``.
  31
  32 .. note::
  33
  34    Scripts are typically loaded just-in-time. This means you can change the
  35    contents of a script that is in use without restarting FRR. Not all
  36    scripting locations may behave this way; refer to the documentation for the
  37    particular location.
  38
  39
  40 Example: on_rib_process_dplane_results
  41 --------------------------------------
  42
  43 This example shows how to write a Lua script that logs changes when a route is
  44 added.
  45
  46 First, identify the Lua hook call to attach a Lua function to: this will be the
  47 name of the Lua function. In this case, since the hook call is
  48 `on_rib_process_dplane_results`:
  49
  50 .. code-block:: lua
  51
  52    function on_rib_process_dplane_results(ctx)
  53       log.info(ctx.rinfo.zd_dest.network)
  54       return {}
  55
  56
  57 The documentation for :ref:`on-rib-process-dplane-results` tells us its
  58 arguments. Here, the destination prefix for a route is being logged out.
  59
  60 Scripts live in :file:`/etc/frr/scripts/` by default. This is configurable at
  61 compile time via ``--with-scriptdir``. It may be overriden at runtime with the
  62 ``--scriptdir`` daemon option.
  63
  64 The documentation for :ref:`on-rib-process-dplane-results` indicates that the
  65 ``script`` command should be used to set the script. Assuming that the above
  66 function was created in :file:`/etc/frr/scripts/my_dplane_script.lua`, the
  67 following vtysh command sets the script for the hook call:
  68
  69 .. code-block:: console
  70
  71    script on_rib_process_dplane_results my_dplane_script
  72
  73
  74 After the script is set, when the hook call is hit, FRR will look for a
  75 *on_rib_process_dplane_results* function in
  76 :file:`/etc/frr/scripts/my_dplane_script.lua` and run it with the ``ctx`` object
  77 as its argument.
  78
  79
  80 .. _lua-hook-calls:
  81
  82 Available Lua hook calls
  83 ========================
  84
  85 :ref:`on-rib-process-dplane-results`