doc/README.tapping

   1 $Id$
   2
   3 The TAP system in Wireshark is a powerful and flexible mechanism to get event
   4 driven notification on packets matching certain protocols and/or filters.
   5 In order to use the tapping system, very little knowledge of Wireshark
   6 internals are required.
   7
   8 As examples on how to use the tap system see the implementation of
   9 tap-rpcstat.c           (tshark version)
  10 gtk/rpc_stat.c          (gtk-wireshark version)
  11
  12 If all you need is to keep some counters, there's the stats_tree API,
  13 which offers a simple way to make a GUI and tshark tap-listener; see
  14 README.stats_tree.  However, keep reading, as you'll need much of what's
  15 in this document.
  16
  17 The tap system consists of two parts:
  18 1, code in the actual dissectors to allow tapping data from that particular
  19 protocol dissector, and
  20 2, event driven code in an extension such as tap-rpcstat.c that registers
  21 a tap listener and processes received data.
  22
  23
  24
  25 So you want to hack together a tap application?
  26
  27
  28 TAP
  29 ===
  30 First you must decide which protocol you are interested in writing a tap
  31 application for and check if that protocol has already got a tap installed
  32 in it.
  33 If it already has a tap device installed then you don't have to do anything.
  34 If not, then you have to add a tap but don't worry, this is extremely easy to
  35 do and is done in four easy steps;
  36 (see packet-rpc.c and search for tap for an example)
  37
  38 1, We need tap.h so just add '#include "tap.h"' (preceded by packet.h) to
  39 the includes.
  40
  41 2, We need a tap handler so just add 'static int <protocol>_tap = -1;'
  42
  43 3, Down in proto_register_<protocol>() you need to add
  44 '<protocol>_tap = register_tap("<protocol>");'
  45
  46 4, In the actual dissector for that protocol, after any child dissectors
  47 have returned, just add 'tap_queue_packet(<protocol>_tap, pinfo, <pointer>);'
  48
  49 <pointer> is used if the tap has any special additional data to provide to the
  50 tap listeners. What this points to is dependent on the protocol that is tapped,
  51 or if there are no useful extra data to provide just specify NULL.  For
  52 packet-rpc.c what we specify there is the persistent structure 'rpc_call' which
  53 contains lots of useful information from the rpc layer that a listener might
  54 need.
  55
  56
  57
  58 TAP LISTENER
  59 ============
  60 (see tap-rpcstat.c as an example)
  61 Interfacing your application is not that much harder either.
  62 Only 3 callbacks and two functions.
  63
  64
  65 The two functions to start or stop tapping are
  66
  67 register_tap_listener(const char *tapname, void *tapdata, const char *fstring,
  68         guint flags,
  69         void (*reset)(void *tapdata),
  70         gboolean (*packet)(void *tapdata, packet_info *pinfo, epan_dissect_t *edt, const void *data),
  71         void (*draw)(void *tapdata));
  72
  73 remove_tap_listener(void *tapdata);
  74
  75
  76 remove_tap_listener(void *tapdata)
  77 This function is used to deregister and stop a tap listener.
  78
  79 register_tap_listener() is used to register an instance of a tap application
  80 to the tap system.
  81
  82 *tapname
  83 is the name of the tap we want to listen to. I.e. the name used in
  84 step 3 above.
  85
  86 *tapdata
  87 is the instance identifier. The tap system uses the value of this
  88 pointer to distinguish between different instances of a tap.
  89 Just make sure that it is unique by letting it be the pointer to a struct
  90 holding all state variables. If you want to allow multiple concurrent
  91 instances, just put ALL state variables inside a struct allocated by
  92 g_malloc() and use that pointer.
  93 (tap-rpcstat.c use this technique to allow multiple simultaneous instances)
  94
  95 *fstring
  96 is a pointer to a filter string.
  97 If this is NULL, then the tap system will provide ALL packets passing the
  98 tapped protocol to your listener.
  99 If you specify a filter string here the tap system will first try
 100 to apply this string to the packet and then only pass those packets that
 101 matched the filter to your listener.
 102 The syntax for the filter string is identical to normal display filters.
 103
 104 NOTE: Specifying filter strings will have a significant performance impact
 105 on your application and Wireshark. If possible it is MUCH better to take
 106 unfiltered data and just filter it yourself in the packet-callback than
 107 to specify a filter string.
 108 ONLY use a filter string if no other option exist.
 109
 110 flags
 111 is a set of flags for the tap listener.  The flags that can be set are:
 112
 113     TL_REQUIRES_PROTO_TREE
 114
 115         set if your tap listener "packet" routine requires a protocol
 116         tree to be built.  It will require a protocol tree to be
 117         built if either
 118
 119                 1) it looks at the protocol tree in edt->tree
 120
 121         or
 122
 123                 2) the tap-specific data passed to it is constructed only if
 124                    the protocol tree is being built.
 125
 126     TL_REQUIRES_COLUMNS
 127
 128         set if your tap listener "packet" routine requires the column
 129         strings to be constructed.
 130
 131     If no flags are needed, use TL_REQUIRES_NOTHING.
 132
 133 void (*reset)(void *tapdata)
 134 This callback is called whenever Wireshark wants to inform your
 135 listener that it is about to start [re]reading a capture file or a new capture
 136 from an interface and that your application should reset any state it has
 137 in the *tapdata instance.
 138
 139 gboolean (*packet)(void *tapdata, packet_info *pinfo, epan_dissect_t *edt, const void *data)
 140 This callback is used whenever a new packet has arrived at the tap and that
 141 it has passed the filter (if there were a filter).
 142 The *data structure type is specific to each tap.
 143 This function returns an gboolean and it should return
 144  TRUE, if the data in the packet caused state to be updated
 145        (and thus a redraw of the window would later be required)
 146  FALSE, if we don't need to redraw the window.
 147 NOTE: that (*packet) should be as fast and efficient as possible. Use this
 148 function ONLY to store data for later and do the CPU-intensive processing
 149 or GUI updates down in (*draw) instead.
 150
 151
 152 void (*draw)(void *tapdata)
 153 This callback is used when Wireshark wants your application to redraw its
 154 output. It will usually not be called unless your application has received
 155 new data through the (*packet) callback.
 156 On some ports of Wireshark (gtk2) (*draw) will be called asynchronously
 157 from a separate thread up to once every 2-3 seconds.
 158 On other ports it might only be called once when the capture is finished
 159 or the file has been [re]read completely.
 160
 161
 162
 163 So, create three callbacks:
 164 1, reset   to reset the state variables in the structure passed to it.
 165 2, packet  to update these state variables.
 166 3, draw    to take these state variables and draw them on the screen.
 167
 168 then just make Wireshark call register_tap_listener() when you want to tap
 169 and call remove_tap_listener() when you are finished.
 170
 171
 172 WHEN DO TAP LISTENERS GET CALLED?
 173 ===================================
 174 Tap listeners are only called when Wireshark reads a new capture for
 175 the first time or whenever Wireshark needs to rescan/redissect
 176 the capture.
 177 Redissection occurs when you apply a new display filter or if you
 178 change and Save/Apply a preference setting that might affect how
 179 packets are dissected.
 180 After each individual packet has been completely dissected and all
 181 dissectors have returned, all the tap listeners that have been flagged
 182 to receive tap data during the dissection of the frame will be called in
 183 sequence.
 184 The order in which the tap listeners will be called is not defined.
 185 Not until all tap listeners for the frame has been called and returned
 186 will Wireshark continue to dissect the next packet.
 187 This is why it is important to make the *_packet() callbacks execute as
 188 quickly as possible, else we create an extra delay until the next packet
 189 is dissected.
 190
 191 Keep in mind though: for some protocols, such as IP, the protocol can
 192 appear multiple times in different layers inside the same packet.
 193 For example, IP encapsulated over IP which will call the ip dissector
 194 twice for the same packet.
 195 IF the tap is going to return private data using the last parameter to
 196 tap_queue_packet() and IF the protocol can appear multiple times inside the
 197 same packet, you will have to make sure that each instance of
 198 tap_queue_packet() is using its own instance of private struct variable
 199 so they don't overwrite each other.
 200
 201 See packet-ip.c which has a simple solution to the problem. It creates
 202 a unique instance of the IP header using ep_alloc().
 203 Previous versions used a static struct of 4 instances of the IP header
 204 struct and cycled through them each time the dissector was called. (4
 205 was just a number taken out of the blue but it should be enough for most
 206 cases.) This would fail if there were more than 4 IP headers in the same
 207 packet, but that was unlikely.
 208
 209
 210 TIPS
 211 ====
 212 Of course, there is nothing that forces you to make (*draw) draw stuff
 213 on the screen.
 214 You can hand register_tap_listener() NULL for both (*draw) and (*reset)
 215 (well also for (*packet) but that would be a very boring extension).
 216
 217 Perhaps you want an extension that will execute a certain command
 218 every time it sees a certain packet?
 219 Well, try this :
 220         int packet(void *tapdata,...) {
 221                 ...
 222                 system("mail ...");
 223                 return0;
 224         }
 225
 226         register_tap_listener("tcp", struct, "tcp.port==57", NULL, packet, NULL);
 227
 228         Let struct contain an email address?
 229         Then you have something simple that will make Wireshark send an email
 230         out automagically for each and every time it dissects
 231         a packet containing TCP traffic to port 57.
 232         Please put in some rate limitation if you do this.
 233
 234         Let struct contain a command line and make (*packet) execute it?
 235         The possibilities are rather large.
 236
 237
 238
 239 See tap-rpcstat.c for an example
 240 See tap.c as well. It contains lots of comments and descriptions on the tap
 241 system.
 242
 243
 244
 245