Table of Contents
Lua is a powerful light-weight programming language designed for extending applications. Wireshark contains an embedded Lua interpreter which can be used to write dissectors, taps, and capture file readers and writers. Wireshark versions 4.2.x and earlier support Lua 5.1 and 5.2, and newer versions support Lua 5.3 and 5.4. The Lua BitOp library is bundled with all version of Wireshark; Lua 5.3 and later also have native support for bitwise operators.
If Lua is enabled, Wireshark will first try to load a file named init.lua
from the global plugins directory.
and then from the user’s
personal plugins directory.
Then all files ending with .lua are loaded from the global plugins
directory and its subdirectories. Then all files ending with .lua in the
personal Lua plugins directory and its subdirectories are loaded. The
files are processed in ASCIIbetical order (compared byte-by-byte, as strcmp),
descending into each subdirectory depth-first in order.
Whether or not Lua scripts are enabled can be controlled via the enable_lua variable. Lua scripts are enabled by default. To disable Lua scripts, set the enable_lua variable to false. Wireshark 2.6 and earlier enabled or disabled Lua scripts using the variable disable_lua (deprecated). If both enable_lua and disable_lua are present, disable_lua is ignored.
Example for init.lua.
-- Set enable_lua to false to disable Lua support.
enable_lua = true
if not enable_lua then
return
end
-- If false and Wireshark was started as (setuid) root, then the user
-- will not be able to execute custom Lua scripts from the personal
-- configuration directory, the -Xlua_script command line option or
-- the Lua Evaluate menu option in the GUI.
-- Note: Not checked on Windows. running_superuser is always false.
run_user_scripts_when_superuser = true
The command line option -X lua_script:file.lua can also be used to load specific Lua scripts. Arguments can be given to a script loaded at the command line with the option -X lua_scriptN:arg, where N is the ordinal index of the script on the command line. For example, if two scripts were loaded on the command line with -X lua_script:my.lua and -X lua_script:other.lua in that order, then -X lua_script1:foo would pass foo to my.lua and -X lua_script2:bar would pass bar to other.lua. Multiple command line options could be passed to my.lua by repeating the option -X lua_script1:. Arguments are available in a script in a global table called arg, similar to when running Lua standalone.
![[Important]](images/important.svg) | Loading order matters |
|---|---|
|
Lua dissectors, unlike compiled protocol dissectors, do not have separate registration and handoff stages yet (see https://gitlab.com/wireshark/wireshark/-/issues/15907). Each Lua dissector’s registration and handoff is completed before moving to the next Lua file in turn. That means that the order in which Lua files are read is quite important; in order for a Lua dissector to register in a dissector table set up by another dissector, the latter dissector must have been already processed. The easiest way to ensure this is to put Lua dissectors that need to be registered first in files whose name is earlier in ASCIIbetical order (the name of the script does not necessarily need to relate to the name of the dissector.) The Lua code is executed after all compiled dissectors, both built-in and plugin, are initialized and before reading any file. This means that Lua dissectors can add themselves to tables registered by compiled dissectors, but not vice versa; compiled dissectors cannot add themselves to dissector tables registered by Lua dissectors. |
Wireshark for Windows uses a modified Lua runtime (lua-unicode) to support Unicode (UTF-8) filesystem paths. This brings consistency with other platforms (for example, Linux and macOS).