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 Lua.org.
  12           Both Tecgraf and Lua.org are laboratories of the Department of Computer Science.
  13         </para>
  14         <para>
  15            In Wireshark Lua can be used to write dissectors and taps.
  16         </para>
  17         <para>
  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.
  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           The command line option <command>-X lua_script:&lt;file.lua&gt;</command> can be used to
  31           load lua scripts as well.
  32         </para>
  33         <para>
  34           The Lua code will be executed once after all the protocols have being initialized and before reading
  35           any file.
  36         </para>
  37   </section>
  38   <section id="wslua_dissector_example">
  39   <title>Example of Dissector written in Lua</title>
  40     <programlisting>
  41 do
  42         local p_multi = Proto("multi","MultiProto");
  43
  44         local vs_protos = {
  45                 [2] = "mtp2",
  46                 [3] = "mtp3",
  47                 [4] = "alcap",
  48                 [5] = "h248",
  49                 [6] = "ranap",
  50                 [7] = "rnsap",
  51                 [8] = "nbap"
  52         }
  53
  54         local f_proto = ProtoField.uint8("multi.protocol","Protocol",base.DEC,vs_protos)
  55         local f_dir = ProtoField.uint8("multi.direction","Direction",base.DEC,{ [1] = "incoming", [0] = "outgoing"})
  56         local f_text = ProtoField.string("multi.text","Text")
  57
  58         p_multi.fields = { f_proto, f_dir, f_text }
  59
  60         local data_dis = Dissector.get("data")
  61
  62         local protos = {
  63                 [2] = Dissector.get("mtp2"),
  64                 [3] = Dissector.get("mtp3"),
  65                 [4] = Dissector.get("alcap"),
  66                 [5] = Dissector.get("h248"),
  67                 [6] = Dissector.get("ranap"),
  68                 [7] = Dissector.get("rnsap"),
  69                 [8] = Dissector.get("nbap"),
  70                 [9] = Dissector.get("rrc"),
  71                 [10] = DissectorTable.get("sctp.ppi"):get_dissector(3), -- m3ua
  72                 [11] = DissectorTable.get("ip.proto"):get_dissector(132), -- sctp
  73         }
  74
  75         function p_multi.dissector(buf,pkt,root)
  76
  77                 local t = root:add(p_multi,buf(0,2))
  78                 t:add(f_proto,buf(0,1))
  79                 t:add(f_dir,buf(1,1))
  80
  81                 local proto_id = buf(0,1):uint()
  82
  83                 local dissector = protos[proto_id]
  84
  85                 if dissector ~= nil then
  86                         dissector:call(buf(2):tvb(),pkt,root)
  87                 elseif proto_id &lt; 2 then
  88                         t:add(f_text,buf(2))
  89                         -- pkt.cols.info:set(buf(2,buf:len() - 3):string())
  90                 else
  91                         data_dis:call(buf(2):tvb(),pkt,root)
  92                 end
  93
  94         end
  95
  96         local wtap_encap_table = DissectorTable.get("wtap_encap")
  97         local udp_encap_table = DissectorTable.get("udp.port")
  98
  99         wtap_encap_table:add(wtap.USER15,p_multi)
 100         wtap_encap_table:add(wtap.USER12,p_multi)
 101         udp_encap_table:add(7555,p_multi)
 102 end
 103         </programlisting>
 104   </section>
 105   <section id="wslua_tap_example">
 106   <title>Example of Listener written in Lua</title>
 107     <programlisting>
 108 -- This program will register a menu that will open a window with a count of occurrences
 109 -- of every address in the capture
 110
 111 do
 112         local function menuable_tap()
 113                 -- Declare the window we will use
 114                 local tw = TextWindow.new("Address Counter")
 115
 116                 -- This will contain a hash of counters of appereances of a certain address
 117                 local ips = {}
 118
 119                 -- this is our tap
 120                 local tap = Listener.new();
 121
 122                 function remove()
 123                         -- this way we remove the listener than otherwise will remain running indifinitelly
 124                         tap:remove();
 125                 end
 126
 127                 -- we tell the window to call the remove() function when closed
 128                 tw:set_atclose(remove)
 129
 130                 -- this function will be called once for each packet
 131                 function tap.packet(pinfo,tvb)
 132                         local src = ips[tostring(pinfo.src)] or 0
 133                         local dst = ips[tostring(pinfo.dst)] or 0
 134
 135                         ips[tostring(pinfo.src)] = src + 1
 136                         ips[tostring(pinfo.dst)] = dst + 1
 137                 end
 138
 139                 -- this function will be called once every few seconds to update our window
 140                 function tap.draw(t)
 141                         tw:clear()
 142                         for ip,num in pairs(ips) do
 143                                 tw:append(ip .. "\t" .. num .. "\n");
 144                         end
 145                 end
 146
 147                 -- this function will be called whenever a reset is needed
 148                 -- e.g. when reloading the capture file
 149                 function tap.reset()
 150                         tw:clear()
 151                         ips = {}
 152                 end
 153         end
 154
 155         -- using this function we register our fuction
 156         -- to be called when the user selects the Tools->Test->Packets menu
 157         register_menu("Test/Packets", menuable_tap, MENU_TOOLS)
 158 end
 159         </programlisting>
 160   </section>
 161   <section id="wsluarm_modules">
 162   <title>Wireshark's Lua API Reference Manual</title>
 163     <para>
 164       This Part of the User Guide describes the Wireshark specific functions in the embedded Lua.
 165         </para>
 166     &WsLuaDumper;
 167     &WsLuaField;
 168     &WsLuaGui;
 169         &WsLuaListener;
 170         &WsLuaPinfo;
 171         &WsLuaProto;
 172         &WsLuaTree;
 173         &WsLuaTvb;
 174         &WsLuaUtility;
 175   </section>
 176 </chapter>