source: docs/PACKETDUMP.TXT @ 099c35e

Last change on this file since 099c35e was 2d7da92, checked in by Brendon Jones <brendonj@…>, 16 years ago

Started writing some documentation about how to create custom decoders for libpacketdump using the parser. Describes the file format etc and has a simple example.

Needs to have information on writing shared libraries for decoding with libpacketdump added. Needs to be re-written so it makes more sense.

  • Property mode set to 100644
File size: 3.8 KB
1Writing decoder modules for libpacketdump
4libpacketdump can be used to decode and print packet structure. This can be
5useful for debugging (network protocols, or your own libtrace programs), or
6just to look at the internals of the packets you are seeing to better
7understand how things work.
9It has a modular design such that each decoder is only responsible for
10its specific part of the packet. It decodes the information it knows about,
11then control is passed to the decoder that understands the next part of the
12packet. Code only needs to be written once for each part, and then decoders
13are mixed and matched as appropriate depending on the structure and content
14of the packet.
16These modules can be constructed in two ways:
18    * as C code within a shared library
19    * as a plain text description of the field sizes and types
21Each modules filename is constructed based on the part of the packet it deals
22with. The bit before the underscore describes the part of the packet it follows
23on from, while the bit after the underscore describes what it actually is.
24Shared libraries end in .so, and plain text files end in .protocol. All these
25files must reside in DIRNAME (by default /usr/local/lib/libpacketdump/).
28Writing a decoder module as a shared library
35Writing a decoder module as plain text
38These files have a very simple format that mimics the layout of the headers
39seen in the packets. Each line of the file represents a single field in the
40header, or describes the header that follows this one. For them to be found
41by the parser they must have a .protocol extension.
43A .protocol file might look something like this:
45    be16 integer    "FOO Src port"
46    be16 integer    "FOO Dst port"
47    be8  hex        "FOO type"
48    be24 integer    "FOO other"
49    next "foo"      "FOO type" 
51All lines in the file are one of these two types:
53Field description:  <byteorder> <size> <displaytype> <name>
54Next header:        next <nextheader prefix> <nextheader fieldname>
58Fields in packet headers can be in big endian or little endian form; most are
59in big endian. Specify 'be' for big endian fields or 'le' for little endian
60fields. This ensures they are displayed correctly.
63The width of the field in bits. For example, addresses in the IP header are
6432 bits, while ports in the UDP/TCP headers are 16 bits.
66<display type>
67This determines how the data is treated when it is displayed. Valid values are:
68    integer - displays the data as an integer value
69    hex     - displays the data as a hexadecimal value
70    ipv4    - displays the data as an IPV4 address in dotted quad form
71    mac     - displays the data as a MAC address as colon separated hexadecimals
72    flag    - displays the field name if the data is true, nothing otherwise
73    hidden  - does not get displayed
76A string literal used as a prefix when printing the field value, and as an
77identifier to be referenced by the nextheader option (if present).
79<nextheader prefix>
80A string literal used as a prefix to the filename describing where to find
81information on decoding the header that follows this one. It usually describes
82the current level at which the packet is being decoded such as "eth" or "ip".
84<nextheader fieldname>
85The string literal used as the name of the field whose value determines what
86the next header should be. The value of this field gets appended to the prefix
87(after an underscore) to create the basename of the file describing the next
88header. For example, in the IP header the next header is described by the value
89of the protocol field, and so the name used for the protocol field should be
90given here. If a TCP packet is being decoded, the value of the protocol field
91will be '6' and this is used to construct the next file name.
Note: See TracBrowser for help on using the repository browser.