From John Bradshaw:
[metze/wireshark/wip.git] / docbook / wsluarm.xml
1 <!-- $Id$ -->
2 <chapter id="wsluarm">
3   <title>Lua Support in Wireshark</title>
4   <section id="wsluarm_intro">
5         <title>Introduction</title>
6         <para>
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
12           <ulink url="http://www.lua.org">Lua.org</ulink>.
13           Both Tecgraf and Lua.org are laboratories of the Department of Computer Science.
14         </para>
15         <para>
16            In Wireshark Lua can be used to write dissectors and taps.
17         </para>
18         <para>
19           Wireshark's Lua interpreter starts by loading <command>init.lua</command> that
20           is located in the global configuration directory of Wireshark.
21           Lua is enabled by default.  To disable Lua the line variable <command>disable_lua</command>
22           should be set to <command>true</command> in <command>init.lua</command>.
23         </para>
24         <para>
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
27           directory.
28         </para>
29         <para>
30           Wireshark will also load all files with <command>.lua</command> suffix from both the
31           global and the personal plugins directory.
32         </para>
33         <para>
34           The command line option <command>-X lua_script:&lt;file.lua&gt;</command> can be used to
35           load Lua scripts as well.
36         </para>
37         <para>
38           The Lua code will be executed once after all the protocol dissectors have being initialized
39           and before reading any file.
40         </para>
41   </section>
42   <section id="wslua_dissector_example">
43   <title>Example of Dissector written in Lua</title>
44     <programlisting>
45 do
46         local p_multi = Proto("multi","MultiProto");
47
48         local vs_protos = {
49                 [2] = "mtp2",
50                 [3] = "mtp3",
51                 [4] = "alcap",
52                 [5] = "h248",
53                 [6] = "ranap",
54                 [7] = "rnsap",
55                 [8] = "nbap"
56         }
57
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")
61
62         p_multi.fields = { f_proto, f_dir, f_text }
63
64         local data_dis = Dissector.get("data")
65
66         local protos = {
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
77         }
78
79         function p_multi.dissector(buf,pkt,root)
80
81                 local t = root:add(p_multi,buf(0,2))
82                 t:add(f_proto,buf(0,1))
83                 t:add(f_dir,buf(1,1))
84
85                 local proto_id = buf(0,1):uint()
86
87                 local dissector = protos[proto_id]
88
89                 if dissector ~= nil then
90                         dissector:call(buf(2):tvb(),pkt,root)
91                 elseif proto_id &lt; 2 then
92                         t:add(f_text,buf(2))
93                         -- pkt.cols.info:set(buf(2,buf:len() - 3):string())
94                 else
95                         data_dis:call(buf(2):tvb(),pkt,root)
96                 end
97
98         end
99
100         local wtap_encap_table = DissectorTable.get("wtap_encap")
101         local udp_encap_table = DissectorTable.get("udp.port")
102
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)
106 end
107     </programlisting>
108   </section>
109   <section id="wslua_tap_example">
110   <title>Example of Listener written in Lua</title>
111     <programlisting>
112 -- This program will register a menu that will open a window with a count of occurrences
113 -- of every address in the capture
114
115 do
116         local function menuable_tap()
117                 -- Declare the window we will use
118                 local tw = TextWindow.new("Address Counter")
119
120                 -- This will contain a hash of counters of appearances of a certain address
121                 local ips = {}
122
123                 -- this is our tap
124                 local tap = Listener.new();
125
126                 function remove()
127                         -- this way we remove the listener than otherwise will remain running indefinitely
128                         tap:remove();
129                 end
130
131                 -- we tell the window to call the remove() function when closed
132                 tw:set_atclose(remove)
133
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
138
139                         ips[tostring(pinfo.src)] = src + 1
140                         ips[tostring(pinfo.dst)] = dst + 1
141                 end
142
143                 -- this function will be called once every few seconds to update our window
144                 function tap.draw(t)
145                         tw:clear()
146                         for ip,num in pairs(ips) do
147                                 tw:append(ip .. "\t" .. num .. "\n");
148                         end
149                 end
150
151                 -- this function will be called whenever a reset is needed
152                 -- e.g. when reloading the capture file
153                 function tap.reset()
154                         tw:clear()
155                         ips = {}
156                 end
157         end
158
159         -- using this function we register our function
160         -- to be called when the user selects the Tools->Test->Packets menu
161         register_menu("Test/Packets", menuable_tap, MENU_TOOLS)
162 end
163     </programlisting>
164   </section>
165   <section id="wsluarm_modules">
166   <title>Wireshark's Lua API Reference Manual</title>
167         <para>
168           This Part of the User Guide describes the Wireshark specific functions in the embedded Lua.
169         </para>
170   </section>
171         &WsLuaDumper;
172         &WsLuaField;
173         &WsLuaGui;
174         &WsLuaListener;
175         &WsLuaPinfo;
176         &WsLuaProto;
177         &WsLuaTree;
178         &WsLuaTvb;
179         &WsLuaUtility;
180 </chapter>