diff --git a/docbook/release-notes.adoc b/docbook/release-notes.adoc index 0fe98cacc0..67454213e1 100644 --- a/docbook/release-notes.adoc +++ b/docbook/release-notes.adoc @@ -50,6 +50,12 @@ They previously shipped with Npcap 1.10. * Wireshark now supports dissecting the rtp packet with OPUS payload. +* Importing captures from text files is now also possible based on regular expressions. By specifying a regex capturing a single + packet including capturing groups for relevant fields a textfile can be converted to a libcap capture file. Supported data + encodings are plain-hexadecimal, -octal, -binary and base64. + Also the timestamp format now allows the second-fractions to be placed anywhere in the timestamp and it will be stored with + nanosecond instead of microsecond precision. + // === Removed Features and Support //=== Removed Dissectors diff --git a/docbook/wsug_graphics/ws-file-import-regex.png b/docbook/wsug_graphics/ws-file-import-regex.png new file mode 100644 index 0000000000..8b680f4920 Binary files /dev/null and b/docbook/wsug_graphics/ws-file-import-regex.png differ diff --git a/docbook/wsug_graphics/ws-file-import.png b/docbook/wsug_graphics/ws-file-import.png index 480193cae9..3edb02de28 100644 Binary files a/docbook/wsug_graphics/ws-file-import.png and b/docbook/wsug_graphics/ws-file-import.png differ diff --git a/docbook/wsug_src/WSUG_chapter_io.adoc b/docbook/wsug_src/WSUG_chapter_io.adoc index da68d59841..04712f9f07 100644 --- a/docbook/wsug_src/WSUG_chapter_io.adoc +++ b/docbook/wsug_src/WSUG_chapter_io.adoc @@ -424,11 +424,17 @@ This is the Qt file open dialog with additional Wireshark extensions. === Import Hex Dump -Wireshark can read in an ASCII hex dump and write the data described into a +Wireshark can read in a hex dump and write the data described into a temporary libpcap capture file. It can read hex dumps with multiple packets in them, and build a capture file of multiple packets. It 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. +Alternatively a Dummy PDU header can be added to specify a dissector the data +should be passed to initially. + +Two methods for converting the input are supported: + +==== Standard ASCII Hexdumps Wireshark understands a hexdump of the form generated by `od -Ax -tx1 -v`. In other words, each byte is individually displayed and surrounded with a space. @@ -461,7 +467,7 @@ 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. If not the first packet is timestamped with the current time the import takes place. Multiple packets are -written with timestamps differing by one microsecond each. In general, short of +written with timestamps differing by one nanosecond each. In general, short of these restrictions, Wireshark 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.) @@ -471,15 +477,85 @@ 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 Wireshark. 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. Wireshark -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. +way it should be processed e.g. timestamps, encapsulation type etc. + +==== Regular Text Dumps + +Wireshark is also capable of scanning the input using a custom perl regular +expression as specified by GLib's https://developer.gnome.org/glib/stable/glib-regex-syntax.html[GRegex here]. +Using a regex capturing a single packet in the given file +wireshark will search the given file from start to the second to last character +(the last character has to be `\n` and is ignored) +for non-overlapping (and non-empty) strings matching the given regex and then +identify the fields to import using named capturing subgroups. Using provided +format information for each field they are then decoded and translated into a +standard libpcap file retaining packet order. + +Note that each named capturing subgroup has to match _exaclty_ once a packet, +but they may be present multiple times in the regex. + +For example the following dump: +---- +> 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 +---- +could be imported using these settings: +---- +regex: ^(?[<>])\s(?