wiretap/README

   1 NOTE: this documents the original intent behind libwiretap.  Currently,
   2 it is being developed solely as a library for reading capture files,
   3 rather than packet capture.  The list of file formats is also
   4 out-of-date.
   5
   6 Wiretap is a library that is being developed as a future replacement for
   7 libpcap, the current standard Unix library for packet capturing. Libpcap
   8 is great in that it is very platform independent and has a wonderful
   9 BPF optimizing engine. But it has some shortcomings as well. These
  10 shortcomings came to a head during the development of Wireshark
  11 (https://www.wireshark.org/), a packet analyzer. As such, I began developing
  12 wiretap so that:
  13
  14 1. The library can easily be amended with new packet filtering objects.
  15 Libpcap is very TCP/IP-oriented. I want to filter on IPX objects, SNA objects,
  16 etc. I also want any decent programmer to be able to add new filters to the
  17 library.
  18
  19 2. The library can read file formats from many packet-capturing utilities.
  20 Libpcap only reads Libpcap files.
  21
  22 3. The library can capture on more than one network interface at a time, and
  23 save this trace in one file.
  24
  25 4. Network names can be resolved immediately after a trace and saved in the
  26 trace file. That way, I can ship a trace of my firewall-protected network to a
  27 colleague, and he'll see the proper hostnames for the IP addresses in the
  28 packet capture, even though he doesn't have access to the DNS server behind my
  29 LAN's firewall.
  30
  31 5. I want to look into the possibility of compressing packet data when saved
  32 to a file, like Sniffer.
  33
  34 6. The packet-filter can be optimized for the host OS. Not all OSes have BPF;
  35 SunOS has NIT and Solaris has DLPI, which both use the CMU/Stanford
  36 packet-filter pseudomachine. RMON has another type of packet-filter syntax
  37 which we could support.
  38
  39 Wiretap is very good at reading many file formats, as per #2
  40 above. Wiretap has no filter capability at present; it currently doesn't
  41 support packet capture, so it wouldn't be useful there, and filtering
  42 when reading a capture file is done by Wireshark, using a more powerful
  43 filtering mechanism than that provided by BPF.
  44
  45
  46 File Formats
  47 ============
  48
  49 Libpcap
  50 -------
  51 The "libpcap" file format was determined by reading the "libpcap" code;
  52 wiretap reads the "libpcap" file format with its own code, rather than
  53 using the "libpcap" library's code to read it.
  54
  55 Sniffer (compressed and uncompressed)
  56 -------
  57 The uncompressed Sniffer format is documented in the Sniffer manual.
  58 Unfortunately, Sniffer manuals tend to document only the format for
  59 the Sniffer model they document. Token-Ring and ethernet seems to work
  60 well, though.  If you have an ATM Sniffer file, both Guy and Gilbert
  61 would be *very* interested in receiving a sample. (see 'AUTHORS' file
  62 for our e-mail addresses).
  63
  64 LANalyzer
  65 ---------
  66 The LANalyzer format is available from http://www.novell.com. Search
  67 their knowledge base for "Trace File Format".
  68
  69 Network Monitor
  70 ---------------
  71 Microsoft's Network Monitor file format is supported, at least under
  72 Ethernet and token-ring. If you have capture files of other datalink
  73 types, please send them to Guy.
  74
  75 "snoop"
  76 -------
  77 The Solaris 2.x "snoop" program's format is documented in RFC 1761.
  78
  79 "iptrace"
  80 ---------
  81 This is the capture program that comes with AIX 3.x and 4.x.  AIX 3 uses
  82 the iptrace 1.0 file format, while AIX4 uses iptrace 2.0.  iptrace has
  83 an undocumented, yet very simple, file format.  The interesting thing
  84 about iptrace is that it will record packets coming in from all network
  85 interfaces; a single iptrace file can contain multiple datalink types.
  86
  87 Sniffer Basic (NetXRay)/Windows Sniffer Pro
  88 -------------------------------------------
  89 Network Associates' Sniffer Basic (formerly NetXRay from Cinco Networks)
  90 file format is now supported, at least for Ethernet and token-ring.
  91 Network Associates' Windows Sniffer Pro appears to use a variant of that
  92 format; it's supported to the same extent.
  93
  94 RADCOM WAN/LAN Analyzers
  95 ------------------------
  96 Olivier Abad has added code to read Ethernet and LAPB captures from
  97 RADCOM WAN/LAN Analyzers (see https://web.archive.org/web/20031231213434/http://www.radcom-inc.com/).
  98
  99 Lucent/Ascend access products
 100 -----------------------------
 101 Gerald
 102
 103 HP-UX nettl
 104 -----------
 105 nettl is used on HP-UX to trace various streams based subsystems.  Wiretap
 106 can read nettl files containing IP frames (NS_LS_IP subsystem) and LAPB
 107 frames (SX25L2 subsystem). It has been tested with files generated on
 108 HP-UX 9.04 and 10.20.
 109 Use the following commands to generate a trace :
 110 # IP capture. 0x30000000 means PDU in and PDU out :
 111 nettl -tn 0x30000000 -e NS_LS_IP -f tracefile
 112 # X25 capture. You must specify an interface :
 113 nettl -tn 0x30000000 -e SX25l2 -d /dev/x25_0 -f tracefile
 114 # stop capture. subsystem is NS_LS_IP or SX25L2 :
 115 nettl -tf -e subsystem
 116
 117 One may be able to specify "-tn pduin pduout" rather than
 118 "-tn 0x30000000"; the nettl man page for HP-UX 10.30 implies that it
 119 should work.
 120
 121 There is also basic support for nettl files containing NS_LS_DRIVER,
 122 NS_LS_TCP, NS_LS_UDP, NS_LS_LOOPBACK, unknown type 0xb9, and NS_LS_ICMP.
 123 However, NS_LS_ICMP will not be decoded since WTAP lacks a raw ICMP
 124 encapsulation type.
 125
 126
 127 Toshiba ISDN Router
 128 -------------------
 129 An under-documented command that the router supports in a telnet session
 130 is "snoop" (not related to the Solaris "snoop" command). If you give
 131 it the "dump" option (either by letting "snoop" query you for its next
 132 argument, or typing "snoop dump" on the command line), you'll get a hex
 133 dump of all packets across the router (except of your own telnet session
 134 -- good thinking Toshiba!). You can select a certain channel to sniff
 135 (LAN, B1, B2, D), but the default is all channels.  You save this hex
 136 dump to disk with 'script' or by 'telnet | tee'. Wiretap will read the
 137 ASCII hex dump and convert it to binary data.
 138
 139 ISDN4BSD "i4btrace" utility
 140 ---------------------------
 141 Bert Driehuis
 142
 143 Cisco Secure Intrusion Detection System iplogging facility
 144 -----------------------------------------------------------
 145 Mike Hall
 146
 147 pppd logs (pppdump-format files)
 148 --------------------------------
 149 Gilbert
 150
 151 VMS TCPTRACE
 152 ------------
 153 Compaq VMS's TCPIPTRACE format is supported.  This is the capture program
 154 that comes with TCP/IP or UCX as supplied by Compaq or Digital Equipment
 155 Corporation.
 156
 157 Under UCX 4.x, it is invoked as TCPIPTRACE.  Under TCPIP 5.x, it is invoked
 158 as TCPTRACE.
 159
 160 TCPTRACE produces an ascii text based format, that has changed slightly over
 161 time.
 162
 163 DBS Etherwatch (text format)
 164 ----------------------------
 165 Text output from DBS Etherwatch is supported.  DBS Etherwatch is available
 166 from: https://web.archive.org/web/20070612033348/http://www.users.bigpond.com/dbsneddon/software.htm.
 167
 168 Catapult DCT2000 (.out files)
 169 -----------------------------
 170 DCT2000 test systems produce ascii text-based .out files for ports
 171 that have logging enabled. When being read, the data part of the message is
 172 prefixed with a short header that provides some context (context+port,
 173 direction, original timestamp, etc).
 174
 175 You can choose to suppress the reading of non-standard protocols
 176 (i.e. messages between layers rather than the well-known link-level protocols
 177 usually found on board ports).
 178
 179
 180 Gilbert Ramirez <gram@alumni.rice.edu>
 181 Guy Harris <guy@alum.mit.edu>
 182
 183 STANAG 4607
 184 -----------
 185 Initial support for the STANAG 4607 protocol.  Documentation at:
 186 https://web.archive.org/web/20130223054955/http://www.nato.int/structur/AC/224/standard/4607/4607.htm