Added 'text2pcap', a utility to convert text hexdumps into pcap

files. See text2pcap.1 (built from doc/text2pcap.pod) for details.

Changed 'tethereal -x' output to match hex dump format of text2pcap,
Ethereal and others.

svn path=/trunk/; revision=3421

2 files changed, 148 insertions, 1 deletions

diff --git a/doc/Makefile.am b/doc/Makefile.am
index 7d184702d4..1adc2a04c0 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -1,7 +1,7 @@
 # Makefile.am
 # Automake file for Ethereal documentation
 #
-# $Id: Makefile.am,v 1.9 2001/03/06 18:38:47 gram Exp $
+# $Id: Makefile.am,v 1.10 2001/05/16 21:32:05 ashokn Exp $
 #
 # Ethereal - Network traffic analyzer
 # By Gerald Combs <gerald@zing.org>
@@ -48,3 +48,9 @@ tethereal.pod: tethereal.pod.template  ../tethereal
 	--center="The Ethereal Network Analyzer" \
 	--release=$(VERSION)			 \
 	> ../editcap.1
+
+../text2pcap.1: text2pcap.pod ../config.h
+	pod2man $(srcdir)/text2pcap.pod                     \
+	--center="The Ethereal Network Analyzer" \
+	--release=$(VERSION)			 \
+	> ../text2pcap.1
diff --git a/doc/text2pcap.pod b/doc/text2pcap.pod
new file mode 100644
index 0000000000..42c88658a3
--- /dev/null
+++ b/doc/text2pcap.pod
@@ -0,0 +1,141 @@
+
+=head1 NAME
+
+Text2pcap - Generate a capture file from an ASCII hexdump of packets
+
+=head1 SYNOPSYS
+
+B<text2pcap>
+S<[ B<-d> ]> 
+S<[ B<-q> ]> 
+S<[ B<-o> hex|oct ]> 
+S<[ B<-l> typenum ]> 
+S<[ B<-e> l3pid ]> 
+S<[ B<-i> proto]> 
+S<[ B<-u> srcport destport]> 
+I<infile>
+I<outfile>
+
+=head1 DESCRIPTION
+
+B<Text2pcap> is a program that reads in an ASCII hex dump and writes
+the data described into a B<libpcap>-style capture file. B<text2pcap>
+can read hexdumps with multiple packets in them, and build a capture
+file of multiple packets. B<text2pcap> is also capable of generating
+dummy Ethernet, IP and UDP headers, in order to build fully
+processable packet dumps from hexdumps of application-level data
+only. 
+
+B<Text2pcap> understands a hexdump of the form generated by I<od -t
+x1>. In other words, each byte is individually displayed and
+surrounded with a space. Each line begins with an offset describing
+the position in the file. The offset is a hex number (can also be
+octal - see B<-o>), of more than two hex digits. Here is a sample dump
+that B<text2pcap> can recognize:
+
+    000000 00 e0 1e a7 05 6f 00 10 ........
+    000008 5a a0 b9 12 08 00 46 00 ........
+    000010 03 68 00 00 00 00 0a 2e ........
+    000018 ee 33 0f 19 08 7f 0f 19 ........
+    000020 03 80 94 04 00 00 10 01 ........
+    000028 16 a2 0a 00 03 50 00 0c ........
+    000030 01 01 0f 19 03 80 11 01 ........
+
+There is no limit on the width or number of bytes per line. Also the
+text dump at the end of the line is ignored. Bytes/hex numbers can be
+uppercase or lowercase. Any text before the offset is ignored,
+including email forwarding characters '>'. Any lines of text between
+the bytestring lines is ignored. The offsets are used to track the
+bytes, so offsets must be correct. Any line which has only bytes
+without a leading offset is ignored. An offset is recognized as being
+a hex number longer than two characters. Any text after the bytes is
+ignored (e.g. the character dump). Any hex numbers in this text are
+also ignored. An offset of zero is indicative of starting a new
+packet, so a single text file with a series of hexdumps can be
+converted into a packet capture with multiple packets. Multiple
+packets are read in with timestamps differing by one second each. In
+general, short of these restrictions, B<text2pcap> is pretty liberal
+about reading in hexdumps and has been tested with a variety of
+mangled outputs (including being forwarded through email multiple
+times, with limited line wrap etc.)
+
+There are a couple of other special features to note. Any line where
+the first non-whitespace character is '#' will be ignored as a
+comment. Any line beginning with #TEXT2PCAP is a directive and options
+can be inserted after this command to be processed by
+B<text2pcap>. Currently there are no directives implemented; in the
+future, these may be used to give more fine grained control on the
+dump and the way it should be processed e.g. timestamps, encapsulation
+type etc.
+
+B<Text2pcap> also allows the user to read in dumps of
+application-level data, by inserting dummy L2, L3 and L4 headers
+before each packet. The user can elect to insert Ethernet headers,
+Ethernet and IP, or Ethernet, IP and UDP headers before each
+packet. This allows Ethereal or any other full-packet decoder to
+handle these dumps.
+
+=head1 OPTIONS
+
+=over 4
+
+=item -d
+
+Displays debugging information during the process. Can be used
+multiple times to generate more debugging information.
+
+=item -q
+
+Be completely quiet during the process.
+
+=item -o hex|oct
+
+Specify the radix for the offsets (hex or octal). Defaults to
+hex. This corresponds to the C<-A> option for I<od>.
+
+=item -l
+
+Specify the link-layer type of this packet. Default is Ethernet
+(1). See I<net/bpf.h> for the complete list of possible
+encapsulations. Note that this option should be used if your dump is a
+complete hex dump of an encapsulated packet and you wish to specify
+the exact type of encapsulation. Example: I<-l 7> for ARCNet packets.
+
+=item -e l3pid
+
+Include a dummy Ethernet header before each packet. Specify the L3PID
+for the Ethernet header in hex. Use this option if your dump is an IP
+packet with IP header and payload, but no Layer 2
+encapsulation. Example: I<-e 0x806> to specify an ARP packet.
+
+=item -i proto
+
+Include dummy IP headers before each packet. Specify the IP protocol
+for the packet in decimal. Use this option if your dump is the payload
+of an IP packet (i.e. has complete L4 information) but does not have
+an IP header. Note that this automatically includes an appropriate
+Ethernet header as well. Example: I<-i 46> to specify an RSVP packet
+(IP protocol 46).
+
+=item -u srcport destport
+
+Include dummy UDP headers before each packet. Specify the source and
+destination UDP ports for the packet in decimal. Use this option if
+your dump is the UDP payload of a packet but does not include any UDP,
+IP or Ethernet headers. Note that this automatically includes
+appropriate Ethernet and IP headers with each packet. Example: I<-u
+1000 69> to make the packets look like TFTP/UDP packets.
+
+
+=head1 SEE ALSO
+
+L<tcpdump(8)>, L<pcap(3)>, L<ethereal(1)>, L<editcap(1)>
+
+=head1 NOTES
+
+B<Text2pcap> is part of the B<Ethereal> distribution.  The latest version
+of B<Ethereal> can be found at B<http://www.ethereal.com>.
+
+=head1 AUTHORS
+
+  Ashok Narayanan          <ashokn@cisco.com>