Tutorial: Plugin end report

When all data is processed or T2 is interrupted by ^C or a signal, then the end report is printed. Before we start doing this, clean out your plugin .so directory if this is the first tutorial you follow. Then all unnecessary plugins should be deleted from the plugin folder ~/.tranalyzer/plugins. We do not need flow output, so no sink plugin is needed.

$ t2build -e
Are you sure you want to empty the plugin folder '/home/wurst/.tranalyzer/plugins' (y/N)? y
Plugin folder emptied
$ t2build tranalyzer2
...
$

If you didn’t read the tutorials before, here is the basis plugin which we will extend: tcpWin

The anonymized sample pcap can be downloaded here: annoloc2.pcap. Please extract it under your data folder: ~/data, if you haven’t already. Now you are all set for end report programming.

Implementing the end report

If your plugin wants to contribute to the end report, then global variables and a pluginReport(FILE *stream) callback have to be added. So open tcpWin.c in an editor and add two global variables after the tcpWinFlows definition. Look for the <-- markers.

In the L4 packet interrupt increment the TCP packet counter, look for the <-- comment.

Then add in the onFlowTerminate(...) callback the lines marked by <-- to aggregate stat and winThCnt of all flows.

Implementing the pluginReport(FILE *stream) callback

Now add the pluginReport(FILE *stream) callback e.g. after onFlowTerminate(). There we print the status and the aggregated winThCnt. Note, that the core can be configured to display hex numbers small or capital. To be consistent with that option, you should use B2T_PRIX8 instead of the normal PRIx8 or %02x constant. So you do not need to worry about these nitty-gritty things anymore. Important for you in the function T2_FPLOG is the name of your plugin: tcpWin, so you can identify your output in the end report, then the C format of your output, and the variables, actually like a normal printf.

Recompile tcpWin and execute T2

$ t2build tcpWin
...
$ t2 -r ~/data/annoloc2.pcap
================================================================================
Tranalyzer 0.8.11 (Anteater), Tarantula. PID: 17582
================================================================================
[INF] Creating flows for L2, IPv4, IPv6
Active plugins:
    01: tcpWin, 0.8.11
[INF] IPv4 Ver: 5, Rev: 16122020, Range Mode: 0, subnet ranges loaded: 406208 (406.21 K)
[INF] IPv6 Ver: 5, Rev: 17122020, Range Mode: 0, subnet ranges loaded: 51196 (51.20 K)
Processing file: /home/wurst/data/annoloc2.pcap
Link layer type: Ethernet [EN10MB/1]
Dump start: 1022171701.691172 sec (Thu 23 May 2002 16:35:01 GMT)
[WRN] snapL2Length: 54 - snapL3Length: 40 - IP length in header: 1500
Dump stop : 1022171726.640398 sec (Thu 23 May 2002 16:35:26 GMT)
Total dump duration: 24.949226 sec
Finished processing. Elapsed time: 0.392854 sec
Finished unloading flow memory. Time: 0.396208 sec
Percentage completed: 100.00%
Number of processed packets: 1219015 (1.22 M)
Number of processed bytes: 64082726 (64.08 M)
Number of raw bytes: 844642686 (844.64 M)
Number of pad bytes: 8591685635 (8.59 G)
Number of pcap bytes: 83586990 (83.59 M)
Number of IPv4 packets: 1218608 (1.22 M) [99.97%]
Number of IPv6 packets: 160 [0.01%]
Number of A packets: 564227 (564.23 K) [46.29%]
Number of B packets: 654788 (654.79 K) [53.71%]
Number of A bytes: 29447862 (29.45 M) [45.95%]
Number of B bytes: 34634864 (34.63 M) [54.05%]
Average A packet load: 52.19
Average B packet load: 52.89
--------------------------------------------------------------------------------
tcpWin: Aggregated tcpWinStat=0x01
tcpWin: Number of TCP winsize packets below threshold 1: 2415 [0.25%]
--------------------------------------------------------------------------------
...
$

As we didn’t load a sink plugin, now flows are produced, although the buffers are filled. If you do not want that to happen try: t2conf tranalyzer2 -D BLOPCK_BUF=1 && t2build -R. Then all plugins stop filling the flow output buffers.

You will notice your end report output starting with tcpWin. Wasn’t so difficult, right?

Now try the T2_FPLOG_NUMP function, which produces a more comprehensive output. The normalization factor must be supplied as a second variable. Just add the <-- marked line in the pluginReport(...) callback.

Recompile tcpWin and execute T2

$ t2build tcpWin
...
$ t2 -r ~/data/annoloc2.pcap
...
--------------------------------------------------------------------------------
tcpWin: Aggregated tcpWinStat=0x01
tcpWin: Number of TCP winsize packets below threshold 1: 2415 [0.25%]
tcpWin: Number of TCP winsize packets below threshold: 2415 (2.42 K) [0.25%]
--------------------------------------------------------------------------------
...
$

Note that large numbers are now better conceivable. You can add any output you want by adding more T2_FPLOG macros

Have fun writing plugins!

The next tutorial will teach you how to add plugin monitoring report

See Also