This wiki has been migrated to https://gitlab.com/wireshark/wireshark/-/wikis/home and is now deprecated. Please use that site instead.
Differences between revisions 1 and 28 (spanning 27 versions)
Revision 1 as of 2006-01-23 11:59:47
Size: 873
Editor: LuisOntanon
Comment:
Revision 28 as of 2006-06-05 03:19:18
Size: 7379
Editor: localhost
Comment:
Deletions are marked like this. Additions are marked like this.
Line 3: Line 3:
= Using Lua in ethereal = = Lua =
 ||attachment:lua_logo.gif||Lua is a powerful light-weight programming language designed for extending applications. Lua is designed and implemented by a [http://www.lua.org/authors.html team] at [http://www.puc-rio.br/ PUC-Rio], the Pontifical Catholic University of Rio de Janeiro in Brazil. Lua was born and raised at [http://www.tecgraf.puc-rio.br/ Tecgraf], the Computer Graphics Technology Group of PUC-Rio, and is now housed at [http://www.lua.org Lua.org]. Both Tecgraf and Lua.org are laboratories of the [http://www.inf.puc-rio.br/ Department of Computer Science]. ||
 
Lua's been added to wireshark as a language for prototyping and scripting.
Line 5: Line 8:
== Info about Lua == 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].
Line 7: Line 10:
== Lua's interface to Ethereal == == beware the GPL ==
Wireshark is released under [http://www.gnu.org/licenses/gpl.html GPL] so every derivative work based on wireshark 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 wireshark 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 wireshark author that will not allow to distribute derivative work under different terms. To distribute Lua code that uses wireshark'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 Wireshark ==
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, wireshark 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 available as a plugin since wireshark 0.10.15(???) but it won't be installed by default. If you want to use it make sure you install it.

If you want to install the lua plugin:

 * *NIX: {{{configure --with-lua=<lua_directory>}}}
 * Windows: select the lua plugin at the {{{setup.exe}}}

To check if it is already installed go to {{{Help->About Wireshark}}} 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!")
}}}

Name this script {{{hello.lua}}} and place it in the current directory.

run {{{tshark -X lua_script:hello.lua}}} from the command prompt and you should see something like:
{{{
$ tshark -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 tshark Lua is ready to go.

/!\ Please note: this won't work with the WIN32 version of Wireshark, as the console is opened '''after''' the lua engine is loaded (or the console it not opened at all, depending on the Preferences)! XXX - We should fix this somehow!

== How Lua fits into wireshark ==
Once the Lua plugin is installed every time wireshark starts it will search first for a script called init.lua located in the global configuration directory of wireshark. If wireshark finds this file it will run the script.

Once ''<global config dir>''/init.lua has run that there are two variables that tell wireshark whether to continue looking for scripts.

If the first init script sets the variable {{{disable_lua}}} to {{{true}}} wireshark will stop reading scripts and shut down the lua engine right after the script was run.

If wireshark 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 run wireshark will continue running ''<perconal config 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.

Line 9: Line 77:

 * [:Lua/Tap: Tap]
 * [:Lua/Field: Field] a handy tool to get fileds from the tree

 * [:Lua/Proto: Proto] represents a protocol
 * [:Lua/ProtoField: ProtoField] the fields of a protocol
 * [:Lua/ProtoFieldArray: ProtoFieldArray]

 * [:Lua/Dissector: Dissector] utility class to handle dissectors
 * [:Lua/Dissector: DissectorTable] utility class to handle dissectors
Line 10: Line 89:
 * [:Lua/Column: Column] access to ethereal packet summary fields
 * [:Lua/Dissector: Dissector] utility class to handle dissectors
 * [:Lua/DissectorTable: DissectorTable] utility class to handle dissectors
 * [:Lua/ProtoField: ProtoField]
 * [:Lua/Tap: Tap]
 * [:Lua/ValueString: ValueString]
 * [:Lua/SubTreeTypeArray: SubTreeTypeArray]
 * [:Lua/SubTreeTypeArray: SubTreeTypeArray]
 * [:Lua/SubTreeTypeArray: SubTreeTypeArray]
Line 20: Line 91:
 * [:Lua/ProtoItem: ProtoItem]  * [:Lua/ProtoTree: ProtoItem]
 * [:Lua/SubTree: SubTree] subtrees
Line 22: Line 95:
 * [:Lua/ByteArray: ByteArray] utility class to manage an array of bytes * [:Lua/FieldExtractor: FieldExtractor]  * [:Lua/ByteArray: ByteArray] utility class to manage an array of bytes

* [:Lua/Gui: TextWindow] class that manages text-only windows.
 * [:Lua/Dumper: Dumpe
r] class that manages writing to capture files.
Line 25: Line 101:
 Examples of generic Lua code can be found in [http://lua-users.org/wiki/SampleCode The Sample Code] page of Lua-Users wiki.

 * [:Lua/Examples/Tap: tap example]
 * [:Lua/Examples/Dissector: dissector example]
 * [:Lua/Examples/PostDissector: post-dissector example]

== External Links ==

 * [http://www.onlamp.com/pub/a/onlamp/2006/02/16/introducing-lua.html Introducing Lua] at O'Reilly (onlamp.com)

== Discussion ==

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

 * How to install/use lua?
 * What's the difference between a post-dissector and a tap

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

  * I do not have yet a clear idea on how Lua will be invoked from wireshark.
     * So far as a temporary solution:
        * it either looks for ~/.wireshark/init.lua and loads that script
        * or looks for a file pointed by the environment variable WIRESHARK_LUA_INIT.
     * It will change as soon as I (or someone else, proposals are welcome) come out with a good way to do it.

  * Tap vs. Postdissector
     * a post dissector is it's like a normal dissector called every time a tree needs to be generated for a frame it just gets called at last.
     * a tap is run once after the first dissection of a packet and it has no access to the tree, it cannot add fields (a postdissector can but it will be called every time a tree needs to be generated).

        -- Luis E. G. O.

Lua

Lua's been added to wireshark 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

Wireshark is released under [http://www.gnu.org/licenses/gpl.html GPL] so every derivative work based on wireshark 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 wireshark 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 wireshark author that will not allow to distribute derivative work under different terms. To distribute Lua code that uses wireshark'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 Wireshark

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, wireshark 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 available as a plugin since wireshark 0.10.15(???) but it won't be installed by default. If you want to use it make sure you install it.

If you want to install the lua plugin:

  • *NIX: configure --with-lua=<lua_directory>

  • Windows: select the lua plugin at the setup.exe

To check if it is already installed go to Help->About Wireshark 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!")

Name this script hello.lua and place it in the current directory.

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

$ tshark -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 tshark Lua is ready to go.

/!\ Please note: this won't work with the WIN32 version of Wireshark, as the console is opened after the lua engine is loaded (or the console it not opened at all, depending on the Preferences)! XXX - We should fix this somehow!

How Lua fits into wireshark

Once the Lua plugin is installed every time wireshark starts it will search first for a script called init.lua located in the global configuration directory of wireshark. If wireshark finds this file it will run the script.

Once <global config dir>/init.lua has run that there are two variables that tell wireshark whether to continue looking for scripts.

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

If wireshark 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 run wireshark will continue running <perconal config 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

  • [:Lua/Tap: Tap]
  • [:Lua/Field: Field] a handy tool to get fileds from the tree
  • [:Lua/Proto: Proto] represents a protocol
  • [:Lua/ProtoField: ProtoField] the fields of a protocol

  • [:Lua/ProtoFieldArray: ProtoFieldArray]

  • [:Lua/Dissector: Dissector] utility class to handle dissectors
  • [:Lua/Dissector: DissectorTable] utility class to handle dissectors

  • [:Lua/Pinfo: Pinfo] current packet information
  • [:Lua/ProtoTree: ProtoTree]

  • [:Lua/ProtoTree: ProtoItem]

  • [:Lua/SubTree: SubTree] subtrees

  • [:Lua/Tvb: Tvb] access to the packet's actual bytes
  • [:Lua/ByteArray: ByteArray] utility class to manage an array of bytes

  • [:Lua/Gui: TextWindow] class that manages text-only windows.

  • [:Lua/Dumper: Dumper] class that manages writing to capture files.

Examples

  • Examples of generic Lua code can be found in [http://lua-users.org/wiki/SampleCode The Sample Code] page of Lua-Users wiki.

  • [:Lua/Examples/Tap: tap example]
  • [:Lua/Examples/Dissector: dissector example]
  • [:Lua/Examples/PostDissector: post-dissector example]

Discussion

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

  • How to install/use lua?
  • What's the difference between a post-dissector and a tap

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

  • I do not have yet a clear idea on how Lua will be invoked from wireshark.
    • So far as a temporary solution:
      • it either looks for ~/.wireshark/init.lua and loads that script
      • or looks for a file pointed by the environment variable WIRESHARK_LUA_INIT.
    • It will change as soon as I (or someone else, proposals are welcome) come out with a good way to do it.
  • Tap vs. Postdissector
    • a post dissector is it's like a normal dissector called every time a tree needs to be generated for a frame it just gets called at last.
    • a tap is run once after the first dissection of a packet and it has no access to the tree, it cannot add fields (a postdissector can but it will be called every time a tree needs to be generated).
      • -- Luis E. G. O.

Lua (last edited 2020-03-31 15:55:54 by GeraldCombs)