diff options
author | Gerald Combs <gerald@wireshark.org> | 2021-09-30 15:31:36 -0700 |
---|---|---|
committer | Wireshark GitLab Utility <gerald+gitlab-utility@wireshark.org> | 2021-10-01 16:42:34 +0000 |
commit | 9f1607ab473c578d714320fa735fb0bc4e1d1e96 (patch) | |
tree | 6e8ae12807953db651f60aaf6a29c9589ebca9bc /doc/text2pcap.adoc | |
parent | 04b0e2b80be9654bbe307c66943222fadf1f93c1 (diff) |
Docs: Prep for POD to Asciidoctor conversion.
[skip ci]
Rename each of our .pod files to .adoc. Add pod2adoc.py, which converts
POD markup to Asciidoctor, along with customizations specific to us.
Diffstat (limited to 'doc/text2pcap.adoc')
-rw-r--r-- | doc/text2pcap.adoc | 274 |
1 files changed, 274 insertions, 0 deletions
diff --git a/doc/text2pcap.adoc b/doc/text2pcap.adoc new file mode 100644 index 0000000000..4a5a653461 --- /dev/null +++ b/doc/text2pcap.adoc @@ -0,0 +1,274 @@ +=begin man + +=encoding utf8 + +=end man + +=head1 NAME + +text2pcap - Generate a capture file from an ASCII hexdump of packets + +=head1 SYNOPSIS + +B<text2pcap> +S<[ B<-a> ]> +S<[ B<-d> ]> +S<[ B<-D> ]> +S<[ B<-e> E<lt>l3pidE<gt> ]> +S<[ B<-h> ]> +S<[ B<-i> E<lt>protoE<gt> ]> +S<[ B<-l> E<lt>typenumE<gt> ]> +S<[ B<-n> ]> +S<[ B<-N> E<lt>intf-nameE<gt> ]> +S<[ B<-m> E<lt>max-packetE<gt> ]> +S<[ B<-o> hex|oct|dec ]> +S<[ B<-q> ]> +S<[ B<-s> E<lt>srcportE<gt>,E<lt>destportE<gt>,E<lt>tagE<gt> ]> +S<[ B<-S> E<lt>srcportE<gt>,E<lt>destportE<gt>,E<lt>ppiE<gt> ]> +S<[ B<-t> E<lt>timefmtE<gt> ]> +S<[ B<-T> E<lt>srcportE<gt>,E<lt>destportE<gt> ]> +S<[ B<-u> E<lt>srcportE<gt>,E<lt>destportE<gt> ]> +S<[ B<-v> ]> +S<[ B<-4> E<lt>srcipE<gt>,E<lt>destipE<gt> ]> +S<[ B<-6> E<lt>srcipE<gt>,E<lt>destipE<gt> ]> +E<lt>I<infile>E<gt>|- +E<lt>I<outfile>E<gt>|- + +=head1 DESCRIPTION + +B<Text2pcap> is a program that reads in an ASCII hex dump and writes the +data described into a B<pcap> or B<pcapng> 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, TCP, or SCTP 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 -Ax +-tx1 -v>. In other words, each byte is individually displayed, with +spaces separating the bytes from each other. Each line begins with an offset +describing the position in the packet, each new packet starts with an offset +of 0 and there is a space separating the offset from the following bytes. +The offset is a hex number (can also be octal or decimal - see B<-o>), +of more than two hex digits. + +Here is a sample dump that B<text2pcap> can recognize: + + 000000 00 0e b6 00 00 02 00 0e b6 00 00 01 08 00 45 00 + 000010 00 28 00 00 00 00 ff 01 37 d1 c0 00 02 01 c0 00 + 000020 02 02 08 00 a6 2f 00 01 00 01 48 65 6c 6c 6f 20 + 000030 57 6f 72 6c 64 21 + 000036 + +Note the last byte must either be followed by the expected next offset value +as in the example above or a space or a line-end character(s). + +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. Packets may be +preceded by a timestamp. These are interpreted according to the format +given on the command line (see B<-t>). If not, the first packet +is timestamped with the current time the conversion takes place. Multiple +packets are written with timestamps differing by one microsecond 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/TCP/SCTP headers before each +packet. This allows Wireshark or any other full-packet decoder to +handle these dumps. + +=head1 OPTIONS + +=over 4 + +=item -a + +Enables ASCII text dump identification. It allows one to identify the start of +the ASCII text dump and not include it in the packet even if it looks like HEX. + +B<NOTE:> Do not enable it if the input file does not contain the ASCII text dump. + +=item -d + +Displays debugging information during the process. Can be used +multiple times to generate more debugging information. + +=item -D + +The text before the packet starts either with an I or O indicating that +the packet is inbound or outbound. This is used when generating dummy headers. +The indication is only stored if the output format is pcapng. + +=item -e E<lt>l3pidE<gt> + +Include a dummy Ethernet header before each packet. Specify the L3PID +for the Ethernet header in hex. Use this option if your dump has Layer +3 header and payload (e.g. IP header), but no Layer 2 +encapsulation. Example: I<-e 0x806> to specify an ARP packet. + +For IP packets, instead of generating a fake Ethernet header you can +also use I<-l 101> to indicate a raw IP packet to Wireshark. Note that +I<-l 101> does not work for any non-IP Layer 3 packet (e.g. ARP), +whereas generating a dummy Ethernet header with I<-e> works for any +sort of L3 packet. + +=item -h + +Displays a help message. + +=item -i E<lt>protoE<gt> + +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 with each packet. Note that an appropriate Ethernet header +is automatically included with each packet as well. +Example: I<-i 46> to specify an RSVP packet (IP protocol 46). See +L<https://www.iana.org/assignments/protocol-numbers/protocol-numbers.xhtml> for +the complete list of assigned internet protocol numbers. + +=item -l + +Specify the link-layer header type of this packet. Default is Ethernet +(1). See L<https://www.tcpdump.org/linktypes.html> 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 encapsulated BSD-style. + +=item -m E<lt>max-packetE<gt> + +Set the maximum packet length, default is 262144. +Useful for testing various packet boundaries when only an application +level datastream is available. Example: + +I<od -Ax -tx1 -v stream | text2pcap -m1460 -T1234,1234 - stream.pcap> + +will convert from plain datastream format to a sequence of Ethernet +TCP packets. + +=item -n + +Write the file in pcapng format rather than pcap format. + +=item -N E<lt>intf-nameE<gt> + +Specify a name for the interface included when writing a pcapng format +file. By default no name is defined. + +=item -o hex|oct|dec + +Specify the radix for the offsets (hex, octal or decimal). Defaults to +hex. This corresponds to the C<-A> option for I<od>. + +=item -q + +Be completely quiet during the process. + +=item -s E<lt>srcportE<gt>,E<lt>destportE<gt>,E<lt>tagE<gt> + +Include dummy SCTP headers before each packet. Specify, in decimal, the +source and destination SCTP ports, and verification tag, for the packet. +Use this option if your dump is the SCTP payload of a packet but does +not include any SCTP, IP or Ethernet headers. Note that appropriate +Ethernet and IP headers are automatically also included with each +packet. A CRC32C checksum will be put into the SCTP header. + +=item -S E<lt>srcportE<gt>,E<lt>destportE<gt>,E<lt>ppiE<gt> + +Include dummy SCTP headers before each packet. Specify, in decimal, the +source and destination SCTP ports, and a verification tag of 0, for the +packet, and prepend a dummy SCTP DATA chunk header with a payload +protocol identifier if I<ppi>. Use this option if your dump is the SCTP +payload of a packet but does not include any SCTP, IP or Ethernet +headers. Note that appropriate Ethernet and IP headers are +automatically included with each packet. A CRC32C checksum will be put +into the SCTP header. + +=item -t E<lt>timefmtE<gt> + +Treats the text before the packet as a date/time code; I<timefmt> is a +format string of the sort supported by strptime(3). +Example: The time "10:15:14.5476" has the format code "%H:%M:%S." + +B<NOTE:> The subsecond component delimiter must be specified (.) but no +pattern is required; the remaining number is assumed to be fractions of +a second. + +B<NOTE:> Date/time fields from the current date/time are +used as the default for unspecified fields. + +=item -T E<lt>srcportE<gt>,E<lt>destportE<gt> + +Include dummy TCP headers before each packet. Specify the source and +destination TCP ports for the packet in decimal. Use this option if +your dump is the TCP payload of a packet but does not include any TCP, +IP or Ethernet headers. Note that appropriate Ethernet and IP headers +are automatically also included with each packet. +Sequence numbers will start at 0. + +=item -u E<lt>srcportE<gt>,E<lt>destportE<gt> + +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 appropriate Ethernet and IP headers +are automatically also included with each packet. +Example: I<-u1000,69> to make the packets look like TFTP/UDP packets. + +=item -v + +Print the version and exit. + +=item -4 E<lt>srcipE<gt>,E<lt>destipE<gt> + +Prepend dummy IP header with specified IPv4 dest and source address. +This option should be accompanied by one of the following options: -i, -s, -S, -T, -u +Use this option to apply "custom" IP addresses. +Example: I<-4 10.0.0.1,10.0.0.2> to use 10.0.0.1 and 10.0.0.2 for all IP packets. + +=item -6 E<lt>srcipE<gt>,E<lt>destipE<gt> + +Prepend dummy IP header with specified IPv6 dest and source address. +This option should be accompanied by one of the following options: -i, -s, -S, -T, -u +Use this option to apply "custom" IP addresses. +Example: I<-6 fe80::202:b3ff:fe1e:8329,2001:0db8:85a3::8a2e:0370:7334> to +use fe80::202:b3ff:fe1e:8329 and 2001:0db8:85a3::8a2e:0370:7334 for all IP packets. + +=back + +=head1 SEE ALSO + +od(1), pcap(3), wireshark(1), tshark(1), dumpcap(1), mergecap(1), +editcap(1), strptime(3), pcap-filter(7) or tcpdump(8) + +=head1 NOTES + +B<Text2pcap> is part of the B<Wireshark> distribution. The latest version +of B<Wireshark> can be found at L<https://www.wireshark.org>. + +=head1 AUTHORS + + Ashok Narayanan <ashokn[AT]cisco.com> |