aboutsummaryrefslogtreecommitdiffstats
path: root/docbook/wsluarm.xml
blob: 906051932bec48461a0ed419d798e2a170f7547f (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
<!-- $Id$ -->
<chapter id="wsluarm">
  <title>Lua Support in Wireshark</title>
  <section id="wsluarm_intro">
	<title>Introduction</title>
	<para>
	  Wireshark has an embedded Lua interpreter. Lua is a powerful light-weight
	  programming language designed for extending applications. Lua is designed
	  and implemented by a team at PUC-Rio, the Pontifical Catholic University
	  of Rio de Janeiro in Brazil. Lua was born and raised at Tecgraf, the
	  Computer Graphics Technology Group of PUC-Rio, and is now housed at
	  <ulink url="http://www.lua.org">Lua.org</ulink>.
	  Both Tecgraf and Lua.org are laboratories of the Department of Computer Science.
	</para>
	<para>
	   In Wireshark Lua can be used to write dissectors and taps.
	</para>
	<para>
	  Wireshark's Lua interpreter starts by loading <command>init.lua</command> that
	  is located in the global configuration directory of Wireshark.
	  Lua is enabled by default.  To disable Lua the line variable <command>disable_lua</command>
	  should be set to <command>true</command> in <command>init.lua</command>.
	</para>
	<para>
	  After loading <command>init.lua</command> from the data directory if Lua is enabled
	  Wireshark will try to load a file named <command>init.lua</command> in the user's
	  directory.
	</para>
	<para>
	  Wireshark will also load all files with <command>.lua</command> suffix from both the
	  global and the personal plugins directory.
	</para>
	<para>
	  The command line option <command>-X lua_script:&lt;file.lua&gt;</command> can be used to
	  load Lua scripts as well.
	</para>
	<para>
	  The Lua code will be executed once after all the protocol dissectors have being initialized
	  and before reading any file.
	</para>
  </section>
  <section id="wslua_dissector_example">
  <title>Example of Dissector written in Lua</title>
    <programlisting>
do
        local p_multi = Proto("multi","MultiProto");

        local vs_protos = {
                [2] = "mtp2",
                [3] = "mtp3",
                [4] = "alcap",
                [5] = "h248",
                [6] = "ranap",
                [7] = "rnsap",
                [8] = "nbap"
        }

        local f_proto = ProtoField.uint8("multi.protocol","Protocol",base.DEC,vs_protos)
        local f_dir = ProtoField.uint8("multi.direction","Direction",base.DEC,{ [1] = "incoming", [0] = "outgoing"})
        local f_text = ProtoField.string("multi.text","Text")

        p_multi.fields = { f_proto, f_dir, f_text }

        local data_dis = Dissector.get("data")

        local protos = {
                [2] = Dissector.get("mtp2"),
                [3] = Dissector.get("mtp3"),
                [4] = Dissector.get("alcap"),
                [5] = Dissector.get("h248"),
                [6] = Dissector.get("ranap"),
                [7] = Dissector.get("rnsap"),
                [8] = Dissector.get("nbap"),
                [9] = Dissector.get("rrc"),
                [10] = DissectorTable.get("sctp.ppi"):get_dissector(3), -- m3ua
                [11] = DissectorTable.get("ip.proto"):get_dissector(132), -- sctp
        }

        function p_multi.dissector(buf,pkt,root)

                local t = root:add(p_multi,buf(0,2))
                t:add(f_proto,buf(0,1))
                t:add(f_dir,buf(1,1))

                local proto_id = buf(0,1):uint()

                local dissector = protos[proto_id]

                if dissector ~= nil then
                        dissector:call(buf(2):tvb(),pkt,root)
                elseif proto_id &lt; 2 then
                        t:add(f_text,buf(2))
                        -- pkt.cols.info:set(buf(2,buf:len() - 3):string())
                else
                        data_dis:call(buf(2):tvb(),pkt,root)
                end

        end

        local wtap_encap_table = DissectorTable.get("wtap_encap")
        local udp_encap_table = DissectorTable.get("udp.port")

        wtap_encap_table:add(wtap.USER15,p_multi)
        wtap_encap_table:add(wtap.USER12,p_multi)
        udp_encap_table:add(7555,p_multi)
end
    </programlisting>
  </section>
  <section id="wslua_tap_example">
  <title>Example of Listener written in Lua</title>
    <programlisting>
-- This program will register a menu that will open a window with a count of occurrences
-- of every address in the capture

do
	local function menuable_tap()
		-- Declare the window we will use
		local tw = TextWindow.new("Address Counter")

		-- This will contain a hash of counters of appearances of a certain address
		local ips = {}

		-- this is our tap
		local tap = Listener.new();

		function remove()
			-- this way we remove the listener that otherwise will remain running indefinitely
			tap:remove();
		end

		-- we tell the window to call the remove() function when closed
		tw:set_atclose(remove)

		-- this function will be called once for each packet
		function tap.packet(pinfo,tvb)
			local src = ips[tostring(pinfo.src)] or 0
			local dst = ips[tostring(pinfo.dst)] or 0

			ips[tostring(pinfo.src)] = src + 1
			ips[tostring(pinfo.dst)] = dst + 1
		end

		-- this function will be called once every few seconds to update our window
		function tap.draw(t)
			tw:clear()
			for ip,num in pairs(ips) do
				tw:append(ip .. "\t" .. num .. "\n");
			end
		end

		-- this function will be called whenever a reset is needed
		-- e.g. when reloading the capture file
		function tap.reset()
			tw:clear()
			ips = {}
		end
	end

	-- using this function we register our function
	-- to be called when the user selects the Tools->Test->Packets menu
	register_menu("Test/Packets", menuable_tap, MENU_TOOLS)
end
    </programlisting>
  </section>
  <section id="wsluarm_modules">
  <title>Wireshark's Lua API Reference Manual</title>
	<para>
	  This Part of the User Guide describes the Wireshark specific functions in the embedded Lua.
	</para>
  </section>
	&WsLuaDumper;
	&WsLuaField;
	&WsLuaGui;
	&WsLuaListener;
	&WsLuaPinfo;
	&WsLuaProto;
	&WsLuaTree;
	&WsLuaTvb;
	&WsLuaUtility;
</chapter>