9.6. How to tap protocols
Prev | Chapter 9. Packet Dissection | Next

## 9.6. How to tap protocols

Adding a Tap interface to a protocol allows it to do some useful things. In particular you can produce protocol statistics from the tap interface.

A tap is basically a way of allowing other items to see what’s happening as a protocol is dissected. A tap is registered with the main program, and then called on each dissection. Some arbitrary protocol specific data is provided with the routine that can be used.

To create a tap, you first need to register a tap. A tap is registered with an integer handle, and registered with the routine `register_tap()`. This takes a string name with which to find it again.

Initialising a tap.

    #include <epan/packet.h>
    #include <epan/tap.h>

    static int foo_tap;

    void proto_register_foo(void)
    {
           ...
        foo_tap = register_tap("foo");

Whilst you can program a tap without protocol specific data, it is generally not very useful. Therefore it’s a good idea to declare a structure that can be passed through the tap. This needs to be allocated in packet scope as it will be used after the dissection routine has returned. It’s generally best to pick out some generic parts of the protocol you are dissecting into the tap data. A packet type, a priority or a status code maybe. The structure really needs to be included in a header file so that it can be included by other components that want to listen in to the tap.

Once you have these defined, it’s simply a case of populating the protocol specific structure and then calling `tap_queue_packet`, probably as the last part of the dissector.

Calling a protocol tap.

    struct FooTap {
        int packet_type;
        int priority;
           ...
    };

    static int
    dissect_foo(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree, void *data _U_)
    {
           ...
        struct FooTap *fooinfo = wmem_new0(pinfo->pool, struct FooTap);
        fooinfo->packet_type = tvb_get_uint8(tvb, 0);
        fooinfo->priority = tvb_get_ntohs(tvb, 8);
           ...
        tap_queue_packet(foo_tap, pinfo, fooinfo);

        return tvb_captured_length(tvb);
    }

| Tip
Allocate your structure using `wmem_new0()`, so it sets all values of your structure to zero. This way, if you add members later but forget to initialize them, they will have a consistent value, making troubleshooting easier.

This now enables those interested parties to listen in on the details of this protocol conversation.

### 9.6.1. How to produce protocol statistics (stats)

Given that you have a tap interface for the protocol, you can use this to produce some interesting statistics (well presumably interesting!) from protocol traces.

This can be done in a separate plugin, or in the same plugin that is doing the dissection. The latter scheme is better, as the tap and stats module typically rely on sharing protocol specific data, which might get out of step between two different plugins.

Here is a mechanism to produce statistics from the above TAP interface.

Initialising a stats interface.

    #include <epan/stats_tree.h>

    void proto_reg_handoff_foo(void) {
           ...
        stats_tree_register("foo", "foo", "Foo" STATS_TREE_MENU_SEPARATOR "Packet Types", 0,
            foo_stats_tree_packet, foo_stats_tree_init, NULL);
    }

The interface entry point, `proto_reg_handoff_foo()`, calls the `stats_tree_register()` function, which takes three strings, an integer, and three callback functions:

1. This is the tap name that was registered using `register_tap()`.
2. An abbreviation of the stats name.
3. The name of the stats module. `STATS_TREE_MENU_SEPARATOR` can be used to make sub menus.
4. Flags for per-packet callback, taken from `epan/stats_tree.h`.
5. The function that will called to generate the stats.
6. A function that can be called to initialise the stats data.
7. A function that will be called to clean up the stats data.

In this case we only need the first two functions, as there is nothing specific to clean up.

| Note
If you are registering statistics from a plugin, then your plugin should have a plugin interface entry point called `plugin_register_tap_listener()`, which should call `stats_tree_register_plugin()` instead of `stats_tree_register()`.

Initialising a stats session.

    static const uint8_t* st_str_packets = "Total Packets";
    static const uint8_t* st_str_packet_types = "FOO Packet Types";
    static int st_node_packets = -1;
    static int st_node_packet_types = -1;

    static void foo_stats_tree_init(stats_tree* st)
    {
        st_node_packets = stats_tree_create_node(st, st_str_packets, 0, STAT_DT_INT, true);
        st_node_packet_types = stats_tree_create_pivot(st, st_str_packet_types, st_node_packets);
    }

In this case we create a new tree node, to handle the total packets, and as a child of that we create a pivot table to handle the stats about different packet types.

Generating the stats.

    static tap_packet_status foo_stats_tree_packet(stats_tree* st, packet_info* pinfo, epan_dissect_t* edt, const void* p, tap_flags_t flags)
    {
        struct FooTap *pi = (struct FooTap *)p;
        tick_stat_node(st, st_str_packets, 0, false);
        stats_tree_tick_pivot(st, st_node_packet_types,
                val_to_str(pinfo->pool, pi->packet_type, packettypenames, "Unknown packet type (%d)"));
        return TAP_PACKET_REDRAW;
    }

In this case the processing of the stats is quite simple. First we call the `tick_stat_node` for the `st_str_packets` packet node, to count packets. Then a call to `stats_tree_tick_pivot()` on the `st_node_packet_types` subtree allows us to record statistics by packet type.

| Note
Notice that stats trees and pivots are identified by their name string, not by the identifier returned by `stats_tree_create_node()`/`stats_tree_create_pivot()`.

### 9.6.2. How to follow protocol streams

Now that you’re familiar with how taps work, you can also use them to allow your dissector to follow streams, if your protocol has that concept, using the Analyze → Follow menu or `tshark -z follow`.

| Note
You cannot re-use a previously defined tap for this purpose. You will need to define a separate tap.

Registering a follow tap.

    #include <epan/packet.h>
    #include <epan/tap.h>
    #include <epan/follow.h>

    static int foo_follow_tap;

    static int
    dissect_foo(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree, void *data _U_)
    {
           ...
        /* We only tap the packet if we're being asked to. */
        if (have_tap_listener(foo_follow_tap)) {

            /* For a follow tap, the userdata argument is
            * the tvbuff containing your protocol's payload data.
            * That may *not* be the entire tvbuff, as it is here.
            */
            tap_queue_packet(foo_follow_tap, pinfo, tvb);
        }

        return tvb_captured_length(tvb);
    }

    void proto_register_foo(void)
    {
           ...
        foo_follow_tap = register_tap("foo_follow");
        register_follow_stream(proto_foo, "foo_follow",
                foo_follow_conv_filter,
                foo_follow_index_filter,
                foo_follow_address_filter,
                foo_port_to_display,
                foo_follow_tap_listener,
                get_foo_stream_count,
                foo_get_substream_id);

The arguments to `register_follow_stream()` are an integer, a string, and several callback functions:

1. The integer protocol identifier returned from `proto_register_protocol()`.
2. The string name of your dedicated follow tap.
3. A callback function which will return a display filter string. The filter should follow a stream based on the conversation that the current packet belongs to.
4. A callback function which will return a display filter string. The filter should follow a stream based on its stream index, if your protocol has such a concept.
5. A callback function which will return a display filter string. The filter should follow a stream based on its address/port pairs.
6. A callback function that will take a port number and resolve it to a string identifying the service, or else return the port as a string.
7. A callback function that will handle reading the tvbuff information provided by the tap when it is called.
8. A callback function that will return the total number of unique streams of your protocol in the current capture file. May be `NULL`.
9. A callback function that will identify whether the current packet contains a substream of your protocol, if it has such a concept. May be `NULL`.

If your protocol is carried over TCP or UDP, and its streams can be found using IP addresses and ports, then you may be able to use some or all of the standard callback functions defined for this purpose:

Table 9.1. Standard callbacks for following streams

Argument | TCP Function | UDP Function
--- | --- | ---
3 | `tcp_follow_conv_filter` | `udp_follow_conv_filter`
4 | `tcp_follow_index_filter` | `udp_follow_index_filter`
5 | `tcp_follow_address_filter` | `udp_follow_address_filter`
6 | `tcp_port_to_display` | `udp_port_to_display`
7 | `follow_tvb_tap_listener` | `follow_tvb_tap_listener`
8 | `get_tcp_stream_count` | `get_udp_stream_count`
9 | `NULL` | `NULL`

If your protocol is not carried over TCP or UDP, or if you have more complex needs than these functions can provide, you can create your own callbacks. Refer to the above functions in the source code to see their arguments, return types, and what they do.

Prev | Up | Next
9.5. How to reassemble split packets | Home | 9.7. How to use conversations