1TEXT2PCAP(1) TEXT2PCAP(1)
2
6 text2pcap - Generate a capture file from an ASCII hexdump of packets
7
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
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 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 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 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 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 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 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 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 Here is a sample dump that text2pcap can recognize, with optional
77 directional indicator and timestamp:
78 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 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 "data" Actual captured frame data to import
95 "time" Timestamp of packet
96 "dir" Direction of packet
97 "seqno" Arbitrary ID of packet
98 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 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 > 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 The regex is compiled with multiline support, and it is recommended to
127 use the anchors '^' and '$' for best results.
128 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 When <infile> or <outfile> are '-', standard input or standard output,
140 respectively, are used.
141
143 -a
144 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 NOTE: Do not enable it if the input file does not contain the ASCII
151 text dump.
152 -b 2|8|16|64
154 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 -D
161 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 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 -e <l3pid>
175 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 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 -E <encapsulation type>
188 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 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 -F <file format>
199 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 -h
205 Displays a help message.
206 -i <proto>
208 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 -l <typenum>
220 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 -m <max-packet>
228 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 od -Ax -tx1 -v stream | text2pcap -m1460 -T1234,1234 - stream.pcap
234 will convert from plain datastream format to a sequence of Ethernet
236 TCP packets.
237 -N <intf-name>
239 Specify a name for the interface included when writing a pcapng
240 format file.
241 -o hex|oct|dec|none
243 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 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 -P <dissector>
253 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 -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 -r <regex>
268 Process the file in regex mode using regex as described above.
270 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 -s <srcport>,<destport>,<tag>
275 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 -S <srcport>,<destport>,<ppi>
285 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 -t <timefmt>
296 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 NOTE: Date/time fields from the current date/time are used as the
307 default for unspecified fields.
308 -T <srcport>,<destport>
310 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 -u <srcport>,<destport>
319 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 -v
329 Print the version and exit.
330 -4 <srcip>,<destip>
332 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 -6 <srcip>,<destip>
340 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
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 --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 --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 --log-debug <list>
368 Force the specified domains to log at the "debug" level. List of
369 domains must be comma-separated.
370 --log-noisy <list>
372 Force the specified domains to log at the "noisy" level. List of
373 domains must be comma-separated.
374 --log-file <path>
376 Write log messages and stderr output to the specified file.
377
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
383 This is the manual page for Text2pcap 4.0.2. Text2pcap is part of the
384 Wireshark distribution. The latest version of Wireshark can be found at
385 https://www.wireshark.org.
386
388 Original Author
389 Ashok Narayanan <ashokn[AT]cisco.com>
390 2022-12-08 TEXT2PCAP(1)