diff options
author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-10 20:34:10 +0000 |
---|---|---|
committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-10 20:34:10 +0000 |
commit | e4ba6dbc3f1e76890b22773807ea37fe8fa2b1bc (patch) | |
tree | 68cb5ef9081156392f1dd62a00c6ccc1451b93df /doc/text2pcap.adoc | |
parent | Initial commit. (diff) | |
download | wireshark-e4ba6dbc3f1e76890b22773807ea37fe8fa2b1bc.tar.xz wireshark-e4ba6dbc3f1e76890b22773807ea37fe8fa2b1bc.zip |
Adding upstream version 4.2.2.upstream/4.2.2
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'doc/text2pcap.adoc')
-rw-r--r-- | doc/text2pcap.adoc | 421 |
1 files changed, 421 insertions, 0 deletions
diff --git a/doc/text2pcap.adoc b/doc/text2pcap.adoc new file mode 100644 index 00000000..ab894747 --- /dev/null +++ b/doc/text2pcap.adoc @@ -0,0 +1,421 @@ +include::../docbook/attributes.adoc[] += text2pcap(1) +:doctype: manpage +:stylesheet: ws.css +:linkcss: +:copycss: ../docbook/{stylesheet} + +== NAME + +text2pcap - Generate a capture file from an ASCII hexdump of packets + +== SYNOPSIS + +[manarg] +*text2pcap* +[ *-a* ] +[ *-b* 2|8|16|64 ] +[ *-D* ] +[ *-e* <l3pid> ] +[ *-E* <encapsulation type> ] +[ *-F* <file format> ] +[ *-i* <proto> ] +[ *-l* <typenum> ] +[ *-N* <intf-name> ] +[ *-m* <max-packet> ] +[ *-o* hex|oct|dec|none ] +[ *-q* ] +[ *-r* <regex> ] +[ *-s* <srcport>,<destport>,<tag> ] +[ *-S* <srcport>,<destport>,<ppi> ] +[ *-t* <timefmt> ] +[ *-T* <srcport>,<destport> ] +[ *-u* <srcport>,<destport> ] +[ *-4* <srcip>,<destip> ] +[ *-6* <srcip>,<destip> ] +<__infile__>|- +<__outfile__>|- + +[manarg] +*text2pcap* +*-h|--help* + +[manarg] +*text2pcap* +*-v|--version* + +== DESCRIPTION + +*Text2pcap* is a program that reads in an ASCII hex dump and writes the +data described into a capture file. *text2pcap* can read hexdumps with +multiple packets in them, and build a capture file of multiple packets. +*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. + +*Text2pcap* can write the file in several output formats. +The *-F* flag can be used to specify the format in which to write the +capture file, *text2pcap -F* provides a list of the available output +formats. By default, it writes the packets to __outfile__ in the *pcapng* +file format. + +*Text2pcap* understands a hexdump of the form generated by __od -Ax + -tx1 -v__. In other words, each byte is individually displayed, with +spaces separating the bytes from each other. Hex digits can be upper +or lowercase. + +In normal operation, each line must begin with an offset describing the +position in the packet, followed a colon, space, or tab separating it from +the bytes. There is no limit on the width or number of bytes per line, but +lines with only hex bytes without a leading offset are ignored (in other words, +line breaks should not be inserted in long lines that wrap.) Offsets are more +than two digits; they are in hex by default, but can also be in octal or +decimal - see *-o*. Each packet must begin with offset zero, and an offset +zero indicates the beginning of a new packet. Offset values must be correct; +an unexpected value causes the current packet to be aborted and the next +packet start awaited. There is also a single packet mode with no offsets; +see *-o*. + +Packets may be preceded by a direction indicator ('I' or 'O') and/or a +timestamp if indicated by the command line (see *-D* and *-t*). If both are +present, the direction indicator precedes the timestamp. The format of the +timestamps is specified as a mandatory parameter to *-t*. If no timestamp is +parsed, in the case of the first packet the current system time is used, while +subsequent packets are written with timestamps one microsecond later than that +of the previous packet. + +Other text in the input data is ignored. Any text before the offset is +ignored, including email forwarding characters '>'. Any text on a line +after the bytes is ignored, e.g. an ASCII character dump (but see *-a* to +ensure that hex digits in the character dump are ignored). Any line where +the first non-whitespace character is a '#' will be ignored as a comment. +Any lines of text between the bytestring lines are considered preamble; +the beginning of the preamble is scanned for the direction indicator and +timestamp as mentioned above and otherwise ignored. + +Any line beginning with #TEXT2PCAP is a directive and options +can be inserted after this command to be processed by *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. + +In general, short of these restrictions, *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.) + +Here is a sample dump that *text2pcap* can recognize, with optional +directional indicator and timestamp: + + I 2019-05-14T19:04:57Z + 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 + +*Text2pcap* is also capable of scanning a text input file using a custom Perl +compatible regular expression that matches a single packet. *text2pcap* +searches the given file (which must end with '\n') for non-overlapping non-empty +strings matching the regex. Named capturing subgroups, which must match +exactly once per packet, are used to identify fields to import. The following +fields are supported in regex mode, one mandatory and three optional: + + "data" Actual captured frame data to import + "time" Timestamp of packet + "dir" Direction of packet + "seqno" Arbitrary ID of packet + +The 'data' field is the captured data, which must be in a selected encoding: +hexadecimal (the default), octal, binary, or base64 and containing no +characters in the data field outside the encoding set besides whitespace. +The 'time' field is parsed according to the format in the *-t* parameter. +The first character of the 'dir' field is compared against a set of characters +corresponding to inbound and outbound that default to "iI<" for inbound and +"oO>" for outbound to assign a direction. The 'seqno' field is assumed to +be a positive integer base 10 used for an arbitrary ID. An optional field's +information will only be written if the field is present in the regex and if +the capture file format supports it. (E.g., the pcapng format supports all +three fields, but the pcap format only supports timestamps.) + +Here is a sample dump that the regex mode can process with the regex +'^(?<dir>[<>])\s(?<time>\d+:\d\d:\d\d.\d+)\s(?<data>[0-9a-fA-F]+)$' along +with timestamp format '%H:%M:%S.%f', directional indications of '<' and '>', +and hex encoding: + + > 0:00:00.265620 a130368b000000080060 + > 0:00:00.280836 a1216c8b00000000000089086b0b82020407 + < 0:00:00.295459 a2010800000000000000000800000000 + > 0:00:00.296982 a1303c8b00000008007088286b0bc1ffcbf0f9ff + > 0:00:00.305644 a121718b0000000000008ba86a0b8008 + < 0:00:00.319061 a2010900000000000000001000600000 + > 0:00:00.330937 a130428b00000008007589186b0bb9ffd9f0fdfa3eb4295e99f3aaffd2f005 + > 0:00:00.356037 a121788b0000000000008a18 + +The regex is compiled with multiline support, and it is recommended to use +the anchors '^' and '$' for best results. + +*Text2pcap* also allows the user to read in dumps of application-level +data and insert dummy L2, L3 and L4 headers before each packet. This allows +Wireshark or any other full-packet decoder to handle these dumps. +If the encapsulation type is Ethernet, the user can elect to insert Ethernet +headers, Ethernet and IP, or Ethernet, IP and UDP/TCP/SCTP headers before +each packet. The fake headers can also be used with the Raw IP, Raw IPv4, +or Raw IPv6 encapsulations, with the Ethernet header omitted. These +encapsulation options can be used in both hexdump mode and regex mode. + +When <__infile__> or <__outfile__> are '-', standard input or standard +output, respectively, are used. + +== OPTIONS + +-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. +This parameter has no effect in regex mode. + +*NOTE:* Do not enable it if the input file does not contain the ASCII text dump. +-- + +-b 2|8|16|64:: ++ +-- +Specify the base (radix) of the encoding of the packet data in regex mode. +The supported options are 2 (binary), 8 (octal), 16 (hexadecimal), and 64 +(base64 encoding), with hex as the default. This parameter has no effect +in hexdump mode. +-- + +-D:: ++ +-- +Indicates that the text before each input packet may start either with an I +or O indicating that the packet is inbound or outbound. If both this flag +and the __t__ flag are used, the directional indicator is expected before +the time code. +This parameter has no effect in regex mode, where the presence of the `<dir>` +capturing group determines whether direction indicators are expected. + +Direction indication is stored in the packet headers if the output format +supports it (e.g. pcapng), and is also used when generating dummy headers +to swap the source and destination addresses and ports as appropriate. +-- + +-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 has Layer +3 header and payload (e.g. IP header), but no Layer 2 +encapsulation. Example: __-e 0x806__ to specify an ARP packet. + +For IP packets, instead of generating a fake Ethernet header you can +also use __-E rawip__ or __-l 101__ to indicate raw IP encapsulation. +Note that raw IP encapsulation does not work for any non-IP Layer 3 packet +(e.g. ARP), whereas generating a dummy Ethernet header with __-e__ works +for any sort of L3 packet. +-- + +-E <encapsulation type>:: ++ +-- +Sets the packet encapsulation type of the output capture file. +*text2pcap -E* provides a list of the available types; note that not +all file formats support all encapsulation types. The default type is +ether (Ethernet). + +*NOTE:* This sets the encapsulation type of the output file, but does +not translate the packet headers or add additional headers. It is used +to specify the encapsulation that matches the input data. +-- + +-F <file format>:: ++ +-- +Sets the file format of the output capture file. *Text2pcap* can write +the file in several formats; *text2pcap -F* provides a list of the +available output formats. The default is the *pcapng* format. +-- + +-h|--help:: +Print the version number and options and exit. + +-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 with each packet. Note that an appropriate Ethernet header +is automatically included with each packet as well if the link-layer +type is Ethernet. +Example: __-i 46__ to specify an RSVP packet (IP protocol 46). See +https://www.iana.org/assignments/protocol-numbers/protocol-numbers.xhtml for +the complete list of assigned internet protocol numbers. +-- + +-l <typenum>:: ++ +-- +Sets the packet encapsulation type of the output capture file, using +pcap link-layer header type numbers. Default is Ethernet (1). +See https://www.tcpdump.org/linktypes.html for the complete list +of possible encapsulations. +Example: __-l 7__ for ARCNet packets encapsulated BSD-style. +-- + +-m <max-packet>:: ++ +-- +Set the maximum packet length, default is 262144. +Useful for testing various packet boundaries when only an application +level datastream is available. Example: + +__od -Ax -tx1 -v stream | text2pcap -m1460 -T1234,1234 - stream.pcap__ + +will convert from plain datastream format to a sequence of Ethernet +TCP packets. +-- + +-N <intf-name>:: +Specify a name for the interface included when writing a pcapng format file. + +-o hex|oct|dec|none:: ++ +-- +Specify the radix for the offsets (hex, octal, decimal, or none). Defaults to +hex. This corresponds to the `-A` option for __od__. This parameter has no +effect in regex mode. + +*NOTE:* With __-o none__, only one packet will be created, ignoring any +direction indicators or timestamps after the first byte along with any offsets. +-- + +-P <dissector>:: ++ +-- +Include an EXPORTED_PDU header before each packet. Specify, as a +string, the dissector to be called for the packet (DISSECTOR_NAME tag). +Use this option if your dump is the payload for a single upper layer +protocol (so specifying a link layer type would not work) and you wish +to create a capture file without a full dummy protocol stack. +Automatically sets the link layer type to Wireshark Upper PDU export. +Without this option, if the Upper PDU export link layer type (252) is +selected the dissector defaults to "data". +-- + +-q:: +Don't display the summary of the options selected at the beginning, or the count of packets processed at the end. + +-r <regex>:: ++ +-- +Process the file in regex mode using __regex__ as described above. + +*NOTE:* The regex mode uses memory-mapped I/O and does not work on +streams that do not support seeking, like terminals and pipes. +-- + +-s <srcport>,<destport>,<tag>:: ++ +-- +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. +-- + +-S <srcport>,<destport>,<ppi>:: ++ +-- +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 __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. +-- + +-t <timefmt>:: ++ +-- +Treats the text before the packet as a date/time code; __timefmt__ is a +format string supported by strftime(3), supplemented with the field +descriptor '%f' for fractional seconds up to nanoseconds. +Example: The time "10:15:14.5476" has the format code "%H:%M:%S.%f" +The special format string __ISO__ indicates that the string should be +parsed according to the ISO-8601 specification. This parameter is used +in regex mode if and only if the `<time>` capturing group is present. + +*NOTE:* Date/time fields from the current date/time are +used as the default for unspecified fields. +-- + +-T <srcport>,<destport>:: ++ +-- +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. +-- + +-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 appropriate Ethernet and IP headers +are automatically also included with each packet. +Example: __-u1000,69__ to make the packets look like TFTP/UDP packets. +-- + +-v|--version:: +Print the full version information and exit. + +-4 <srcip>,<destip>:: ++ +-- +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: __-4 10.0.0.1,10.0.0.2__ to use 10.0.0.1 and 10.0.0.2 for all IP packets. +-- + +-6 <srcip>,<destip>:: ++ +-- +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: __-6 2001:db8::b3ff:fe1e:8329,2001:0db8:85a3::8a2e:0370:7334__ to +use 2001:db8::b3ff:fe1e:8329 and 2001:0db8:85a3::8a2e:0370:7334 for all IP packets. +-- + +include::diagnostic-options.adoc[] + +== SEE ALSO + +od(1), xref:https://www.tcpdump.org/manpages/pcap.3pcap.html[pcap](3), xref:wireshark.html[wireshark](1), xref:tshark.html[tshark](1), xref:dumpcap.html[dumpcap](1), xref:mergecap.html[mergecap](1), +xref:editcap.html[editcap](1), strftime(3), xref:https://www.tcpdump.org/manpages/pcap-filter.7.html[pcap-filter](7) or xref:https://www.tcpdump.org/manpages/tcpdump.1.html[tcpdump](8) + +== NOTES + +This is the manual page for *Text2pcap* {wireshark-version}. +*Text2pcap* is part of the *Wireshark* distribution. +The latest version of *Wireshark* can be found at https://www.wireshark.org. + +== AUTHORS + +.Original Author +[%hardbreaks] +Ashok Narayanan <ashokn[AT]cisco.com> |