This wiki has been migrated to https://gitlab.com/wireshark/wireshark/-/wikis/home and is now deprecated. Please use that site instead.

Lua

Lua's been added to ethereal as a language for prototyping and scripting.

For more information about Lua refer to [http://www.lua.org Lua's main site], there you can find its [http://www.lua.org/manual/5.0/manual.html Reference Manual] and a [http://www.lua.org/pilhttp://www.lua.org/pil book] that describes the language. There is also [http://lua-users.org/wiki/ The lua-users wiki].

beware the GPL

Ethereal is released under [http://www.gnu.org/licenses/gpl.html GPL] so every derivative work based on ethereal must be released under the terms of the GPL.

/!\ Even if the code you write in Lua does not need to be GPL'ed. The code written in Lua that uses bindings to ethereal must be distributed under the GPL terms. see the [http://www.gnu.org/licenses/gpl-faq.html#TOCIfInterpreterIsGPL GPL FAQ] for more info /!\

There is at least one ethereal author that will not allow to distribute derivative work under different terms. To distribute Lua code that uses ethereal's bindings under different terms would be a clear violation of the GPL.

If it isn't clear to you what the GPL is and how it works please consult your laywer.

Lua in Ethereal

Lua can be used to write [:Lua/Dissectors: dissectors], post-dissectors and [:Lua/Taps: taps].

Although it's possible to write [:Lua/Dissectors: dissectors] in Lua, ethereal dissectors are written in C, as C is several times faster than Lua. Lua is ok for prototyping dissectors, during Reverse Engineering you can use your time for finding out how things work instead of compiling and debugging your C dissector.

Post-dissectors are dissectors meant to run after every other dissector has run. They can add items the dissection tree so they can be used to create your own extensions to the filtering mechanism.

[:Lua/Taps: Taps] are used to collect information after the packet has been dissected.

Getting Started

Lua is an optional module in ethereal 0.10.15(???) so it won't be installed by default. If you want to use it make sure you install it.

To check if it is installed go to Help->About Ethereal go to the Plugins tab and look for it.

attachment:about.png

To test if it works write a simple Lua script like:

-- hello.lua
-- Lua's implementation of D. Ritchie's hello world program.

    print("hello world!")

run tethereal -X lua_script:hello.lua from the command prompt and tou should see something like:

$ tethereal -X lua_script:hello.lua
hello world!
Capturing on en0
1   0.000000 111.123.234.55 -> 111.123.234.255 NBNS Name query NB XXX.COM<00>

if you can read "hello world!" in the first line after you run tethereal Lua is ready to go.

How Lua fits into ethereal

Once the Lua plugin is installed every time ethereal starts it will serach first for a script called init.lua located in the data directory of ethereal. If it founds it ethereal will run this script.

Once data_dir/init.lua has run that there are two variables that tell ethethereal whether to continue looking for scripts.

If the first init script sets the variable disable_lua to true ethereal will stop reading scripts and shut down the lua engine right after the script was runt.

If ethereal is running suexec (i.e. as root but launched by another user) it will check if the variable run_user_scripts_when_superuser is set to true before loading any further scripts.

Once this first script was runt ethereal will continue running user_dir/init.lua and then all scripts passed with the -X lua_script:xxx.lua command line option in the given order.

All these scripts will be run before packets are read, at the end of the dissector registration process. So, what you have to do, is to register a series of functions that will be called while processing packets.

Classes

Examples

Discussion

This page is a good start. However, some things remain unclear:

That's what it is, a start... I think it's soon to complete as things are changing as I go ahead.