Chapter 12. Lua Support in Wireshark
Prev | Part II. Wireshark Development | Next

## Chapter 12. Lua Support in Wireshark

## 12.1. Introduction

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. A subdirectory in the global or personal plugin directories containing a `init.lua` is loaded as a package, where the `init.lua` file is the entry-point of the module and responsible for loading any additional submodules within its directory tree.

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.

| Loading order matters
Lua dissectors, unlike compiled protocol dissectors, do not have separate registration and handoff stages yet (see Issue 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. To align more closely with Lua conventions, Wireshark treats any directory in either the global or personal plugin directory that contains a `init.lua` file as a package, and will only load the `init.lua` script from that directory. The script is then responsible for requiring any additional dependencies, allowing for more control over the loading order within the package.

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).

Prev | Up | Next
11.5. How to plugin related interface options | Home | 12.2. Example: Creating a Menu with Lua