1TEXT2PCAP(1)                                                      TEXT2PCAP(1)
2
3
4

NAME

6       text2pcap - Generate a capture file from an ASCII hexdump of packets
7

SYNOPSIS

9       text2pcap [ -a ] [ -b 2|8|16|64 ] [ -D ] [ -e <l3pid> ]
10       [ -E <encapsulation type> ] [ -F <file format> ] [ -h ] [ -i <proto> ]
11       [ -l <typenum> ] [ -N <intf-name> ] [ -m <max-packet> ]
12       [ -o hex|oct|dec|none ] [ -q ] [ -r <regex> ]
13       [ -s <srcport>,<destport>,<tag> ] [ -S <srcport>,<destport>,<ppi> ]
14       [ -t <timefmt> ] [ -T <srcport>,<destport> ]
15       [ -u <srcport>,<destport> ] [ -v ] [ -4 <srcip>,<destip> ]
16       [ -6 <srcip>,<destip> ] <infile>|- <outfile>|-
17

DESCRIPTION

19       Text2pcap is a program that reads in an ASCII hex dump and writes the
20       data described into a capture file. text2pcap can read hexdumps with
21       multiple packets in them, and build a capture file of multiple packets.
22       Text2pcap is also capable of generating dummy Ethernet, IP, and UDP,
23       TCP or SCTP headers, in order to build fully processable packet dumps
24       from hexdumps of application-level data only.
25
26       Text2pcap can write the file in several output formats. The -F flag can
27       be used to specify the format in which to write the capture file,
28       text2pcap -F provides a list of the available output formats. By
29       default, it writes the packets to outfile in the pcapng file format.
30
31       Text2pcap understands a hexdump of the form generated by od -Ax -tx1
32       -v. In other words, each byte is individually displayed, with spaces
33       separating the bytes from each other. Hex digits can be upper or
34       lowercase.
35
36       In normal operation, each line must begin with an offset describing the
37       position in the packet, followed a colon, space, or tab separating it
38       from the bytes. There is no limit on the width or number of bytes per
39       line, but lines with only hex bytes without a leading offset are
40       ignored (in other words, line breaks should not be inserted in long
41       lines that wrap.) Offsets are more than two digits; they are in hex by
42       default, but can also be in octal or decimal - see -o. Each packet must
43       begin with offset zero, and an offset zero indicates the beginning of a
44       new packet. Offset values must be correct; an unexpected value causes
45       the current packet to be aborted and the next packet start awaited.
46       There is also a single packet mode with no offsets; see -o.
47
48       Packets may be preceded by a direction indicator ('I' or 'O') and/or a
49       timestamp if indicated by the command line (see -D and -t). If both are
50       present, the direction indicator precedes the timestamp. The format of
51       the timestamps is specified as a mandatory parameter to -t. If no
52       timestamp is parsed, in the case of the first packet the current system
53       time is used, while subsequent packets are written with timestamps one
54       microsecond later than that of the previous packet.
55
56       Other text in the input data is ignored. Any text before the offset is
57       ignored, including email forwarding characters '>'. Any text on a line
58       after the bytes is ignored, e.g. an ASCII character dump (but see -a to
59       ensure that hex digits in the character dump are ignored). Any line
60       where the first non-whitespace character is a '#' will be ignored as a
61       comment. Any lines of text between the bytestring lines are considered
62       preamble; the beginning of the preamble is scanned for the direction
63       indicator and timestamp as mentioned above and otherwise ignored.
64
65       Any line beginning with #TEXT2PCAP is a directive and options can be
66       inserted after this command to be processed by text2pcap. Currently
67       there are no directives implemented; in the future, these may be used
68       to give more fine grained control on the dump and the way it should be
69       processed e.g. timestamps, encapsulation type etc.
70
71       In general, short of these restrictions, text2pcap is pretty liberal
72       about reading in hexdumps and has been tested with a variety of mangled
73       outputs (including being forwarded through email multiple times, with
74       limited line wrap etc.)
75
76       Here is a sample dump that text2pcap can recognize, with optional
77       directional indicator and timestamp:
78
79           I 2019-05-14T19:04:57Z
80           000000 00 0e b6 00 00 02 00 0e b6 00 00 01 08 00 45 00
81           000010 00 28 00 00 00 00 ff 01 37 d1 c0 00 02 01 c0 00
82           000020 02 02 08 00 a6 2f 00 01 00 01 48 65 6c 6c 6f 20
83           000030 57 6f 72 6c 64 21
84           000036
85
86       Text2pcap is also capable of scanning a text input file using a custom
87       Perl compatible regular expression that matches a single packet.
88       text2pcap searches the given file (which must end with '\n') for
89       non-overlapping non-empty strings matching the regex. Named capturing
90       subgroups, which must match exactly once per packet, are used to
91       identify fields to import. The following fields are supported in regex
92       mode, one mandatory and three optional:
93
94           "data"  Actual captured frame data to import
95           "time"  Timestamp of packet
96           "dir"   Direction of packet
97           "seqno" Arbitrary ID of packet
98
99       The 'data' field is the captured data, which must be in a selected
100       encoding: hexadecimal (the default), octal, binary, or base64 and
101       containing no characters in the data field outside the encoding set
102       besides whitespace. The 'time' field is parsed according to the format
103       in the -t parameter. The first character of the 'dir' field is compared
104       against a set of characters corresponding to inbound and outbound that
105       default to "iI<" for inbound and "oO>" for outbound to assign a
106       direction. The 'seqno' field is assumed to be a positive integer base
107       10 used for an arbitrary ID. An optional field’s information will only
108       be written if the field is present in the regex and if the capture file
109       format supports it. (E.g., the pcapng format supports all three fields,
110       but the pcap format only supports timestamps.)
111
112       Here is a sample dump that the regex mode can process with the regex
113       '^(?<dir>[<>])\s(?<time>\d+:\d\d:\d\d.\d+)\s(?<data>[0-9a-fA-F]+)$'
114       along with timestamp format '%H:%M:%S.%f', directional indications of
115       '<' and '>', and hex encoding:
116
117           > 0:00:00.265620 a130368b000000080060
118           > 0:00:00.280836 a1216c8b00000000000089086b0b82020407
119           < 0:00:00.295459 a2010800000000000000000800000000
120           > 0:00:00.296982 a1303c8b00000008007088286b0bc1ffcbf0f9ff
121           > 0:00:00.305644 a121718b0000000000008ba86a0b8008
122           < 0:00:00.319061 a2010900000000000000001000600000
123           > 0:00:00.330937 a130428b00000008007589186b0bb9ffd9f0fdfa3eb4295e99f3aaffd2f005
124           > 0:00:00.356037 a121788b0000000000008a18
125
126       The regex is compiled with multiline support, and it is recommended to
127       use the anchors '^' and '$' for best results.
128
129       Text2pcap also allows the user to read in dumps of application-level
130       data and insert dummy L2, L3 and L4 headers before each packet. This
131       allows Wireshark or any other full-packet decoder to handle these
132       dumps. If the encapsulation type is Ethernet, the user can elect to
133       insert Ethernet headers, Ethernet and IP, or Ethernet, IP and
134       UDP/TCP/SCTP headers before each packet. The fake headers can also be
135       used with the Raw IP, Raw IPv4, or Raw IPv6 encapsulations, with the
136       Ethernet header omitted. These encapsulation options can be used in
137       both hexdump mode and regex mode.
138
139       When <infile> or <outfile> are '-', standard input or standard output,
140       respectively, are used.
141

OPTIONS

143       -a
144
145           Enables ASCII text dump identification. It allows one to identify
146           the start of the ASCII text dump and not include it in the packet
147           even if it looks like HEX. This parameter has no effect in regex
148           mode.
149
150           NOTE: Do not enable it if the input file does not contain the ASCII
151           text dump.
152
153       -b 2|8|16|64
154
155           Specify the base (radix) of the encoding of the packet data in
156           regex mode. The supported options are 2 (binary), 8 (octal), 16
157           (hexadecimal), and 64 (base64 encoding), with hex as the default.
158           This parameter has no effect in hexdump mode.
159
160       -D
161
162           Indicates that the text before each input packet may start either
163           with an I or O indicating that the packet is inbound or outbound.
164           If both this flag and the t flag are used, the directional
165           indicator is expected before the time code. This parameter has no
166           effect in regex mode, where the presence of the <dir> capturing
167           group determines whether direction indicators are expected.
168
169           Direction indication is stored in the packet headers if the output
170           format supports it (e.g. pcapng), and is also used when generating
171           dummy headers to swap the source and destination addresses and
172           ports as appropriate.
173
174       -e <l3pid>
175
176           Include a dummy Ethernet header before each packet. Specify the
177           L3PID for the Ethernet header in hex. Use this option if your dump
178           has Layer 3 header and payload (e.g. IP header), but no Layer 2
179           encapsulation. Example: -e 0x806 to specify an ARP packet.
180
181           For IP packets, instead of generating a fake Ethernet header you
182           can also use -E rawip or -l 101 to indicate raw IP encapsulation.
183           Note that raw IP encapsulation does not work for any non-IP Layer 3
184           packet (e.g. ARP), whereas generating a dummy Ethernet header with
185           -e works for any sort of L3 packet.
186
187       -E <encapsulation type>
188
189           Sets the packet encapsulation type of the output capture file.
190           text2pcap -E provides a list of the available types; note that not
191           all file formats support all encapsulation types. The default type
192           is ether (Ethernet).
193
194           NOTE: This sets the encapsulation type of the output file, but does
195           not translate the packet headers or add additional headers. It is
196           used to specify the encapsulation that matches the input data.
197
198       -F <file format>
199
200           Sets the file format of the output capture file. Text2pcap can
201           write the file in several formats; text2pcap -F provides a list of
202           the available output formats. The default is the pcapng format.
203
204       -h
205           Displays a help message.
206
207       -i <proto>
208
209           Include dummy IP headers before each packet. Specify the IP
210           protocol for the packet in decimal. Use this option if your dump is
211           the payload of an IP packet (i.e. has complete L4 information) but
212           does not have an IP header with each packet. Note that an
213           appropriate Ethernet header is automatically included with each
214           packet as well if the link-layer type is Ethernet. Example: -i 46
215           to specify an RSVP packet (IP protocol 46). See
216           https://www.iana.org/assignments/protocol-numbers/protocol-numbers.xhtml
217           for the complete list of assigned internet protocol numbers.
218
219       -l <typenum>
220
221           Sets the packet encapsulation type of the output capture file,
222           using pcap link-layer header type numbers. Default is Ethernet (1).
223           See https://www.tcpdump.org/linktypes.html for the complete list of
224           possible encapsulations. Example: -l 7 for ARCNet packets
225           encapsulated BSD-style.
226
227       -m <max-packet>
228
229           Set the maximum packet length, default is 262144. Useful for
230           testing various packet boundaries when only an application level
231           datastream is available. Example:
232
233           od -Ax -tx1 -v stream | text2pcap -m1460 -T1234,1234 - stream.pcap
234
235           will convert from plain datastream format to a sequence of Ethernet
236           TCP packets.
237
238       -N <intf-name>
239           Specify a name for the interface included when writing a pcapng
240           format file.
241
242       -o hex|oct|dec|none
243
244           Specify the radix for the offsets (hex, octal, decimal, or none).
245           Defaults to hex. This corresponds to the -A option for od. This
246           parameter has no effect in regex mode.
247
248           NOTE: With -o none, only one packet will be created, ignoring any
249           direction indicators or timestamps after the first byte along with
250           any offsets.
251
252       -P <dissector>
253
254           Include an EXPORTED_PDU header before each packet. Specify, as a
255           string, the dissector to be called for the packet (DISSECTOR_NAME
256           tag). Use this option if your dump is the payload for a single
257           upper layer protocol (so specifying a link layer type would not
258           work) and you wish to create a capture file without a full dummy
259           protocol stack. Automatically sets the link layer type to Wireshark
260           Upper PDU export. Without this option, if the Upper PDU export link
261           layer type (252) is selected the dissector defaults to "data".
262
263       -q
264           Don’t display the summary of the options selected at the beginning,
265           or the count of packets processed at the end.
266
267       -r <regex>
268
269           Process the file in regex mode using regex as described above.
270
271           NOTE: The regex mode uses memory-mapped I/O and does not work on
272           streams that do not support seeking, like terminals and pipes.
273
274       -s <srcport>,<destport>,<tag>
275
276           Include dummy SCTP headers before each packet. Specify, in decimal,
277           the source and destination SCTP ports, and verification tag, for
278           the packet. Use this option if your dump is the SCTP payload of a
279           packet but does not include any SCTP, IP or Ethernet headers. Note
280           that appropriate Ethernet and IP headers are automatically also
281           included with each packet. A CRC32C checksum will be put into the
282           SCTP header.
283
284       -S <srcport>,<destport>,<ppi>
285
286           Include dummy SCTP headers before each packet. Specify, in decimal,
287           the source and destination SCTP ports, and a verification tag of 0,
288           for the packet, and prepend a dummy SCTP DATA chunk header with a
289           payload protocol identifier if ppi. Use this option if your dump is
290           the SCTP payload of a packet but does not include any SCTP, IP or
291           Ethernet headers. Note that appropriate Ethernet and IP headers are
292           automatically included with each packet. A CRC32C checksum will be
293           put into the SCTP header.
294
295       -t <timefmt>
296
297           Treats the text before the packet as a date/time code; timefmt is a
298           format string supported by strftime(3), supplemented with the field
299           descriptor '%f' for fractional seconds up to nanoseconds. Example:
300           The time "10:15:14.5476" has the format code "%H:%M:%S.%f" The
301           special format string ISO indicates that the string should be
302           parsed according to the ISO-8601 specification. This parameter is
303           used in regex mode if and only if the <time> capturing group is
304           present.
305
306           NOTE: Date/time fields from the current date/time are used as the
307           default for unspecified fields.
308
309       -T <srcport>,<destport>
310
311           Include dummy TCP headers before each packet. Specify the source
312           and destination TCP ports for the packet in decimal. Use this
313           option if your dump is the TCP payload of a packet but does not
314           include any TCP, IP or Ethernet headers. Note that appropriate
315           Ethernet and IP headers are automatically also included with each
316           packet. Sequence numbers will start at 0.
317
318       -u <srcport>,<destport>
319
320           Include dummy UDP headers before each packet. Specify the source
321           and destination UDP ports for the packet in decimal. Use this
322           option if your dump is the UDP payload of a packet but does not
323           include any UDP, IP or Ethernet headers. Note that appropriate
324           Ethernet and IP headers are automatically also included with each
325           packet. Example: -u1000,69 to make the packets look like TFTP/UDP
326           packets.
327
328       -v
329           Print the version and exit.
330
331       -4 <srcip>,<destip>
332
333           Prepend dummy IP header with specified IPv4 dest and source
334           address. This option should be accompanied by one of the following
335           options: -i, -s, -S, -T, -u Use this option to apply "custom" IP
336           addresses. Example: -4 10.0.0.1,10.0.0.2 to use 10.0.0.1 and
337           10.0.0.2 for all IP packets.
338
339       -6 <srcip>,<destip>
340
341           Prepend dummy IP header with specified IPv6 dest and source
342           address. This option should be accompanied by one of the following
343           options: -i, -s, -S, -T, -u Use this option to apply "custom" IP
344           addresses. Example: -6
345           2001:db8::b3ff:fe1e:8329,2001:0db8:85a3::8a2e:0370:7334 to use
346           2001:db8::b3ff:fe1e:8329 and 2001:0db8:85a3::8a2e:0370:7334 for all
347           IP packets.
348

DIAGNOSTIC OPTIONS

350       --log-level <level>
351           Set the active log level. Supported levels in lowest to highest
352           order are "noisy", "debug", "info", "message", "warning",
353           "critical", and "error". Messages at each level and higher will be
354           printed, for example "warning" prints "warning", "critical", and
355           "error" messages and "noisy" prints all messages. Levels are case
356           insensitive.
357
358       --log-fatal <level>
359           Abort the program if any messages are logged at the specified level
360           or higher. For example, "warning" aborts on any "warning",
361           "critical", or "error" messages.
362
363       --log-domains <list>
364           Only print messages for the specified log domains, e.g.
365           "GUI,Epan,sshdump". List of domains must be comma-separated.
366
367       --log-debug <list>
368           Force the specified domains to log at the "debug" level. List of
369           domains must be comma-separated.
370
371       --log-noisy <list>
372           Force the specified domains to log at the "noisy" level. List of
373           domains must be comma-separated.
374
375       --log-file <path>
376           Write log messages and stderr output to the specified file.
377

SEE ALSO

379       od(1), pcap(3), wireshark(1), tshark(1), dumpcap(1), mergecap(1),
380       editcap(1), strftime(3), pcap-filter(7) or tcpdump(8)
381

NOTES

383       This is the manual page for Text2pcap 4.0.8. Text2pcap is part of the
384       Wireshark distribution. The latest version of Wireshark can be found at
385       https://www.wireshark.org.
386

AUTHORS

388       Original Author
389       Ashok Narayanan <ashokn[AT]cisco.com>
390
391
392
393                                  2023-08-31                      TEXT2PCAP(1)
Impressum