forked from osmocom/wireshark
![Pascal Quantin](/assets/img/avatar_default.png)
Change-Id: I73ab87032e4a0c0259227622412be36aaf66a9d6 Reviewed-on: https://code.wireshark.org/review/20758 Reviewed-by: Guy Harris <guy@alum.mit.edu>
262 lines
10 KiB
Text
262 lines
10 KiB
Text
|
|
=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<-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> ]>
|
|
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> 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 only stored if the output format is PCAP-NG.
|
|
|
|
=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<http://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<http://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 PCAP-NG file instead of a PCAP.
|
|
|
|
=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:0:0:0:202:b3ff:fe1e:8329, 2001:0db8:85a3:0000:0000:8a2e:0370:7334> to
|
|
use fe80:0:0:0:202:b3ff:fe1e:8329 and 2001:0db8:85a3:0000:0000: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>
|