File: c61.html

package info (click to toggle)
libpcapnav 0.8-2
links: PTS
area: main
in suites: jessie, jessie-kfreebsd
size: 1,968 kB
ctags: 207
sloc: sh: 8,869; ansic: 1,849; makefile: 221
file content (845 lines) | stat: -rw-r--r-- 16,008 bytes
parent folder | download | duplicates (2)
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML
><HEAD
><TITLE
>Using libpcapnav</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK
REL="HOME"
TITLE="libpcapnav Manual"
HREF="index.html"><LINK
REL="PREVIOUS"
TITLE="Introduction"
HREF="c17.html"><LINK
REL="NEXT"
TITLE="libpcapnav API Reference"
HREF="api.html"><LINK
REL="STYLESHEET"
TYPE="text/css"
HREF="stylesheet.css"></HEAD
><BODY
CLASS="CHAPTER"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
><CODE
CLASS="FUNCTION"
>libpcapnav</CODE
> Manual</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="c17.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="api.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="CHAPTER"
><H1
><A
NAME="AEN61"
></A
>Using <CODE
CLASS="FUNCTION"
>libpcapnav</CODE
></H1
><DIV
CLASS="TOC"
><DL
><DT
><B
>Table of Contents</B
></DT
><DT
><A
HREF="c61.html#AEN74"
>Using <TT
CLASS="FILENAME"
>pcapnav-config</TT
> in
	  <TT
CLASS="FILENAME"
>configure</TT
> scripts</A
></DT
><DT
><A
HREF="c61.html#AEN83"
><CODE
CLASS="FUNCTION"
>libpcapnav</CODE
> code examples</A
></DT
><DT
><A
HREF="c61.html#AEN137"
>Controlling debugging output at runtime</A
></DT
><DT
><A
HREF="c61.html#AEN152"
>Using <CODE
CLASS="FUNCTION"
>libpcapnav</CODE
> to append packets to existing traces</A
></DT
></DL
></DIV
><P
>        In case you are used to using <CODE
CLASS="FUNCTION"
>libpcap</CODE
>, handling <CODE
CLASS="FUNCTION"
>libpcapnav</CODE
> will be
        trivial. The API is intentionally just a minimal wrapper around
        <CODE
CLASS="FUNCTION"
>libpcap</CODE
> calls, with a few extra functions to perform the trace file
        navigation. Essentially, wherever you said "pcap" before, you
        now say "pcapnav". This chapter will walk you through an example
        that demonstrates how to open a trace file, navigate to specific
        points in the file, and read &amp; write packets.
      </P
><DIV
CLASS="NOTE"
><P
></P
><TABLE
CLASS="NOTE"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="images/note.gif"
HSPACE="5"
ALT="Note"></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>        To make it easier to configure your software package to use
        <CODE
CLASS="FUNCTION"
>libpcapnav</CODE
>, the library comes with a shellscript that provides the neccessary
        compiler and linker flags (similarly to many other packages):
        <TT
CLASS="FILENAME"
>pcapnav-config</TT
>.
        Use the <TT
CLASS="FILENAME"
>--cflags</TT
> option to obtain the
        compiler options and <TT
CLASS="FILENAME"
>--libs</TT
> to obtain the
        linker options.
        </P
></TD
></TR
></TABLE
></DIV
><BR
CLEAR="all"><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="AEN74"
>Using <TT
CLASS="FILENAME"
>pcapnav-config</TT
> in
	  <TT
CLASS="FILENAME"
>configure</TT
> scripts</A
></H1
><P
>      
        If you use the <B
CLASS="COMMAND"
>autoconf</B
>/<B
CLASS="COMMAND"
>automake</B
>
        tools, we recommend something along the following lines for your
	<TT
CLASS="FILENAME"
>configure</TT
> script:
      </P
><TABLE
WIDTH="100%"
BORDER="0"
BGCOLOR="#dadae0"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>dnl ##################################################
dnl # Check for pcapnav
dnl ##################################################
AC_ARG_WITH(pcapnav-config,
    AC_HELP_STRING([--with-pcapnav-config=FILE], [Use given pcapnav-config]),
    [ pcncfg="$withval" ],
    [ AC_PATH_GENERIC(pcapnav,,
          pcncfg="pcapnav-config",
          AC_MSG_ERROR(Cannot find libpcapnav: Is pcapnav-config in path?)) ])

pcapnav_libs=`$pcncfg --libs`
pcapnav_cflags=`$pcncfg --cflags`
AC_SUBST(pcapnav_libs)
AC_SUBST(pcapnav_cflags)
      </PRE
></TD
></TR
></TABLE
></DIV
><BR
CLEAR="all"><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="AEN83"
><CODE
CLASS="FUNCTION"
>libpcapnav</CODE
> code examples</A
></H1
><P
>        Time for some code. We will introduce variables whenever context
        requires it, and not necessarily at the beginning. In order to make
        the API known to the compiler, include pcapnav.h. This includes
        <TT
CLASS="FILENAME"
>pcap.h</TT
> for you, so you don't need to do it.
      </P
><TABLE
WIDTH="100%"
BORDER="0"
BGCOLOR="#dadae0"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>#include &#60;pcapnav.h&#62;
      </PRE
></TD
></TR
></TABLE
><P
>        <CODE
CLASS="FUNCTION"
>libpcapnav</CODE
> needs a tiny bit of initialization (right now
        only for debugging purposes, but this might change in the
        future). After that, the functions access their stateful
        information just like <CODE
CLASS="FUNCTION"
>libpcap</CODE
> through a handle structure
        that you obtain as follows:
      </P
><TABLE
WIDTH="100%"
BORDER="0"
BGCOLOR="#dadae0"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>pcapnav_t *pn;

/* Initialize the library */
pcapnav_init();

/* Now create a pcapnav handle */
if ( (pn = pcapnav_open_offline("foo.trace")) == NULL)
  {
    /* Didn't work -- appropriate error handling */
  }
      </PRE
></TD
></TR
></TABLE
><P
>        At this point you can iterate the packets in the trace
        as usual, or navigate to some region in the trace. For example,
        you find out the timeframe that is contained in the trace:
      </P
><TABLE
WIDTH="100%"
BORDER="0"
BGCOLOR="#dadae0"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>&#13;struct bpf_timeval start_tv, end_tv;

if (pcapnav_get_timespan(pn, &#38;start_tv, &#38;end_tv) != 0)
  {
    printf("Could not obtain timespan.\n");
    /* Rest of error handling */
  }
      </PRE
></TD
></TR
></TABLE
><P
>        <CODE
CLASS="FUNCTION"
>libpcapnav</CODE
> jumped close to the end of trace, resynchronized with
        the packet stream and copied out the timestamp of the last packet.
        Note that it is recommended to always use struct bpf_timeval when
        using <CODE
CLASS="FUNCTION"
>libpcapnav</CODE
> and not struct timeval. This masks some deviations
        in naming among different platforms.
      </P
><P
>        Now say you know that an interesting event occurred in the traffic
        at a specific time. You want to jump to the packet whose
        timestamp is closest to that time, and then dump all packets
        that were captured within the next ten minutes to a new trace
        file. We'll need a <CODE
CLASS="FUNCTION"
>libpcap</CODE
> dumper, as usual. To obtain the
        standard %pcap; handle from a %pcapnav; handle, use
        <CODE
CLASS="FUNCTION"
>pcapnav_pcap()</CODE
>:
      </P
><TABLE
WIDTH="100%"
BORDER="0"
BGCOLOR="#dadae0"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>pcap_dumper_t *dumper;
char *savefile;

/* Obtain savefile name somehow ... */

if ( (dumper = pcap_dump_open(pcapnav_pcap(pn), savefile)) == NULL)
  {
    printf("Could not open savefile %s\n", savefile);
    /* Rest of error handling */
  }
      </PRE
></TD
></TR
></TABLE
><P
>        Now let's jump to the timestamp we are interested in:
      </P
><TABLE
WIDTH="100%"
BORDER="0"
BGCOLOR="#dadae0"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>struct bpf_timeval event_tv;
pcapnav_result_t result;

/* Set event_tv to the correct time somehow ... */

/* Attempt to jump to that timestamp: */
result = pcapnav_goto_timestamp(pn, &#38;event_tv);
      </PRE
></TD
></TR
></TABLE
><DIV
CLASS="CAUTION"
><P
></P
><TABLE
CLASS="CAUTION"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="images/caution.gif"
HSPACE="5"
ALT="Caution"></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>          At this point, several things may have gone wrong: maybe the
          timestamp you are looking for actually falls outside the timeframe
          contained in the trace, or it was not possible to determine
          unambiguously the sequence of packets. After performing navigation,
          you should therefore <SPAN
CLASS="emphasis"
><B
CLASS="EMPHASIS"
>always</B
></SPAN
> perform error
          checking!
        </P
></TD
></TR
></TABLE
></DIV
><P
>        The following outcomes are possible:
      </P
><P
></P
><UL
><LI
><P
>            <CODE
CLASS="CONSTANT"
>PCAPNAV_DEFINITELY</CODE
>: yay. This is what
            you want: <CODE
CLASS="FUNCTION"
>libpcapnav</CODE
> was able to unambiguously resynchronize to
            the stream.
          </P
></LI
><LI
><P
>            <CODE
CLASS="CONSTANT"
>PCAPNAV_ERROR</CODE
>: a real problem occurred, such
            as invalid input.
          </P
></LI
><LI
><P
>            <CODE
CLASS="CONSTANT"
>PCAPNAV_NONE</CODE
>: no packet could be found;
            synchronization with the packet stream failed.
          </P
></LI
><LI
><P
>            <CODE
CLASS="CONSTANT"
>PCAPNAV_CLASH</CODE
>: there was more than one possible
            way to resynchronize to the stream, and they all looked equally likely.
            This should happen only rarely and is best resolved by attempting
            the jump again, but to a slightly different offset.
          </P
></LI
><LI
><P
>            <CODE
CLASS="CONSTANT"
>PCAPNAV_PERHAPS</CODE
>: it looks like <CODE
CLASS="FUNCTION"
>libpcapnav</CODE
> resynchronized
            successfully, but there was not enough data to be sure, for example
            near the end of a trace.
          </P
></LI
></UL
><P
>        We want to be sure that things work, so we check for <CODE
CLASS="CONSTANT"
>PCAPNAV_DEFINITELY</CODE
>:
      </P
><TABLE
WIDTH="100%"
BORDER="0"
BGCOLOR="#dadae0"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>if (result != PCAPNAV_DEFINITELY)
  {
    printf("Navigation failed.\n");
    /* Rest of error handling */
  }
      </PRE
></TD
></TR
></TABLE
><P
>        We want the next 10 minutes of traffic, so let's obtain the timestamp
        of the packet we're now pointing at, and add 10 minutes as a stop condition.
      </P
><TABLE
WIDTH="100%"
BORDER="0"
BGCOLOR="#dadae0"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>struct bpf_timeval current_tv, stop_tv;

if (pcapnav_get_current_timestamp(pn, &#38;current_tv) != 0)
  {
    printf("Something went wrong -- invalid input?\n");
    /* Rest of error handling */      
  }

/* Current timestamp is now in current_tv, add 10 mins for stop condition: */
stop_tv = current_tv;
stop_tv.tv_sec += 10*60;
      </PRE
></TD
></TR
></TABLE
><P
>        Almost there &mdash; now just iterate!
      </P
><TABLE
WIDTH="100%"
BORDER="0"
BGCOLOR="#dadae0"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>const u_char *packet_data;
struct pcap_pkthdr header;

do {
  if (! (packet_data = pcapnav_next(pn, &#38;header)))
    {
      printf("No more packets readable -- aborting.\n");
      /* Rest of error handling */       
    }

  /* Dump packet to new trace: */
  pcap_dump((u_char *) dumper, &#38;header, packet_data);
  current_tv = header.ts;

} while (pcapnav_timeval_cmp(&#38;current_tv, &#38;stop_tv) &#60;= 0);
      </PRE
></TD
></TR
></TABLE
><P
>        We're done, now clean up:
      </P
><TABLE
WIDTH="100%"
BORDER="0"
BGCOLOR="#dadae0"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>pcap_dump_close(dumper);
pcapnav_close(pn);
      </PRE
></TD
></TR
></TABLE
><P
>        In other scenarios you may find the callback-based
        <CODE
CLASS="FUNCTION"
>pcapnav_loop()</CODE
> more convenient. Please
        have a look at the API reference in the following chapter
        for more details.
      </P
></DIV
><BR
CLEAR="all"><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="AEN137"
>Controlling debugging output at runtime</A
></H1
><P
>	If your <CODE
CLASS="FUNCTION"
>libpcapnav</CODE
> was built with debugging support enabled (by passing
	<CODE
CLASS="FUNCTION"
>--enable-debugging</CODE
> at configure time), you can enable
	and disable debugging output at any time in your
	program in the global <CODE
CLASS="FUNCTION"
>pcapnav_runtime_options</CODE
>
	structure. The relevant elements are as follows:
	</P
><P
></P
><UL
><LI
><P
>                <CODE
CLASS="FUNCTION"
>debug</CODE
>: enables debugging output when
		set to a value &#62;= 1, and disables it when set to 0.
		Initialially, it is disabled.
	      </P
></LI
><LI
><P
>                <CODE
CLASS="FUNCTION"
>calldepth_limit</CODE
>: you can limit the calldepth
		up to which debugging output is displayed, to avoid excessive logging.
		By default, everything is logged (loglevel 0).
	      </P
></LI
></UL
><P
>	Setting these values in a non-debugging <CODE
CLASS="FUNCTION"
>libpcapnav</CODE
> will still compile (no need
	for preprocessor hacks) but won't have any effect.
	</P
></DIV
><BR
CLEAR="all"><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="AEN152"
>Using <CODE
CLASS="FUNCTION"
>libpcapnav</CODE
> to append packets to existing traces</A
></H1
><P
>	  When creating an output dumper using <CODE
CLASS="FUNCTION"
>libpcap</CODE
> (using
	  <CODE
CLASS="FUNCTION"
>pcap_dump_open()</CODE
>), the output trace file
	  is created from scratch. Using <CODE
CLASS="FUNCTION"
>libpcapnav</CODE
>, you can also create
	  a <CODE
CLASS="FUNCTION"
>libpcap</CODE
> dumper out of an existing trace and append packets
	  at the trace's end.
	</P
><P
>	  The function you use for this purpose is
	  <A
HREF="pcapnav-pcapnav.html#PCAPNAV-DUMP-OPEN"
><CODE
CLASS="FUNCTION"
>pcapnav_dump_open()</CODE
></A
>.
	  It allows you to append packets to an existing trace file, given that the linklevel
	  protocols are the same (that's imposed by the current <CODE
CLASS="FUNCTION"
>libpcap</CODE
> file format).
	  There are three different modes you can select for the operation:
	</P
><P
></P
><UL
><LI
><P
>                <CODE
CLASS="CONSTANT"
>LND_DUMP_TRUNC</CODE
>: the normal way. The output file,
	        if it exists already, is truncated and new packets are written from
	        the beginning. Otherwise the output trace is created, just as with
		<CODE
CLASS="FUNCTION"
>pcap_dump_open()</CODE
>.
              </P
></LI
><LI
><P
>                <CODE
CLASS="CONSTANT"
>LND_DUMP_APPEND_SAFE</CODE
>: appends packets to the end of the
		trace, including checking whether the last packet is truncated or not.
		Truncated packets occur when a <CODE
CLASS="FUNCTION"
>libpcap</CODE
> packet header is present in the
		trace and indicates a packet size that is not actually fully present
		in the file. In this case, the size in the <CODE
CLASS="FUNCTION"
>libpcap</CODE
> header is corrected
		to the part of the packet actually present, and new packets are appended
		after that.
              </P
></LI
><LI
><P
>                <CODE
CLASS="CONSTANT"
>LND_DUMP_APPEND_FAST</CODE
>: appends packets to the end of the
		trace, without paranoia checking. This is much faster than the safe alternative
		above, but should only be used when you can assume that the existing trace is
		not truncated at the end (for example, because you just created it and closed
		it properly).
              </P
></LI
></UL
><P
>	  Once you're done, you can close the dumper as usual, using
	  <CODE
CLASS="FUNCTION"
>pcap_dump_close()</CODE
>.
	</P
></DIV
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="c17.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="api.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Introduction</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
>&nbsp;</TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><CODE
CLASS="FUNCTION"
>libpcapnav</CODE
> API Reference</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>