3 <title>Lua Support in Wireshark</title>
4 <section id="wsluarm_intro">
5 <title>Introduction</title>
7 Wireshark has an embedded Lua interpreter. Lua is a powerful light-weight
8 programming language designed for extending applications. Lua is designed
9 and implemented by a team at PUC-Rio, the Pontifical Catholic University
10 of Rio de Janeiro in Brazil. Lua was born and raised at Tecgraf, the
11 Computer Graphics Technology Group of PUC-Rio, and is now housed at Lua.org.
12 Both Tecgraf and Lua.org are laboratories of the Department of Computer Science.
15 In Wireshark Lua can be used to write dissectors and taps.
18 Wireshark's Lua interpreter starts by loading <command>init.lua</command> that
19 is located in the global configuration directory of Wireshark.
20 Lua is disabled by default by setting the variable <command>disable_lua</command>
21 to true in <command>init.lua</command>. To enable lua the line that sets that variable
22 must be removed or commented out.
25 After loading <command>init.lua</command> from the data directory if lua is enabled
26 Wireshark will try to load a file named <command>init.lua</command> in the user's
30 Wireshark will also load all files with <command>.lua</command> suffix from both the
31 global and the personal plugins directory.
34 The command line option <command>-X lua_script:<file.lua></command> can be used to
35 load lua scripts as well.
38 The Lua code will be executed once after all the protocols have being initialized and before reading
42 <section id="wslua_dissector_example">
43 <title>Example of Dissector written in Lua</title>
46 local p_multi = Proto("multi","MultiProto");
58 local f_proto = ProtoField.uint8("multi.protocol","Protocol",base.DEC,vs_protos)
59 local f_dir = ProtoField.uint8("multi.direction","Direction",base.DEC,{ [1] = "incoming", [0] = "outgoing"})
60 local f_text = ProtoField.string("multi.text","Text")
62 p_multi.fields = { f_proto, f_dir, f_text }
64 local data_dis = Dissector.get("data")
67 [2] = Dissector.get("mtp2"),
68 [3] = Dissector.get("mtp3"),
69 [4] = Dissector.get("alcap"),
70 [5] = Dissector.get("h248"),
71 [6] = Dissector.get("ranap"),
72 [7] = Dissector.get("rnsap"),
73 [8] = Dissector.get("nbap"),
74 [9] = Dissector.get("rrc"),
75 [10] = DissectorTable.get("sctp.ppi"):get_dissector(3), -- m3ua
76 [11] = DissectorTable.get("ip.proto"):get_dissector(132), -- sctp
79 function p_multi.dissector(buf,pkt,root)
81 local t = root:add(p_multi,buf(0,2))
82 t:add(f_proto,buf(0,1))
85 local proto_id = buf(0,1):uint()
87 local dissector = protos[proto_id]
89 if dissector ~= nil then
90 dissector:call(buf(2):tvb(),pkt,root)
91 elseif proto_id < 2 then
93 -- pkt.cols.info:set(buf(2,buf:len() - 3):string())
95 data_dis:call(buf(2):tvb(),pkt,root)
100 local wtap_encap_table = DissectorTable.get("wtap_encap")
101 local udp_encap_table = DissectorTable.get("udp.port")
103 wtap_encap_table:add(wtap.USER15,p_multi)
104 wtap_encap_table:add(wtap.USER12,p_multi)
105 udp_encap_table:add(7555,p_multi)
109 <section id="wslua_tap_example">
110 <title>Example of Listener written in Lua</title>
112 -- This program will register a menu that will open a window with a count of occurrences
113 -- of every address in the capture
116 local function menuable_tap()
117 -- Declare the window we will use
118 local tw = TextWindow.new("Address Counter")
120 -- This will contain a hash of counters of appearances of a certain address
124 local tap = Listener.new();
127 -- this way we remove the listener than otherwise will remain running indifinitelly
131 -- we tell the window to call the remove() function when closed
132 tw:set_atclose(remove)
134 -- this function will be called once for each packet
135 function tap.packet(pinfo,tvb)
136 local src = ips[tostring(pinfo.src)] or 0
137 local dst = ips[tostring(pinfo.dst)] or 0
139 ips[tostring(pinfo.src)] = src + 1
140 ips[tostring(pinfo.dst)] = dst + 1
143 -- this function will be called once every few seconds to update our window
146 for ip,num in pairs(ips) do
147 tw:append(ip .. "\t" .. num .. "\n");
151 -- this function will be called whenever a reset is needed
152 -- e.g. when reloading the capture file
159 -- using this function we register our fuction
160 -- to be called when the user selects the Tools->Test->Packets menu
161 register_menu("Test/Packets", menuable_tap, MENU_TOOLS)
165 <section id="wsluarm_modules">
166 <title>Wireshark's Lua API Reference Manual</title>
168 This Part of the User Guide describes the Wireshark specific functions in the embedded Lua.