HTTP Lua Parsers CLI Debugging Tool

Document created by RSA Information Design and Development Employee on Jan 29, 2020Last modified by RSA Product Team on Jan 30, 2020
Version 2Show Document
  • View in full screen mode

The information in this topic applies to RSA NetWitness Platform version 11.4 and later.

The NetWitness Decoder provides the Lua Parser Command Line Debugger tool in NwConsole. It is intended for NetWitness Content developers and for customers who are developing their own Lua parsers content.

The Lua parser command line debugger tool is a remote tool in NwConsole. The debugger can attach to NwDecoder as a debug target and can pause to inspect the state of a running parser. It also provides the option to run Lua Stack Sampler, which quickly pauses the running Lua environments in the Decoder, collects the stack traces, and then resumes execution.

Prerequisites

A new role permission, debugger is available in /users/roles/debuggers; it allows usage of the Lua parser debugger tool. The debugger permission must be enabled for users to launch the Lua parser debugger tool.

To enable the debugger permission:

  1. Log into the NetWitness Platform user interface and go to ADMIN > Services.
  2. Select a Decoder service and click > View > Security.
  3. Click the Roles tab, and in the right pane, click a role, for example, Administrators.
    Permissions that are available for that role are displayed in the right pane.
  4. Select debuggers and then click Apply.
    The debuggers permission is enabled for the role that you selected.

Usage

The following image shows how to user the Lua parsers debug command: luadbg.

The purpose of the Lua debugger is to allow users to pause Decoder Lua parser execution and then inspect Lua parsers state and execution, and to collect stack trace samples. The Lua debugger can be used while the Decoder is running with Capture on or while importing pcap. After luadbg is started, it reads commands from the terminal until you use the command exit to exit the debugger.

Functional Options

You can perform the following functions with the Lua Parser command line debugger tool:

  • Freeze execution of a live-running instance of code (by hitting a breakpoint on a specific line of code).
  • Examine variables used by the parser at the point where the breakpoint was hit.
  • Advance the parser code line-by-line to follow the execution path.
  • View the call stack to see how and when the Decoder executes its parser code.
  • Check the status of the current stack frame, which displays source code context of 4 lines above and 5 lines below the current breakpoint.
  • Step into and out of the routine.
  • Walk up and down over the call stack and inspect local variables within frames of the call stack.
  • Use the stack sampler to collect stack trace across all Lua parser threads.
    • The stack sampler can be used to get an understanding of how Lua parsers are performing. It can be useful to be able to quickly get a sample of the parsers' call stack while it is running.
    • Probability dictates that the sample will land wherever the parser is doing the most work. If you sample many times, you can get a simple profile of the Lua parser.

At least one breakpoint must be set for the Lua parsers to enter active debug mode. Certain activities on the Decoder occur at a higher precedence than current debug activity. When those activities are initiated, the debugger becomes detached and the execution continues to allow those operations. You can control this by disabling the debugger auto.detach mode using the configuration option /decoder/parsers/config/lua.debugger.auto.detach. The default for this option is yes.

The Lua parser debugger is automatically detached in higher-precedence conditions such as the following:

  • Parser reload
  • Parser upload
  • Capture stop
  • Service shutdown
  • Decoder pcap import.

    • By default, the Lua parser debugger is detached during pcap import. You can control this with the following setting:

      set /decoder/parsers/config/lua.debugger.auto.detach = no

      • Enable or disable this option to automatically detach a running Lua debugger on capture stop.
      • Disabling lua.debugger.auto.detach pauses the capture stop process when parse threads are waiting on a breakpoint.
      • If you are debugging a pcap upload, set this option to no so that the debugger does not automatically detach.

        • The Decoder service will be paused to allow debug activity when parse threads are waiting on a breakpoint.
        • On exit, the debugger will be detached to allow other operations on the Decoder.
      • The default value is set to yes, which automatically detaches the Lua Debugger when capture is stopped. The change takes effect immediately.

Lua Debugger Commands and Options

The following image shows the Lua Parser Debugger tool commands and options (available using the help command).

Usage:

command <optional sub-command>

help command - for individual command help

Individual commands also have a command alias for a better debugging experience, as described below.

break [b]

Add a breakpoint to the specified source file and line number. (Requires file:line-number)

continue [c]

Continue Lua execution.

info [i]

Information about sub-commands: (Requires sub-command)

  • locals Dumps local variables.
  • breakpoints [bp] List of breakpoints.
  • frame Shows debug status.
  • sources Shows list of Lua source files.

info breakpoints or info bp

delete [del]

Delete the breakpoint at the index provided.

status [st]

Shows the current debug status.

  • Shows the context of the current lines of source (5 lines above and 4 lines below the current break wait.)
  • Shows thread ID and frame details.

backtrace [bt]

Shows a backtrace of the current stack.

  • #<num> is the frame number.
  • ?? is displayed for unnamed method references.

info locals

Dumps local variables.

print [p]

Shows the value of specified variable. (Requires file:line-number)

The following image shows the info and print commands.

next [n]

Steps to the next line.

step [s]

Steps into a routine.

import [imp]

Imports Lua source file references into the debugger. Requires a.lua or .luax filename as an argument.

The following image shows the step and import commands.

Note: In this example, after stepping to nwll.lua the source context was not found because it was not loaded. We used another command to import nwll.lua, and were then able to print the source context.

finish [fin]

Step out of a routine.

up [u]

Move one frame up the stack.

down [d]

Move one frame down the stack.

frame [f]

Switch to a specified frame number. The default is to print the current frame.

The following image shows the up, down, and frame commands.

interrupt [int]

Requests an interrupt in Lua execution. The default is to turn on the interrupt request.

Sub commands:

  • error on

    Turns on interrupt for errors. This pauses Lua execution on errors.

  • error off

    Turns off interrupt for errors. Clears the interrupt error handler.

  • on

    Turns on interrupt request. Requires that capture is running.

  • off

    Turns off interrupt request.

The following image shows interrupt with error on.

The following image shows interrupt with on.

info sources

Shows the list of Lua source files.

remove [rm]

Removes a Lua source file reference from debugger. Requires .lua or .luax filename as an argument.

The following image shows the sources list when multiple sources are imported.

detach

Detaches the Lua debugger. This also resets breakpoints.

Lua Stack Sampler

stacktrace [where]

Attaches the Lua debugger and returns stacktrace from the available threads.

The following images show three examples of the Lua stack sampler.

 

You are here

Table of Contents > HTTP Lua Parsers CLI Debugging Tool

Attachments

    Outcomes