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 27 and 55 (spanning 28 versions)
Revision 27 as of 2006-03-16 20:37:15
Size: 7366
Editor: UlfLamping
Comment: name the script dirs after they are named in the about folder tabs
Revision 55 as of 2020-03-31 15:55:54
Size: 6738
Editor: GeraldCombs
Comment: Remove a no-longer-relevant link.
Deletions are marked like this. Additions are marked like this.
Line 3: Line 3:
Line 4: Line 5:
 ||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 ethereal as a language for prototyping and scripting.
Line 8: Line 6:
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]. || {{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]]. ||
Line 10: Line 8:
== 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.
Line 13: Line 9:
/!\ 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 /!\ Lua's been added to Wireshark as a language for prototyping and scripting.
Line 15: Line 11:
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. 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/pil|book]] that describes the language. There is also [[http://lua-users.org/wiki/|The lua-users wiki]].
Line 17: Line 13:
If it isn't clear to you what the GPL is and how it works please consult your laywer. <<TableOfContents()>>
Line 19: Line 15:
== 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.
== 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 lawyer.

== 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.
Line 26: Line 31:
[:Lua/Taps: Taps] are used to collect information after the packet has been dissected. [[/Taps]] are used to collect information after the packet has been dissected.
Line 29: Line 34:
Lua is available as a plugin since ethereal 0.10.15(???) but it won't be installed by default. If you want to use it make sure you install it. Lua has shipped with the Windows version of Wireshark since 0.99.4. Availability on other platforms varies. To see if your version of Wireshark supports Lua, go to ''Help→About Wireshark'' and look for Lua in the "Compiled with" paragraph.
Line 31: Line 36:
If you want to install the lua plugin: {{attachment:lua-about.png}}
Line 33: Line 38:
 * *NIX: {{{configure --with-lua=<lua_directory>}}}
 * Windows: select the lua plugin at the {{{setup.exe}}}
In some older versions Lua was available as a plugin.
Line 36: Line 40:
To check if it is already installed go to {{{Help->About Ethereal}}} go to the {{{Plugins}}} tab and look for it. To test Lua on your system, do the following:
Line 38: Line 42:
attachment:about.png  1. Make sure Lua is enabled in the global configuration as described below in '''How Lua Fits Into Wireshark'''
Line 40: Line 44:
To test if it works write a simple Lua script like:
{{{
-- hello.lua
-- Lua's implementation of D. Ritchie's hello world program.
 1. Create a simple Lua script such as:
 {{{
 -- hello.lua
 -- Lua's implementation of D. Ritchie's hello world program.
Line 48: Line 51:
Name this script {{{hello.lua}}} and place it in the current directory.  1. Name this script {{{hello.lua}}} and place it in the current directory.
Line 50: Line 53:
run {{{tethereal -X lua_script:hello.lua}}} from the command prompt and you 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>
 1. Run {{{tshark -X lua_script:hello.lua}}} from the command prompt. 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>
Line 58: Line 61:
If you can read "hello world!" in the first line after you run tethereal Lua is ready to go. If you can read "hello world!" in the first line after you run tshark Lua is ready to go!
Line 60: Line 63:
/!\ Please note: this won't work with the WIN32 version of Ethereal, 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! /!\ Please note: On Windows, you may not see any output when running Lua scripts in Wireshark. If the console window is enabled it will be opened '''after''' the Lua engine is loaded. This does not affect TShark, since it is a console program.
Line 62: Line 65:
== How Lua fits into ethereal ==
Once the Lua plugin is installed every time ethereal starts it will search first for a script called init.lua located in the global configuration directory of ethereal. If ethereal finds this file it will run the script.
== How Lua fits into Wireshark ==
Every time wireshark starts it will search for a script called `init.lua` located in the global configuration directory of Wireshark. If Wireshark finds this file it will run the script.
Line 65: Line 68:
Once ''<global config dir>''/init.lua has run that there are two variables that tell ethereal whether to continue looking for scripts.  Once ''<global configuration directory>''`/init.lua` has run that there are two variables that tell wireshark whether to continue looking for scripts.
Line 67: Line 70:
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 run. 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.
Line 69: Line 72:
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 run Wireshark will search the global plugin directory directory for files ending in `.lua` and run them as scripts.
Line 71: Line 74:
Once this first script was run ethereal 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. 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. Otherwise, after that, it will run the `init.lua` script in your personal configuration directory, if it exists, and then search your personal plugin directory for files ending in `.lua` and run them as scripts, and then will run all scripts passed with the '''-X lua_script:'''''xxx.lua'' command line option in the given order.
Line 75: Line 78:
The location of the directories containing these scripts are different on different platforms. See [[https://www.wireshark.org/docs/wsug_html/#AppFiles|Appendix B, "Files and Folders"]] of the Wireshark User's Guide for the location of those directories.
Line 76: Line 80:
== Classes == == Wireshark's Lua API ==
Line 78: Line 82:
 * [: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.
Wireshark’s Lua API Reference Manual can be found [[https://www.wireshark.org/docs/wsdg_html_chunked/wsluarm.html|here]]. Changes to the API can be found [[Lua/ApiChanges|here]].
Line 101: Line 85:
 Examples of generic Lua code can be found in [http://lua-users.org/wiki/SampleCode The Sample Code] page of Lua-Users wiki. Examples of generic Lua code can be found in [[http://lua-users.org/wiki/SampleCode|The Sample Code]] page of Lua-Users wiki.
Line 103: Line 87:
 * [:Lua/Examples/Tap: tap example]
 * [:Lua/Examples/Dissector: dissector example]
 * [:Lua/Examples/PostDissector: post-dissector example]
Examples of wireshark and tshark specific scripts can be found in [[Lua/Examples|the Lua examples wiki page]], as well as on the [[Contrib|Contrib repository wiki page]].
Line 108: Line 90:

 * [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 ethereal.
     * So far as a temporary solution:
        * it either looks for ~/.ethereal/init.lua and loads that script
        * or looks for a file pointed by the environment variable ETHEREAL_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.
 * [[http://www.onlamp.com/pub/a/onlamp/2006/02/16/introducing-lua.html|Introducing Lua]] at O'Reilly (onlamp.com)
 * [[https://studio.zerobrane.com/|ZeroBrane Studio]] Lightweight IDE for your Lua needs
 * [[https://github.com/MarkoPaul0/WireBait|WireBait]] Lua library to facilitate the development of Wireshark dissectors by enabling users to run them against packet data without Wireshark. The packet data can come from hexadecimal string or a .pcap file. The goal here is to provide a tool reducing development time when creating a new dissector.

Lua

lua_logo.gif

Lua is a powerful light-weight programming language designed for extending applications. Lua is designed and implemented by a team at PUC-Rio, the Pontifical Catholic University of Rio de Janeiro in Brazil. Lua was born and raised at Tecgraf, the Computer Graphics Technology Group of PUC-Rio, and is now housed at Lua.org. Both Tecgraf and Lua.org are laboratories of the Department of Computer Science.

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

For more information about Lua refer to Lua's main site, there you can find its Reference Manual and a book that describes the language. There is also The lua-users wiki.

Beware the GPL

Wireshark is released under 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 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 lawyer.

Lua in Wireshark

Lua can be used to write dissectors, post-dissectors and taps.

Although it's possible to write 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.

/Taps are used to collect information after the packet has been dissected.

Getting Started

Lua has shipped with the Windows version of Wireshark since 0.99.4. Availability on other platforms varies. To see if your version of Wireshark supports Lua, go to Help→About Wireshark and look for Lua in the "Compiled with" paragraph.

lua-about.png

In some older versions Lua was available as a plugin.

To test Lua on your system, do the following:

  1. Make sure Lua is enabled in the global configuration as described below in How Lua Fits Into Wireshark

  2. Create a simple Lua script such as:
     -- hello.lua
     -- Lua's implementation of D. Ritchie's hello world program.
        print("hello world!")
  3. Name this script hello.lua and place it in the current directory.

  4. Run tshark -X lua_script:hello.lua from the command prompt. 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: On Windows, you may not see any output when running Lua scripts in Wireshark. If the console window is enabled it will be opened after the Lua engine is loaded. This does not affect TShark, since it is a console program.

How Lua fits into Wireshark

Every time wireshark starts it will search 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 configuration directory>/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.

Once this first script was run Wireshark will search the global plugin directory directory for files ending in .lua and run them as scripts.

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. Otherwise, after that, it will run the init.lua script in your personal configuration directory, if it exists, and then search your personal plugin directory for files ending in .lua and run them as scripts, and then will run 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.

The location of the directories containing these scripts are different on different platforms. See Appendix B, "Files and Folders" of the Wireshark User's Guide for the location of those directories.

Wireshark's Lua API

Wireshark’s Lua API Reference Manual can be found here. Changes to the API can be found here.

Examples

Examples of generic Lua code can be found in The Sample Code page of Lua-Users wiki.

Examples of wireshark and tshark specific scripts can be found in the Lua examples wiki page, as well as on the Contrib repository wiki page.

  • Introducing Lua at O'Reilly (onlamp.com)

  • ZeroBrane Studio Lightweight IDE for your Lua needs

  • WireBait Lua library to facilitate the development of Wireshark dissectors by enabling users to run them against packet data without Wireshark. The packet data can come from hexadecimal string or a .pcap file. The goal here is to provide a tool reducing development time when creating a new dissector.

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