Developer environment

Explains how to use a “development mode” and use the LUA debugger.

Development testbench

While starting to write your LUA scripts it is better to first target a single threaded and single backend engine. This allows you to get the LUA script functionality right. It is also much easier to debug a single threaded Trisul engine calling your LUA scripts.

testbench run options

The following testbench commands are available.

trisulctl_probe testbench guid
Generates a new GUID when you want to create new counter groups, alerts etc
trisulctl_probe testbench run <pcap-file>
Runs a PCAP against your LUA scripts in a single threaded environment with output to the screen
trisulctl_probe testbench run <pcap-file> luatestdir=<lua-directory>
Runs a PCAP file against your lua scripts in the luatestdir directory. Adds this directory to the probe search path. Use this in development mode to avoid copying your lua files to the standard search paths.
trisulctl_probe testbench run <pcap-file> frontend-only
Only runs the frontend fast engine. Use this to test frontend scripts. This is much faster.
trisulctl_probe testbench runluainput <lua-input-filter> <data-file>
Use this to test LUA input filter scripts. Run the input filter LUA passing the data-file as the argument to it. This argument is passed as T.args to your input filter script.

The special ‘debug0’ context

This is a special context that sets up a nice development environment for you.

  1. single threaded
  2. the debug0 context does not actually save the data at the hub, this frees you from cleanups and resets
  3. use the testbench tools which automatically work with the debug0 context
  4. use the built in LUA debugger and interact with the terminal

Creating the debug0 context

Typically this is created automatically when you run the testbench tools


trisulctl_probe
> testbench run /home/bigcaps/upload_misc.tcpd 

Specify a development directory for LUA scripts

Using tp testbench run <pcap-file> luatestdir=<directory> you have test all the LUA scripts in the development directory without copying them to the standard places where Trisul searches for LUA scripts.


# trisulctl_probe
# testbench run /home/mike/pcaps/largeisp.pcap luatestdir=/home/mike/development/trisul_lua/BGPanalysis

TRISUL_LUA_PATHS environment variable

You can also set the TRISUL_LUA_PATHS environment variable before starting Trisul to add your own paths to the standard LUA search paths.



# export TRISUL_LUA_PATHS=/home/mike/development/trisul_lua/BGPanalysis
# trisulctl_probe testbench run /home/mike/pcaps/largeisp.pcap

Using the Lua Debugger

The Trisul framework includes a powerful debugger you can use immediately.

The debugger is installed in /usr/local/lib/trisul-probe/plugins/lua/helpers and is available to all scripts without any special download or installation.

Threading Note
Use the debugger using the testbench tools. It could get messy when you turn it on a regular context as multiple threads can enter the debugger at the same time and you cant tell them apart.

To use the debugger



local dbg = require("debugger")

..

-- then at some point
dbg()



that will drop you into the debugger. You can single step, examine variables, Trisul objects, set breakpoints, etc.

For more check out the documentation for debugger.lua