// WSUG Chapter IO [#ChapterIO] == File Input, Output, And Printing [#ChIOIntroductionSection] === Introduction This chapter will describe input and output of capture data. * Open capture files in various capture file formats * Save and export capture files in various formats * Merge capture files together * Import text files containing hex dumps of packets * Print packets [#ChIOOpenSection] === Open Capture Files Wireshark can read in previously saved capture files. To read them, simply select the menu:File[Open] menu or toolbar item. Wireshark will then pop up the “File Open” dialog box, which is discussed in more detail in <>. [TIP] .You can use drag and drop to open files ==== On most systems you can open a file by simply dragging it in your file manager and dropping it onto Wireshark’s main window. ==== If you haven’t previously saved the current capture file you will be asked to do so to prevent data loss. This warning can be disabled in the preferences. In addition to its native file format (pcapng), Wireshark can read and write capture files from a large number of other packet capture programs as well. See <> for the list of capture formats Wireshark understands. [#ChIOOpen] ==== The “Open Capture File” Dialog Box The “Open Capture File” dialog box allows you to search for a capture file containing previously captured packets for display in Wireshark. The following sections show some examples of the Wireshark “Open File” dialog box. The appearance of this dialog depends on the system. However, the functionality should be the same across systems. Common dialog behavior on all systems: * Select files and directories. * Click the btn:[Open] button to accept your selected file and open it. * Click the btn:[Cancel] button to go back to Wireshark and not load a capture file. * The btn:[Help] button will take you to this section of the “User’s Guide”. Wireshark adds the following controls: * View file preview information such as the size and the number of packets in a selected a capture file. // XXX - we need a better description of these read filters * Specify a read filter with the “Read filter” field. This filter will be used when opening the new file. The text field background will turn green for a valid filter string and red for an invalid one. Read filters can be used to exclude various types of traffic, which can be useful for large capture files. They use the same syntax as display filters, which are discussed in detail in <>. * Optionally force Wireshark to read a file as a particular type using the “Automatically detect file type” drop-down. [#ChIOOpenFileDialogWin32] .“Open” on Microsoft Windows image::wsug_graphics/ws-open-win32.png[{medium-screenshot-attrs}] This is the common Windows file open dialog along with some Wireshark extensions. [#ChIOOpenFileDialog] .“Open” - Linux and UNIX image::wsug_graphics/ws-open-qt5.png[{medium-screenshot-attrs}] This is the common Qt file open dialog along with some Wireshark extensions. // XXX Add macOS [#ChIOInputFormatsSection] ==== Input File Formats The native capture file formats used by Wireshark are: * pcap. The default format used by the _libpcap_ packet capture library. Used by _tcpdump, _Snort_, _Nmap_, _Ntop_, and many other tools. * pcapng. A flexible, extensible successor to the pcap format. Wireshark 1.8 and later save files as pcapng by default. Versions prior to 1.8 used pcap. Used by Wireshark and by _tcpdump_ in newer versions of macOS. The following file formats from other capture tools can be opened by Wireshark: * Oracle (previously Sun) _snoop_ and _atmsnoop_ captures * Finisar (previously Shomiti) _Surveyor_ captures * Microsoft _Network Monitor_ captures * Novell _LANalyzer_ captures * AIX _iptrace_ captures * Cinco Networks NetXray captures * NETSCOUT (previously Network Associates/Network General) Windows-based Sniffer and Sniffer Pro captures * Network General/Network Associates DOS-based Sniffer captures (compressed or uncompressed) captures * LiveAction (previously WildPackets/Savvius) *Peek/EtherHelp/PacketGrabber captures * RADCOM’s WAN/LAN Analyzer captures * Viavi (previously Network Instruments) Observer captures * Lucent/Ascend router debug output * captures from HP-UX nettl * Toshiba’s ISDN routers dump output * output from _i4btrace_ from the ISDN4BSD project * traces from the EyeSDN USB S0 * the IPLog format output from the Cisco Secure Intrusion Detection System * pppd logs (pppdump format) * the output from VMS’s TCPIPtrace/TCPtrace/UCX$TRACE utilities * the text output from the DBS Etherwatch VMS utility * Visual Networks’ Visual UpTime traffic capture * the output from CoSine L2 debug * the output from InfoVista (previously Accellent) 5Views LAN agents * Endace Measurement Systems’ ERF format captures * Linux Bluez Bluetooth stack hcidump -w traces * Catapult (now Ixia/Keysight) DCT2000 .out files * Gammu generated text output from Nokia DCT3 phones in Netmonitor mode * IBM Series (OS/400) Comm traces (ASCII & UNICODE) * Juniper Netscreen snoop captures * Symbian OS btsnoop captures * Tamosoft CommView captures * Tektronix K12xx 32bit .rf5 format captures * Tektronix K12 text file format captures * Apple PacketLogger captures * Captures from Aethra Telecommunications’ PC108 software for their test instruments * Citrix NetScaler Trace files * Android Logcat binary and text format logs * Colasoft Capsa and PacketBuilder captures * Micropross mplog files * Unigraf DPA-400 DisplayPort AUX channel monitor traces * 802.15.4 traces from Daintree's Sensor Network Analyzer * MPEG-2 Transport Streams as defined in ISO/IEC 13818-1 * Log files from the _candump_ utility * Logs from the BUSMASTER tool * Ixia IxVeriWave raw captures * Rabbit Labs CAM Inspector files * _systemd_ journal files * 3GPP TS 32.423 trace files New file formats are added from time to time. It may not be possible to read some formats dependent on the packet types captured. Ethernet captures are usually supported for most file formats but it may not be possible to read other packet types such as PPP or IEEE 802.11 from all file formats. [#ChIOSaveSection] === Saving Captured Packets You can save captured packets by using the menu:File[Save] or menu:File[Save As...] menu items. You can choose which packets to save and which file format to be used. Not all information will be saved in a capture file. For example, most file formats don’t record the number of dropped packets. See <> for details. [#ChIOSaveAs] ==== The “Save Capture File As” Dialog Box The “Save Capture File As” dialog box allows you to save the current capture to a file. The exact appearance of this dialog depends on your system. However, the functionality is the same across systems. Examples are shown below. [#ChIOSaveAsFileWin32] .“Save” on Microsoft Windows image::wsug_graphics/ws-save-as-win32.png[{medium-screenshot-attrs}] This is the common Windows file save dialog with some additional Wireshark extensions. [#ChIOSaveAsFile2] .“Save” on Linux and UNIX image::wsug_graphics/ws-save-as-qt5.png[{medium-screenshot-attrs}] This is the common Qt file save dialog with additional Wireshark extensions. // XXX Add macOS You can perform the following actions: * Type in the name of the file in which you wish to save the captured packets. * Select the directory to save the file into. * Specify the format of the saved capture file by clicking on the “Save as” drop-down box. You can choose from the types described in <>. Some capture formats may not be available depending on the packet types captured. * The btn:[Help] button will take you to this section of the “User’s Guide”. * “Compress with gzip” will compress the capture file as it is being written to disk. * Click the btn:[Save] button to accept your selected file and save it. * Click on the btn:[Cancel] button to go back to Wireshark without saving any packets. If you don’t provide a file extension to the filename (e.g., `.pcap`) Wireshark will append the standard file extension for that file format. [TIP] .Wireshark can convert file formats ==== You can convert capture files from one format to another by opening a capture and saving it as a different format. ==== If you wish to save some of the packets in your capture file you can do so via <>. [#ChIOOutputFormatsSection] ==== Output File Formats Wireshark can save the packet data in its native file format (pcapng) and in the file formats of other protocol analyzers so other tools can read the capture data. [NOTE] .Saving in a different format might lose data ==== Saving your file in a different format might lose information such as comments, name resolution, and time stamp resolution. See <> for more information on time stamps. ==== The following file formats can be saved by Wireshark (with the known file extensions): * pcapng ({asterisk}.pcapng). A flexible, extensible successor to the libpcap format. Wireshark 1.8 and later save files as pcapng by default. Versions prior to 1.8 used libpcap. * pcap ({asterisk}.pcap). The default format used by the _libpcap_ packet capture library. Used by _tcpdump, _Snort_, _Nmap_, _Ntop_, and many other tools. * Accellent 5Views ({asterisk}.5vw) * captures from HP-UX nettl ({asterisktrc0,{asterisk}.trc1) * Microsoft Network Monitor - NetMon ({asterisk}.cap) * Network Associates Sniffer - DOS ({asterisk}.cap,{asterisk}.enc,{asterisk}.trc,{asterisk}.fdc,{asterisk}.syc) * Cinco Networks NetXray captures ({asterisk}.cap) * Network Associates Sniffer - Windows ({asterisk}.cap) * Network Instruments/Viavi Observer ({asterisk}.bfr) * Novell LANalyzer ({asterisk}.tr1) * Oracle (previously Sun) snoop ({asterisk}.snoop,{asterisk}.cap) * Visual Networks Visual UpTime traffic ({asterisk}.{asterisk}) * Symbian OS btsnoop captures ({asterisk}.log) * Tamosoft CommView captures ({asterisk}.ncf) * Catapult (now Ixia/Keysight) DCT2000 .out files ({asterisk}.out) * Endace Measurement Systems’ ERF format capture({asterisk}.erf) * EyeSDN USB S0 traces ({asterisk}.trc) * Tektronix K12 text file format captures ({asterisk}.txt) * Tektronix K12xx 32bit .rf5 format captures ({asterisk}.rf5) * Android Logcat binary logs ({asterisk}.logcat) * Android Logcat text logs ({asterisk}.{asterisk}) * Citrix NetScaler Trace files ({asterisk}.cap) New file formats are added from time to time. Whether or not the above tools will be more helpful than Wireshark is a different question ;-) [NOTE] .Third party protocol analyzers may require specific file extensions ==== Wireshark examines a file’s contents to determine its type. Some other protocol analyzers only look at a file's extension. For example, you might need to use the `.cap` extension in order to open a file using the Windows version of _Sniffer_. ==== [#ChIOMergeSection] === Merging Capture Files Sometimes you need to merge several capture files into one. For example, this can be useful if you have captured simultaneously from multiple interfaces at once (e.g., using multiple instances of Wireshark). There are three ways to merge capture files using Wireshark: * Use the menu:File[Merge] menu to open the “Merge” dialog. See <> for details. This menu item will be disabled unless you have loaded a capture file. * Use _drag and drop_ to drop multiple files on the main window. Wireshark will try to merge the packets in chronological order from the dropped files into a newly created temporary file. If you drop a single file, it will simply replace the existing capture. * Use the `mergecap` tool from the command line to merge capture files. This tool provides the most options to merge capture files. See <> for details. [#ChIOMergeDialog] ==== The “Merge With Capture File” Dialog Box This lets you select a file to be merged into the currently loaded file. If your current data has not been saved you will be asked to save it first. Most controls of this dialog will work the same way as described in the “Open Capture File” dialog box. See <> for details. Specific controls of this merge dialog are: Prepend packets:: Prepend the packets from the selected file before the currently loaded packets. Merge chronologically:: Merge both the packets from the selected and currently loaded file in chronological order. Append packets:: Append the packets from the selected file after the currently loaded packets. [#ChIOMergeFileTab] .“Merge Capture File As” dialog box examples [#ChIOMergeFileWin32] .“Merge” on Microsoft Windows image::wsug_graphics/ws-merge-win32.png[{medium-screenshot-attrs}] This is the common Windows file open dialog with additional Wireshark extensions. [#ChIOMergeFile2] .“Merge” on Linux and UNIX image::wsug_graphics/ws-merge-qt5.png[{medium-screenshot-attrs}] This is the Qt file open dialog with additional Wireshark extensions. // XXX Add macOS [#ChIOImportSection] === Import Hex Dump 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, 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 (i.e., 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. 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. Packets may be preceded by a direction indicator ('I' or 'O') and/or a timestamp if indicated. If both are present, the direction indicator precedes the timestamp. The format of the timestamps must be specified. 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 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. 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.) Here is a sample dump that can be imported, including optional directional indicator and timestamp: ---- I 2019-05-14T19:04:57Z 000000 00 e0 1e a7 05 6f 00 10 ........ 000008 5a a0 b9 12 08 00 46 00 ........ 000010 03 68 00 00 00 00 0a 2e ........ 000018 ee 33 0f 19 08 7f 0f 19 ........ 000020 03 80 94 04 00 00 10 01 ........ 000028 16 a2 0a 00 03 50 00 0c ........ 000030 01 01 0f 19 03 80 11 01 ........ ---- ==== Regular Text Dumps Wireshark is also capable of scanning the input using a custom Perl regular expression as specified by GLib's https://developer-old.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 _exactly_ 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(?