Changes between Initial Version and Version 1 of WirelessTraces

03/06/07 12:31:27 (14 years ago)



  • WirelessTraces

    v1 v1  
     1= Libtrace Wireless Support =
     2Libtrace3 contains functions that allow easy access to wireless metadata attached to frames in wireless traces. For example, a trace taken from a [ MadWiFi] based monitor mode VAP can have Radiotap or Prism headers prepended to each IEEE802.11 frame. These headers include information such as bitrate, signal strength, etc, for each packet. Libtrace's wireless support allows access to this information in a consistent manner, no matter what frame encapsulation is used.
     4'''Note, as of libtrace 3.0, only Radiotap encapsulation is supported.'''
     6== General API ==
     7The complete wireless API can be found [ here]. We will give a brief overview and example of its usage below.
     9All wireless functions are named `trace_get_wireless_*`, where * is the wireless metadata that you are interested in. Each of the functions returns a bool which indicates whether the requested metadata could be found in the packet. Each function takes a void pointer to the start of the metadata header (usually obtained by `trace_get_link(pkt)`), a linktype to indicate the type of encapsulation (usually obtained by `trace_get_link_type(pkt)`), and an address to store the resulting metadata.
     11=== Trace Processing Example ===
     12For example, assume we want to retrieve the signal strength in dBm for each packet in our trace:
     14while (trace_read_packet(trace, pkt) > 0)
     16    int8_t signal;
     17    trace_get_wireless_signal_strength_dbm(trace_get_link(pkt), trace_get_link_type(pkt), &signal);
     18    printf("%i dBm\n", signal);
     21Note that in this code we have not specified what encapsulation is used. The `trace_get_wireless_*` methods will skip Linux SLL headers automatically and figure out how to obtain the metadata. Note that if the packet does not contain the requested metadata, the `trace_get_wireless_*` functions will return false, and the value in the output parameter is undefined.
     23== Capturing Traces with Wireless Metadata ==
     24As an aside, we will explain how to capture traces that include useful metadata suitable for use in Libtrace. The example given below is based on [ MadWiFi] version 0.9.3, however the same principles apply to other wireless drivers. The only pre-requisite is that a driver be capable of prepending a supported wireless metadata format to frames. Also note that as of Libtrace 3.0, the wireless support is limited to Radiotap encapsulation, though Prism AVS is planned (though it appears that Prism support is to be deprecated in upcoming Linux kernels in favour of the more extensible Radiotap).
     26=== Setting up !MadWiFi for Radiotap ===
     27Create a new Monitor mode VAP:
     29{{{wlanconfig mon0 create wlandev wifi0 wlanmode mon}}} (where mon0 is the name of the monitor mode vap, and wifi0 is the name of the !MadWiFi base device)
     31Enable Radiotap encapsulation:
     33{{{echo '803' > /proc/sys/net/mon0/dev_type}}}
     35Capture packets using either `tcpdump -w` or `tracesplit`, e.g.
     37{{{tracesplit int:mon0 pcapfile:trace.pcap}}}
     39You can then open the trace `trace.pcap` with your libtrace application and use the `trace_get_wireless_*` methods to extract per-packet metadata.