diff options
| -rw-r--r-- | README.cmake | 3 | ||||
| -rw-r--r-- | docbook/CMakeLists.txt | 6 | ||||
| -rw-r--r-- | docbook/Makefile.common | 6 | ||||
| -rw-r--r-- | docbook/user-guide.xml | 3 | ||||
| -rw-r--r-- | docbook/wsug_graphics/ws-merge-gtk20.png | bin | 25097 -> 0 bytes | |||
| -rw-r--r-- | docbook/wsug_graphics/ws-open-gtk20.png | bin | 23914 -> 0 bytes | |||
| -rw-r--r-- | docbook/wsug_graphics/ws-save-as-gtk20.png | bin | 47397 -> 0 bytes | |||
| -rw-r--r-- | docbook/wsug_src/WSUG_chapter_io.asciidoc | 928 | ||||
| -rw-r--r-- | docbook/wsug_src/WSUG_chapter_io.xml | 1482 |
9 files changed, 935 insertions, 1493 deletions
diff --git a/README.cmake b/README.cmake index ca9216e370..14e1bde5d5 100644 --- a/README.cmake +++ b/README.cmake @@ -47,6 +47,9 @@ Note 1: # Disable GTK+ 3 -DENABLE_GTK3=OFF + # Build documentation + -DENABLE_GUIDES=ON + # Make ccache and clang work together -DCMAKE_C_FLAGS='-Qunused-arguments' diff --git a/docbook/CMakeLists.txt b/docbook/CMakeLists.txt index c2e1e0de00..3b6c0d564c 100644 --- a/docbook/CMakeLists.txt +++ b/docbook/CMakeLists.txt @@ -42,7 +42,7 @@ set(WSUG_FILES WSUG_chapter_capture.xml wsug_src/WSUG_chapter_customize.xml WSUG_chapter_introduction.xml - wsug_src/WSUG_chapter_io.xml + WSUG_chapter_io.xml WSUG_chapter_statistics.xml wsug_src/WSUG_chapter_telephony.xml wsug_src/WSUG_chapter_troubleshoot.xml @@ -58,6 +58,7 @@ set(WSDG_ASCIIDOC_FILES wsug_src/WSUG_chapter_build_install.asciidoc wsug_src/WSUG_chapter_capture.asciidoc wsug_src/WSUG_chapter_introduction.asciidoc + wsug_src/WSUG_chapter_io.asciidoc wsug_src/WSUG_chapter_statistics.asciidoc wsug_src/WSUG_chapter_use.asciidoc wsug_src/WSUG_preface.asciidoc @@ -121,11 +122,9 @@ set(WSUG_GRAPHICS wsug_graphics/ws-main-toolbar.png wsug_graphics/ws-main.png wsug_graphics/ws-menu.png - wsug_graphics/ws-merge-gtk20.png wsug_graphics/ws-merge-gtk24.png wsug_graphics/ws-merge-win32.png wsug_graphics/ws-nameresolution-preferences.png - wsug_graphics/ws-open-gtk20.png wsug_graphics/ws-open-gtk24.png wsug_graphics/ws-open-win32.png wsug_graphics/ws-packet-format.png @@ -135,7 +134,6 @@ set(WSUG_GRAPHICS wsug_graphics/ws-packet-sep-win.png wsug_graphics/ws-print.png wsug_graphics/ws-printing-preferences.png - wsug_graphics/ws-save-as-gtk20.png wsug_graphics/ws-save-as-gtk24.png wsug_graphics/ws-save-as-win32.png wsug_graphics/ws-statistics-menu.png diff --git a/docbook/Makefile.common b/docbook/Makefile.common index 746aca2bda..98b8d008f7 100644 --- a/docbook/Makefile.common +++ b/docbook/Makefile.common @@ -11,7 +11,7 @@ WSUG_FILES = \ wsug_src/WSUG_chapter_capture.asciidoc \ wsug_src/WSUG_chapter_customize.xml \ wsug_src/WSUG_chapter_introduction.asciidoc \ - wsug_src/WSUG_chapter_io.xml \ + wsug_src/WSUG_chapter_io.asciidoc \ wsug_src/WSUG_chapter_statistics.asciidoc \ wsug_src/WSUG_chapter_telephony.xml \ wsug_src/WSUG_chapter_troubleshoot.xml \ @@ -26,6 +26,7 @@ WSUG_GENERATED_SOURCE = \ wsug_src/WSUG_chapter_build_install.xml \ wsug_src/WSUG_chapter_capture.xml \ wsug_src/WSUG_chapter_introduction.xml \ + wsug_src/WSUG_chapter_io.xml \ wsug_src/WSUG_chapter_statistics.xml \ wsug_src/WSUG_chapter_use.xml \ wsug_src/WSUG_preface.xml @@ -97,11 +98,9 @@ WSUG_GRAPHICS = \ wsug_graphics/ws-main-toolbar.png \ wsug_graphics/ws-main.png \ wsug_graphics/ws-menu.png \ - wsug_graphics/ws-merge-gtk20.png \ wsug_graphics/ws-merge-gtk24.png \ wsug_graphics/ws-merge-win32.png \ wsug_graphics/ws-nameresolution-preferences.png \ - wsug_graphics/ws-open-gtk20.png \ wsug_graphics/ws-open-gtk24.png \ wsug_graphics/ws-open-win32.png \ wsug_graphics/ws-packet-format.png \ @@ -111,7 +110,6 @@ WSUG_GRAPHICS = \ wsug_graphics/ws-packet-sep-win.png \ wsug_graphics/ws-print.png \ wsug_graphics/ws-printing-preferences.png \ - wsug_graphics/ws-save-as-gtk20.png \ wsug_graphics/ws-save-as-gtk24.png \ wsug_graphics/ws-save-as-win32.png \ wsug_graphics/ws-statistics-menu.png \ diff --git a/docbook/user-guide.xml b/docbook/user-guide.xml index b08a9970d7..84d2a41b88 100644 --- a/docbook/user-guide.xml +++ b/docbook/user-guide.xml @@ -283,9 +283,6 @@ FILE SECTION <!ENTITY WiresharkCaptureOptionsRemoteSettingsDialog SYSTEM "./wsug_graphics/ws-capture-options-remote-settings.png" NDATA PNG> <!-- Fifth Chapter --> - <!ENTITY WiresharkOpenDialog20 SYSTEM "./wsug_graphics/ws-open-gtk20.png" NDATA PNG> - <!ENTITY WiresharkSaveAsDialog20 SYSTEM "./wsug_graphics/ws-save-as-gtk20.png" NDATA PNG> - <!ENTITY WiresharkMergeDialog20 SYSTEM "./wsug_graphics/ws-merge-gtk20.png" NDATA PNG> <!ENTITY WiresharkOpenDialog24 SYSTEM "./wsug_graphics/ws-open-gtk24.png" NDATA PNG> <!ENTITY WiresharkSaveAsDialog24 SYSTEM "./wsug_graphics/ws-save-as-gtk24.png" NDATA PNG> <!ENTITY WiresharkMergeDialog24 SYSTEM "./wsug_graphics/ws-merge-gtk24.png" NDATA PNG> diff --git a/docbook/wsug_graphics/ws-merge-gtk20.png b/docbook/wsug_graphics/ws-merge-gtk20.png Binary files differdeleted file mode 100644 index 3c21c09e47..0000000000 --- a/docbook/wsug_graphics/ws-merge-gtk20.png +++ /dev/null diff --git a/docbook/wsug_graphics/ws-open-gtk20.png b/docbook/wsug_graphics/ws-open-gtk20.png Binary files differdeleted file mode 100644 index 63eabc4618..0000000000 --- a/docbook/wsug_graphics/ws-open-gtk20.png +++ /dev/null diff --git a/docbook/wsug_graphics/ws-save-as-gtk20.png b/docbook/wsug_graphics/ws-save-as-gtk20.png Binary files differdeleted file mode 100644 index c0d45046e2..0000000000 --- a/docbook/wsug_graphics/ws-save-as-gtk20.png +++ /dev/null diff --git a/docbook/wsug_src/WSUG_chapter_io.asciidoc b/docbook/wsug_src/WSUG_chapter_io.asciidoc new file mode 100644 index 0000000000..adaf72a65c --- /dev/null +++ b/docbook/wsug_src/WSUG_chapter_io.asciidoc @@ -0,0 +1,928 @@ +++++++++++++++++++++++++++++++++++++++ +<!-- 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/Export capture files in various capture file 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 <<ChIOOpen>>. + +[TIP] +.It's convenient to use drag-and-drop +==== +You can open a file by simply dragging it in your file manager and dropping it +onto Wireshark's main window. However, drag-and-drop may not be available in all +desktop environments. +==== + +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 +<<ChIOInputFormatsSection>> 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 behaviour on all systems: + +* Select files and directories. + +* Click the button:[Open] or button:[OK] button to accept your selected file and + open it. + +* Click the button:[Cancel] button to go back to Wireshark and not load a capture file. + +Wireshark extensions to the standard behaviour of these dialogs: + +* View file preview information such as the filesize and the number of packets + in a selected a capture file. + +* Specify a display filter with the button:[Filter] button and filter field. + This filter will be used when opening the new file. The text field background + becomes green for a valid filter string and red for an invalid one. Clicking + on the button:[Filter] button causes Wireshark to pop up the ``Filters'' + dialog box (which is discussed further in <<ChWorkDisplayFilterSection>>). ++ +// XXX - we need a better description of these read filters + +* Specify which type of name resolution is to be performed for all packets by + clicking on one of the ``... name resolution'' check buttons. Details about name + resolution can be found in <<ChAdvNameResolutionSection>>. + +[TIP] +.Save a lot of time loading huge capture files +==== +You can change the display filter and name resolution settings later while +viewing the packets. However, loading huge capture files can take a significant +amount of extra time if these settings are changed later, so in such situations +it can be a good idea to set at least the filter in advance here. +==== + +[[ChIOOpenFileDialogWin32]] + +.``Open'' on Microsoft Windows +image::wsug_graphics/ws-open-win32.png[] + +This is the common Windows file open dialog - plus some Wireshark extensions. + +Specific for this dialog: + +* The button:[Help] button will lead you to this section of this ``User's Guide''. + +[[ChIOOpenFileDialog]] + +.``Open'' - Linux and UNIX +image::wsug_graphics/ws-open-gtk24.png[] + +This is the common Gimp/GNOME file open dialog plus some Wireshark extensions. + +Specific for this dialog: + +* The button:[+] button allows you to add a directory selected in the + right-hand pane to the favorites list on the left. These changes are + persistent. + +* The button:[-] button allows you to remove a selected directory from the list. + Some items (such as ``Desktop'') cannot be removed from the favorites list. + +* If Wireshark doesn't recognize the selected file as a capture file it will + grey out the button:[Open] button. + +// XXX Add OS X + + +[[ChIOInputFormatsSection]] + + +==== Input File Formats + +The following file formats from other capture tools can be opened by Wireshark: + +* pcapng. A flexible, etensible successor to the libpcap format. Wireshark 1.8 and later + save files as pcapng by default. Versions prior to 1.8 used libpcap. + +* libpcap. The default format used by the _libpcap_ packet capture library. Used + by _tcpdump, _Snort_, _Nmap_, _Ntop_, and many other tools. + +* Oracle (previously Sun) _snoop_ and _atmsnoop_ + +* Finisar (previously Shomiti) _Surveyor_ captures + +* Microsoft _Network Monitor_ captures + +* Novell _LANalyzer_ captures + +* AIX _iptrace_ captures + +* Cinco Networks NetXray captures + +* Network Associates Windows-based Sniffer and Sniffer Pro captures + +* Network General/Network Associates DOS-based Sniffer (compressed or uncompressed) captures + +* AG Group/WildPackets EtherPeek/TokenPeek/AiroPeek/EtherHelp/PacketGrabber captures + +* RADCOM's WAN/LAN Analyzer captures + +* Network Instruments Observer version 9 captures + +* Lucent/Ascend router debug output + +* HP-UX's nettl + +* Toshiba's ISDN routers dump output + +* ISDN4BSD _i4btrace_ utility + +* traces from the EyeSDN USB S0 + +* IPLog format 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 Accellent's 5Views LAN agents + +* Endace Measurement Systems' ERF format captures + +* Linux Bluez Bluetooth stack hcidump -w traces + +* Catapult 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 + +* Textronix K12xx 32bit .rf5 format captures + +* Textronix K12 text file format captures + +* Apple PacketLogger captures + +* Captures from Aethra Telecommunications' PC108 software for their test instruments + +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 simply by using the menu:File[Save As...] menu +item. 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 +<<ChAppFilesCaptureFilesSection>> 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 following sections show some examples of this dialog box. The +appearance of this dialog depends on the system. However, the functionality +should be the same across systems. + +[[ChIOSaveAsFileWin32]] + +.``Save'' on Microsoft Windows +image::wsug_graphics/ws-save-as-win32.png[] + +This is the common Windows file save dialog with some additional Wireshark extensions. + +Specific behavior for this dialog: + +* If available, the ``Help'' button will lead you to this section of this "User's Guide". + +* 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. + +[[ChIOSaveAsFile2]] + +.``Save'' on Linux and UNIX +image::wsug_graphics/ws-save-as-gtk24.png[] + +This is the common Gimp/GNOME file save dialog with additional Wireshark extensions. + +Specific for this dialog: + +* Clicking on the + at "Browse for other folders" will allow you to browse files and folders in your file system. + +// XXX Add OS X + +With this dialog box, you can perform the following actions: + +. Type in the name of the file you wish to save the captured packets in, as a + standard file name in your file system. + +. Select the directory to save the file into. + +. Select the range of the packets to be saved. See <<ChIOPacketRangeSection>>. + +. Specify the format of the saved capture file by clicking on the File type drop + down box. You can choose from the types described in + <<ChIOOutputFormatsSection>>. + +Some capture formats may not be available depending on the packet types captured. + +[TIP] +.Wireshark can convert file formats +==== +You can convert capture files from one format to another by reading in a capture +file and writing it out using a different format. +==== + +. Click the button:[Save] or button:[OK] button to accept your selected file and + save to it. If Wireshark has a problem saving the captured packets to the file + you specified it will display an error dialog box. After clicking button:[OK] + on that error dialog box you can try again. + +. Click on the button:[Cancel] button to go back to Wireshark without saving any + packets. + +[[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. + + +[WARNING] +.Different file formats have different time stamp accuracies +==== +Saving from the currently used file format to a different format may reduce the +time stamp accuracy; see the <<ChAdvTimestamps>> for details. +==== + +The following file formats can be saved by Wireshark (with the known file extensions): + +* pcapng ($$*$$.pcapng). A flexible, etensible successor to the libpcap format. + Wireshark 1.8 and later save files as pcapng by default. Versions prior to 1.8 + used libpcap. + +* libpcap, tcpdump and various other tools using tcpdump's capture format ($$*$$.pcap,$$*$$.cap,$$*$$.dmp) + +* Accellent 5Views ($$*$$.5vw) + +* HP-UX's nettl ($$*$$.TRC0,$$*$$.TRC1) + +* Microsoft Network Monitor - NetMon ($$*$$.cap) + +* Network Associates Sniffer - DOS ($$*$$.cap,$$*$$.enc,$$*$$.trc,*fdc,$$*$$.syc) + +* Network Associates Sniffer - Windows ($$*$$.cap) + +* Network Instruments Observer version 9 ($$*$$.bfr) + +* Novell LANalyzer ($$*$$.tr1) + +* Oracle (previously Sun) snoop ($$*$$.snoop,$$*$$.cap) + +* Visual Networks Visual UpTime traffic ($$*.*$$) + +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 filename extensions. For example, you might need to use +the `.cap` extension in order to open a file using _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 + <<ChIOMergeDialog>>. 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 only a single file it will simply + replace the existing capture. + +* Use the `mergecap` tool, a command line tool to merge capture files. + This tool provides the most options to merge capture files. See + <<AppToolsmergecap>> for details. + +[[ChIOMergeDialog]] + +==== The ``Merge with Capture File'' dialog box + +This dialog box let 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 <<ChIOOpen>>. + +Specific controls of this merge dialog are: + +_Prepend packets to existing file_:: +Prepend the packets from the selected file before the currently loaded packets. + +_Merge packets chronologically_:: +Merge both the packets from the selected and currently loaded file in chronological order. + +_Append packets to existing file_:: +Append the packets from the selected file after the currently loaded packets. + + +[[ChIOMergeFileTab]] + +.The system specific ``Merge Capture File As'' dialog box + +[[ChIOMergeFileWin32]] + +.``Merge'' on Microsoft Windows +image::wsug_graphics/ws-merge-win32.png[] + +This is the common Windows file open dialog with additional Wireshark extensions. + +[[ChIOMergeFile2]] + +.``Merge'' on Linux and UNIX +image::wsug_graphics/ws-merge-gtk24.png[] + +This is the common Gimp/GNOME file open dialog with additional Wireshark extensions. + + +[[ChIOImportSection]] + +=== Import hex dump + +Wireshark can read in an ASCII 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. + +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. +Each line begins with an offset describing the position in the file. The offset +is a hex number (can also be octal or decimal), of more than two hex digits. +Here is a sample dump that can be imported: + +---- +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 ........ +---- + +There is no limit on the width or number of bytes per line. Also the text dump +at the end of the line is ignored. Byte and hex numbers can be uppercase or +lowercase. Any text before the offset is ignored, including email forwarding +characters '>'. Any lines of text between the bytestring lines are ignored. +The offsets are used to track the bytes, so offsets must be correct. Any line +which has only bytes without a leading offset is ignored. An offset is +recognized as being a hex number longer than two characters. Any text after the +bytes is ignored (e.g. the character dump). Any hex numbers in this text are +also ignored. An offset of zero is indicative of starting a new packet, so a +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 +read in with timestamps differing by one microsecond 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.) + +There are a couple of other special features to note. Any line where the first +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. + +[[ChIOImportDialog]] + +==== The ``Import from Hex Dump'' dialog box + +This dialog box lets you select a text file, containing a hex dump of packet +data, to be imported and set import parameters. + +[[ChIOFileImportDialog]] + +.The ``Import from Hex Dump'' dialog +image::wsug_graphics/ws-file-import.png[] + +Specific controls of this import dialog are split in two sections: + +Input:: Determine which input file has to be imported and how it is to be +interpreted. + +Import:: Determine how the data is to be imported. + +The input parameters are as follows: + +_Filename / Browse_:: +Enter the name of the text file to import. You can use _Browse_ to browse for a +file. + +_Offsets_:: +Select the radix of the offsets given in the text file to import. This is +usually hexadecimal, but decimal and octal are also supported. + +_Date/Time_:: +Tick this checkbox if there are timestamps associated with the frames in the +text file to import you would like to use. Otherwise the current time is used +for timestamping the frames. + +_Format_:: +This is the format specifier used to parse the timestamps in the text file to +import. It uses a simple syntax to describe the format of the timestamps, using +%H for hours, %M for minutes, %S for seconds, etc. The straightforward HH:MM:SS +format is covered by %T. For a full definition of the syntax look for +`strptime(3)`. + +The import parameters are as follows: + +_Encapsulation type_:: +Here you can select which type of frames you are importing. This all depends on +from what type of medium the dump to import was taken. It lists all types that +Wireshark understands, so as to pass the capture file contents to the right +dissector. + +_Dummy header_:: +When Ethernet encapsulation is selected you have to option to prepend dummy +headers to the frames to import. These headers can provide artificial Ethernet, +IP, UDP or TCP or SCTP headers and SCTP data chunks. When selecting a type of +dummy header the applicable entries are enabled, others are grayed out and +default values are used. + +_Maximum frame length_:: +You may not be interested in the full frames from the text file, just the first +part. Here you can define how much data from the start of the frame you want to +import. If you leave this open the maximum is set to 65535 bytes. + +Once all input and import parameters are setup click button:[OK] to start the +import. If your current data wasn't saved before you will be asked to save it +first. + +When completed there will be a new capture file loaded with the frames imported +from the text file. + +[[ChIOFileSetSection]] + +=== File Sets + +When using the "Multiple Files" option while doing a capture (see: +<<ChCapCaptureFiles>>), the capture data is spread over several capture files, +called a file set. + +As it can become tedious to work with a file set by hand, Wireshark provides +some features to handle these file sets in a convenient way. + +.How does Wireshark detect the files of a file set? +**** +A filename in a file set uses the format Prefix_Number_DateTimeSuffix which +might look something like `test_00001_20060420183910.pcap`. All files of a file +set share the same prefix (e.g. ``test'') and suffix (e.g. ``.pcap'') and a +varying middle part. + +To find the files of a file set, Wireshark scans the directory where the +currently loaded file resides and checks for files matching the filename pattern +(prefix and suffix) of the currently loaded file. + +This simple mechanism usually works well but has its drawbacks. If several file +sets were captured with the same prefix and suffix, Wireshark will detect them +as a single file set. If files were renamed or spread over several directories +the mechanism will fail to find all files of a set. +**** + +The following features in the menu:File[File Set] submenu are available to work +with file sets in a convenient way: + +* The ``List Files'' dialog box will list the files Wireshark has recognized as + being part of the current file set. + +* button:[Next File] closes the current and opens the next file in the file + set. + +* button:[Previous File] closes the current and opens the previous file in the + file set. + +[[ChIOFileSetListDialog]] + +==== The ``List Files'' dialog box + +.The "List Files" dialog box +image::wsug_graphics/ws-file-set-dialog.png[] + +Each line contains information about a file of the file set: + +* _Filename_ the name of the file. If you click on the filename (or the radio + button left to it), the current file will be closed and the corresponding + capture file will be opened. + +* _Created_ the creation time of the file + +* _Last Modified_ the last time the file was modified + +* _Size_ the size of the file + +The last line will contain info about the currently used directory where all of +the files in the file set can be found. + +The content of this dialog box is updated each time a capture file is +opened/closed. + +The button:[Close] button will, well, close the dialog box. + +[[ChIOExportSection]] + +=== Exporting data + +Wireshark provides several ways and formats to export packet data. This section +describes general ways to export data from the main Wireshark application. There +are more specialized functions to export specific data which are described +elsewhere. + +// XXX - add detailed descriptions of the output formats and some sample output, too. + +// XXX Most of this content is no longer relevant in the current GTK+ UI, much less Qt. + +[[ChIOExportPlainDialog]] + +==== The ``Export as Plain Text File'' dialog box + +[[ChIOExportPlain]] + +Export packet data into a plain ASCII text file, much like the format used to print packets. + +[TIP] +==== +If you would like to be able to import any previously exported packets from a +plain text file it is recommended that you: + +* Add the ``Absolute date and time'' column. + +* Temporarily hide all other columns. + +* Disable the menu:Edit[Preferences,Protocols,Data] ``Show not dissected data + on new Packet Bytes pane'' preference. More details are provided in + <<ChCustPreferencesSection>> + +* Include the packet summary line. + +* Exclude column headings. + +* Exclude packet details. + +* Include the packet bytes. +==== + +.The ``Export as Plain Text File'' dialog box +image::wsug_graphics/ws-export-plain.png[] + +* The ``Export to file:'' frame chooses the file to export the packet data to. + +* The ``Packet Range'' frame is described in <<ChIOPacketRangeSection>>. + +* The ``Packet Details'' frame is described in <<ChIOPacketFormatSection>>. + +[[ChIOExportPSDialog]] + +==== The ``Export as PostScript File'' dialog box + +.The "Export as PostScript File" dialog box +image::wsug_graphics/ws-export-ps.png[] + +* _Export to file:_ frame chooses the file to export the packet data to. + +* The _Packet Range_ frame is described in <<ChIOPacketRangeSection>>. + +* The _Packet Details_ frame is described in <<ChIOPacketFormatSection>>. + +[[ChIOExportCSVDialog]] + +==== The "Export as CSV (Comma Separated Values) File" dialog box + +// XXX - add screenshot + +Export packet summary into CSV, used e.g. by spreadsheet programs to im-/export data. + +//<!--<figure> +// <title>The "Export as Comma Separated Values File" dialog box</title> +// <graphic entityref="WiresharkExportCSVDialog" format="PNG"/> +// </figure>--> + +* _Export to file:_ frame chooses the file to export the packet data to. + +* The _Packet Range_ frame is described in <<ChIOPacketRangeSection>>. + +[[ChIOExportCArraysDialog]] + +==== The "Export as C Arrays (packet bytes) file" dialog box + +// XXX - add screenshot + +Export packet bytes into C arrays so you can import the stream data into your own C program. + +// <figure> +// <title>The "Export as C Arrays (packet bytes) file" dialog box</title> +// <graphic entityref="WiresharkExportCArraysDialog" format="PNG"/> +// </figure> + +* _Export to file:_ frame chooses the file to export the packet data to. + +* The _Packet Range_ frame is described in <<ChIOPacketRangeSection>>. + +[[ChIOExportPSMLDialog]] + +==== The "Export as PSML File" dialog box + +Export packet data into PSML. This is an XML based format including only the +packet summary. The PSML file specification is available at: +link:$$http://www.nbee.org/doku.php?id=netpdl:psml_specification$$[]. + +.The "Export as PSML File" dialog box +image::wsug_graphics/ws-export-psml.png[] + +* _Export to file:_ frame chooses the file to export the packet data to. + +* The _Packet Range_ frame is described in <<ChIOPacketRangeSection>>. + +There's no such thing as a packet details frame for PSML export, as the packet +format is defined by the PSML specification. + +[[ChIOExportPDMLDialog]] + +==== The "Export as PDML File" dialog box + +Export packet data into PDML. This is an XML based format including the packet +details. The PDML file specification is available at: +link:$$http://www.nbee.org/doku.php?id=netpdl:pdml_specification$$[]. + +[NOTE] +==== +The PDML specification is not officially released and Wireshark's implementation +of it is still in an early beta state, so please expect changes in future +Wireshark versions. +==== + +.The "Export as PDML File" dialog box +image::wsug_graphics/ws-export-pdml.png[] + +* _Export to file:_ frame chooses the file to export the packet data to. + +* The _Packet Range_ frame is described in <<ChIOPacketRangeSection>>. + +There's no such thing as a packet details frame for PDML export, as the packet +format is defined by the PDML specification. + +[[ChIOExportSelectedDialog]] + +==== The "Export selected packet bytes" dialog box + +Export the bytes selected in the "Packet Bytes" pane into a raw binary file. + +.The "Export Selected Packet Bytes" dialog box +image::wsug_graphics/ws-export-selected.png[] + +* _Name:_ the filename to export the packet data to. + +* The _Save in folder:_ field lets you select the folder to save to (from some predefined folders). + +* _Browse for other folders_ provides a flexible way to choose a folder. + +[[ChIOExportObjectsDialog]] + +==== The "Export Objects" dialog box + +This feature scans through HTTP streams in the currently open capture file or +running capture and takes reassembled objects such as HTML documents, image +files, executables and anything else that can be transferred over HTTP and lets +you save them to disk. If you have a capture running, this list is automatically +updated every few seconds with any new objects seen. The saved objects can then +be opened with the proper viewer or executed in the case of executables (if it +is for the same platform you are running Wireshark on) without any further work +on your part. This feature is not available when using GTK2 versions below 2.4. + +.The "Export Objects" dialog box +image::wsug_graphics/ws-export-objects.png[] + +* _Packet num:_ The packet number in which this object was found. In some + cases, there can be multiple objects in the same packet. + +* _Hostname:_ The hostname of the server that sent the object as a response to + an HTTP request. + +* _Content Type:_ The HTTP content type of this object. + +* _Bytes:_ The size of this object in bytes. + +* _Filename:_ The final part of the URI (after the last slash). This is + typically a filename, but may be a long complex looking string, which + typically indicates that the file was received in response to a HTTP POST + request. + +* _Help:_ Opens this section in the user's guide. + +* _Close:_ Closes this dialog. + +* _Save As:_ Saves the currently selected object as a filename you specify. The + default filename to save as is taken from the filename column of the objects + list. + +* _Save All:_ Saves all objects in the list using the filename from the + filename column. You will be asked what directory / folder to save them in. + If the filename is invalid for the operating system / file system you are + running Wireshark on, then an error will appear and that object will not be + saved (but all of the others will be). + +[[ChIOPrintSection]] + +=== Printing packets + +To print packets, select the menu:File[Print...] menu item. When you +do this Wireshark pops up the ``Print'' dialog box as shown in +<<ChIOPrintDialogBox>>. + +==== The ``Print'' dialog box + +[[ChIOPrintDialogBox]] + +.The ``Print'' dialog box +image::wsug_graphics/ws-print.png[] + +The following fields are available in the Print dialog box: _Printer_:: +This field contains a pair of mutually exclusive radio buttons: + +* _Plain Text_ specifies that the packet print should be in plain text. + +* _PostScript_ specifies that the packet print process should use PostScript to + generate a better print output on PostScript aware printers. + +* _Output to file:_ specifies that printing be done to a file, using the + filename entered in the field or selected with the browse button. ++ +This field is where you enter the _file_ to print to if you have selected Print +to a file, or you can click the button to browse the filesystem. It is greyed +out if Print to a file is not selected. + +* _Print command_ specifies that a command be used for printing. ++ +[NOTE] +.Note! +==== +These _Print command_ fields are not available on windows platforms. +==== ++ +This field specifies the command to use for printing. It is typically `lpr`. You +would change it to specify a particular queue if you need to print to a queue +other than the default. An example might be: ++ +---- +$ lpr -Pmypostscript +---- ++ +This field is greyed out if _Output to file:_ is checked above. + +_Packet Range_:: +Select the packets to be printed, see <<ChIOPacketRangeSection>> + +_Packet Format_:: +Select the output format of the packets to be printed. You can choose, how each +packet is printed, see <<ChIOPacketFormatFrame>> + +[[ChIOPacketRangeSection]] + +=== The ``Packet Range'' frame + +The packet range frame is a part of various output related dialog boxes. It +provides options to select which packets should be processed by the output +function. + +[[ChIOPacketRangeFrame]] + +.The ``Packet Range'' frame +image::wsug_graphics/ws-packet-range.png[] + +If the button:[Captured] button is set (default), all packets from the selected rule +will be processed. If the button:[Displayed] button is set, only the currently +displayed packets are taken into account to the selected rule. + +* _All packets_ will process all packets. + +* _Selected packet only_ process only the selected packet. + +* _Marked packets only_ process only the marked packets. + +* _From first to last marked packet_ process the packets from the first to the + last marked one. + +* _Specify a packet range_ process a user specified range of packets, e.g. + specifying _5,10-15,20-_ will process the packet number five, the packets from + packet number ten to fifteen (inclusive) and every packet from number twenty + to the end of the capture. + +[[ChIOPacketFormatSection]] + +=== The Packet Format frame + +The packet format frame is a part of various output related dialog boxes. It +provides options to select which parts of a packet should be used for the output +function. + +[[ChIOPacketFormatFrame]] + +.The ``Packet Format'' frame +image::wsug_graphics/ws-packet-format.png[] + +* _Packet summary line_ enable the output of the summary line, just as in the + ``Packet List'' pane. + +* _Packet details_ enable the output of the packet details tree. + +* _All collapsed_ the info from the ``Packet Details'' pane in ``all collapsed'' + state. + +* _As displayed_ the info from the ``Packet Details'' pane in the current state. + +* _All expanded_ the info from the ``Packet Details'' pane in ``all expanded'' + state. + +* _Packet bytes_ enable the output of the packet bytes, just as in the ``Packet + Bytes'' pane. + +* _Each packet on a new page_ put each packet on a separate page (e.g. when + saving/printing to a text file, this will put a form feed character between + the packets). + +++++++++++++++++++++++++++++++++++++++ +<!-- End of WSUG Chapter IO --> +++++++++++++++++++++++++++++++++++++++
\ No newline at end of file diff --git a/docbook/wsug_src/WSUG_chapter_io.xml b/docbook/wsug_src/WSUG_chapter_io.xml deleted file mode 100644 index 3baaa2ccd5..0000000000 --- a/docbook/wsug_src/WSUG_chapter_io.xml +++ /dev/null @@ -1,1482 +0,0 @@ -<!-- WSUG Chapter IO --> - -<chapter id="ChapterIO"> - <title>File Input / Output and Printing</title> - - <section id="ChIOIntroductionSection"><title>Introduction</title> - <para> - This chapter will describe input and output of capture data. - <itemizedlist> - <listitem> - <para> - Open capture files in various capture file formats - </para> - </listitem> - <listitem> - <para> - Save/Export capture files in various capture file formats - </para> - </listitem> - <listitem> - <para> - Merge capture files together - </para> - </listitem> - <listitem> - <para> - Import text files containing hex dumps of packets - </para> - </listitem> - <listitem> - <para> - Print packets - </para> - </listitem> - </itemizedlist> - </para> - </section> - - <section id="ChIOOpenSection"><title>Open capture files</title> - <para> - Wireshark can read in previously saved capture files. - To read them, simply select the menu or toolbar item: "File/ - <inlinegraphic entityref="WiresharkToolbarOpen" format="PNG"/> - <command>Open</command>". - Wireshark will then pop up the File - Open dialog box, which is discussed in more detail in - <xref linkend="ChIOOpen"/>. - </para> - <tip><title>It's convenient to use drag-and-drop!</title> - <para> - ... to open a file, by simply dragging the desired file from your file - manager and dropping it onto Wireshark's main window. - However, drag-and-drop is not available/won't work in all desktop - environments. - </para> - </tip> - <para> - If you haven't previously saved the current capture file, you will be asked - to do so, to prevent data loss (this behaviour can be disabled in the - preferences). - </para> - <para> - In addition to its native file format (libpcap format, also used by - tcpdump/WinDump and other libpcap/WinPcap-based programs), Wireshark can - read capture files from a large number of other packet capture programs - as well. See <xref linkend="ChIOInputFormatsSection"/> for the list of - capture formats Wireshark understands. - </para> - - <section id="ChIOOpen"> - <title>The "Open Capture File" dialog box</title> - <para> - The "Open Capture File" dialog box allows you to search for a - capture file containing previously captured packets for display in - Wireshark. <xref linkend="ChIOOpenFileTab"/> shows some examples - of the Wireshark Open File Dialog box. - </para> - <note> - <title>The dialog appearance depends on your system!</title> - <para> - The appearance of this dialog depends on the system and/or GTK+ - toolkit version used. However, the functionality remains basically - the same on any particular system. - </para> - </note> - - <para> - <command>Common dialog behaviour</command> on all systems: - </para> - <itemizedlist> - <listitem> - <para> - Select files and directories. - </para> - </listitem> - <listitem> - <para> - Click the Open/Ok button to accept your selected file and open it. - </para> - </listitem> - <listitem> - <para> - Click the Cancel button to go back to Wireshark and not load a capture - file. - </para> - </listitem> - </itemizedlist> - - <para> - <command>Wireshark extensions</command> to the standard behaviour of - these dialogs: - </para> - <itemizedlist> - <listitem> - <para> - View file preview information (like the filesize, the number of - packets, ...), if you've selected a capture file. - </para> - </listitem> - <listitem> - <para> - Specify a display filter with the "Filter:" button and filter - field. This filter will be used when opening the new file. - The text field background becomes green for a valid filter string - and red for an invalid one. - Clicking on the Filter button causes Wireshark to pop up - the Filters dialog box (which is discussed further in - <xref linkend="ChWorkDisplayFilterSection"/>). - </para> - <para> - XXX - we need a better description of these read filters - </para> - </listitem> - <listitem> - <para> - Specify which type of name resolution is to be performed for all packets by - clicking on one of the "... name resolution" check buttons. - Details about name resolution can be found in - <xref linkend="ChAdvNameResolutionSection"/>. - </para> - </listitem> - </itemizedlist> - - <tip><title>Save a lot of time loading huge capture files!</title> - <para> - You can change the display filter and name resolution settings later - while viewing the packets. - However, loading huge capture files can take a significant amount of - extra time if these settings are changed later, so in such situations it can - be a good idea to set at least the filter in advance here. - </para> - </tip> - - <!-- frame="none" --> - <table id="ChIOOpenFileTab"> - <title>The system specific "Open Capture File" dialog box</title> - <tgroup cols="2"> - <tbody> - <row> - <entry valign="top"> - <para> - <figure id="ChIOOpenFileDialogWin32"> - <title>"Open" on native Windows</title> - <graphic entityref="WiresharkOpenDialogWin32" format="PNG"/> - </figure> - </para> - </entry> - <entry valign="top"> - <para><command>Microsoft Windows</command></para> - <para> - This is the common Windows file open dialog - - plus some Wireshark extensions. - </para> - <para> - Specific for this dialog: - </para> - <itemizedlist> - <listitem> - <para> - If available, the "Help" button will lead you to this section of - this "User's Guide". - </para> - </listitem> - <listitem> - <note><para> - The "Filter:" button currently doesn't work on Windows! - </para></note> - </listitem> - </itemizedlist> - </entry> - </row> - <row> - <entry valign="top"> - <para> - <figure id="ChIOOpenFileDialog"> - <title>"Open" - new GTK version</title> - <graphic entityref="WiresharkOpenDialog24" format="PNG"/> - </figure> - </para> - </entry> - <entry valign="top"> - <para><command>Unix/Linux: GTK version >= 2.4</command></para> - <para> - This is the common Gimp/GNOME file open dialog - - plus some Wireshark extensions. - </para> - <para> - Specific for this dialog: - </para> - <itemizedlist> - <listitem> - <para> - The "+ Add" button allows you to add a directory, selected in the - right-hand pane, to the favorites list on the left. Those changes - are persistent. - </para> - </listitem> - <listitem> - <para> - The "- Remove" button allows you to remove a selected directory from - that list again (the items like: "Home", "Desktop", and "Filesystem" - cannot be removed). - </para> - </listitem> - <listitem> - <para> - If Wireshark doesn't recognize the selected file as a capture file, - it will grey out the "Open" button. - </para> - </listitem> - </itemizedlist> - </entry> - </row> - <row> - <entry valign="top"> - <para> - <figure id="ChIOOpenFileDialog1"> - <title>"Open" - old GTK version</title> - <graphic entityref="WiresharkOpenDialog20" format="PNG"/> - </figure> - </para> - </entry> - <entry valign="top"> - <para> - <command>Unix/Linux: GTK version < 2.4</command></para> - <para> - This is the file open dialog of former Gimp/GNOME versions - - plus some Wireshark extensions. - </para> - <para> - Specific for this dialog: - </para> - <itemizedlist> - <listitem> - <para> - If Wireshark doesn't recognize the selected file as a capture file, - it will grey out the "Ok" button. - </para> - </listitem> - </itemizedlist> - </entry> - </row> - </tbody> - </tgroup> - </table> - - - </section> - - <section id="ChIOInputFormatsSection"> - <title>Input File Formats</title> - <para> - The following file formats from other capture tools can be opened by - <application>Wireshark</application>: - <itemizedlist> - <listitem><para>libpcap - captures from <emphasis>Wireshark</emphasis>/<emphasis>TShark</emphasis>/<emphasis>dumpcap</emphasis>, <emphasis>tcpdump</emphasis>, and various other tools using libpcap's/tcpdump's capture format</para></listitem> - <listitem><para>pcap-ng - "next-generation" successor to libpcap format</para></listitem> - <listitem><para>Sun snoop and atmsnoop</para></listitem> - <listitem><para>Shomiti/Finisar <emphasis>Surveyor</emphasis> captures</para></listitem> - <listitem><para>Novell <emphasis>LANalyzer</emphasis> captures</para></listitem> - <listitem><para>Microsoft Network Monitor captures</para></listitem> - <listitem><para>AIX's iptrace captures</para></listitem> - <listitem><para>Cinco Networks NetXray captures</para></listitem> - <listitem><para>Network Associates Windows-based Sniffer and Sniffer Pro captures</para></listitem> - <listitem><para>Network General/Network Associates DOS-based Sniffer (compressed or uncompressed) captures</para></listitem> - <listitem><para>AG Group/WildPackets EtherPeek/TokenPeek/AiroPeek/EtherHelp/PacketGrabber captures</para></listitem> - <listitem><para>RADCOM's WAN/LAN Analyzer captures</para></listitem> - <listitem><para>Network Instruments Observer version 9 captures</para></listitem> - <listitem><para>Lucent/Ascend router debug output</para></listitem> - <listitem><para>HP-UX's nettl</para></listitem> - <listitem><para>Toshiba's ISDN routers dump output</para></listitem> - <listitem><para>ISDN4BSD <emphasis>i4btrace</emphasis> utility</para></listitem> - <listitem><para>traces from the EyeSDN USB S0</para></listitem> - <listitem><para>IPLog format from the Cisco Secure Intrusion Detection System</para></listitem> - <listitem><para>pppd logs (pppdump format)</para></listitem> - <listitem><para>the output from VMS's TCPIPtrace/TCPtrace/UCX$TRACE utilities</para></listitem> - <listitem><para>the text output from the DBS Etherwatch VMS utility</para></listitem> - <listitem><para>Visual Networks' Visual UpTime traffic capture</para></listitem> - <listitem><para>the output from CoSine L2 debug</para></listitem> - <listitem><para>the output from Accellent's 5Views LAN agents</para></listitem> - <listitem><para>Endace Measurement Systems' ERF format captures</para></listitem> - <listitem><para>Linux Bluez Bluetooth stack hcidump -w traces</para></listitem> - <listitem><para>Catapult DCT2000 .out files</para></listitem> - <listitem><para>Gammu generated text output from Nokia DCT3 phones in Netmonitor mode</para></listitem> - <listitem><para>IBM Series (OS/400) Comm traces (ASCII & UNICODE)</para></listitem> - <listitem><para>Juniper Netscreen snoop captures</para></listitem> - <listitem><para>Symbian OS btsnoop captures</para></listitem> - <listitem><para>Tamosoft CommView captures</para></listitem> - <listitem><para>Textronix K12xx 32bit .rf5 format captures</para></listitem> - <listitem><para>Textronix K12 text file format captures</para></listitem> - <listitem><para>Apple PacketLogger captures</para></listitem> - <listitem><para>Captures from Aethra Telecommunications' PC108 software for their test instruments</para></listitem> - <listitem><para>... new file formats are added from time to time</para></listitem> - </itemizedlist> - </para> - <note><title>Opening a file may fail due to invalid packet types!</title> - <para> - 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 (e.g. token ring packets) - from all file formats. - </para> - </note> - - </section> - - </section> - - <section id="ChIOSaveSection"><title>Saving captured packets</title> - <para> - You can save captured packets simply by using the Save As... menu - item from the File menu under Wireshark. You can choose which - packets to save and which file format to be used. - </para> - <warning> - <title>Saving may reduce the available information!</title> - <para> - Saving the captured packets will slightly reduce the amount of - information, e.g. the number of dropped packets will be lost; - see <xref linkend="ChAppFilesCaptureFilesSection"/> for details. - </para> - </warning> - <section id="ChIOSaveAs"> - <title>The "Save Capture File As" dialog box</title> - <para> - The "Save Capture File As" dialog box allows you to save - the current capture to a file. - <xref linkend="ChIOSaveFileTab"/> shows some examples of this - dialog box. - </para> - <note> - <title>The dialog appearance depends on your system!</title> - <para> - The appearance of this dialog depends on the system and GTK+ toolkit - version used. However, the functionality remains basically the same - on any particular system. - </para> - </note> - - <table id="ChIOSaveFileTab"> - <title>The system specific "Save Capture File As" dialog box</title> - <tgroup cols="2"> - <tbody> - <row> - <entry valign="top"> - <para> - <figure id="ChIOSaveAsFileWin32"> - <title>"Save" on native Windows</title> - <graphic entityref="WiresharkSaveAsDialogWin32" format="PNG"/> - </figure> - </para> - </entry> - <entry valign="top"> - <para><command>Microsoft Windows</command></para> - <para> - This is the common Windows file save dialog - - plus some Wireshark extensions. - </para> - <para> - Specific for this dialog: - </para> - <itemizedlist> - <listitem> - <para> - If available, the "Help" button will lead you to this section of - this "User's Guide". - </para> - </listitem> - <listitem> - <para> - 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. - </para> - </listitem> - </itemizedlist> - </entry> - </row> - <row> - <entry valign="top"> - <para> - <figure id="ChIOSaveAsFile2"> - <title>"Save" - new GTK version</title> - <graphic entityref="WiresharkSaveAsDialog24" format="PNG"/> - </figure> - </para> - </entry> - <entry valign="top"> - <para><command>Unix/Linux: GTK version >= 2.4</command></para> - <para> - This is the common Gimp/GNOME file save dialog - - plus some Wireshark extensions. - </para> - <para> - Specific for this dialog: - </para> - <itemizedlist> - <listitem> - <para> - Clicking on the + at "Browse for other folders" will allow you - to browse files and folders in your file system. - </para> - </listitem> - </itemizedlist> - </entry> - </row> - <row> - <entry valign="top"> - <para> - <figure id="ChIOSaveAsFile1"> - <title>"Save" - old GTK version</title> - <graphic entityref="WiresharkSaveAsDialog20" format="PNG"/> - </figure> - </para> - </entry> - <entry valign="top"> - <para><command>Unix/Linux: GTK version < 2.4</command></para> - <para> - This is the file save dialog of former Gimp/GNOME versions - - plus some Wireshark extensions. - </para> - </entry> - </row> - </tbody> - </tgroup> - </table> - - <para> - With this dialog box, you can perform the following actions: - <orderedlist> - <listitem> - <para> - Type in the name of the file you wish to save the captured - packets in, as a standard file name in your file system. - </para> - </listitem> - <listitem> - <para> - Select the directory to save the file into. - </para> - </listitem> - <listitem> - <para> - Select the range of the packets to be saved, see - <xref linkend="ChIOPacketRangeSection"/> - </para> - </listitem> - <listitem> - <para> - Specify the format of the saved capture file by clicking on - the File type drop down box. You can choose from the - types, described in <xref linkend="ChIOOutputFormatsSection"/>. - </para> - <note> - <title>The selection of capture formats may be reduced!</title> - <para> - Some capture formats may not be available, depending on the - packet types captured. - </para> - </note> - <tip> - <title>File formats can be converted!</title> - <para> - You can convert capture files from one format to another - by reading in a capture file and writing it out using a - different format. - </para> - </tip> - </listitem> - <listitem> - <para> - Click on the Save/Ok button to accept your selected file and save to - it. If Wireshark has a problem saving the captured packets to - the file you specified, it will display an error dialog box. - After clicking OK on that error dialog box, you can try again. - </para> - </listitem> - <listitem> - <para> - Click on the Cancel button to go back to Wireshark and not save the - captured packets. - </para> - </listitem> - </orderedlist> - </para> - </section> - <section id="ChIOOutputFormatsSection"> - <title>Output File Formats</title> - <para> - Wireshark can save the packet data in its "native" file format (libpcap) - and in the file formats of some other protocol analyzers, so other tools - can read the capture data. - </para> - <warning><title>File formats have different time stamp accuracies!</title> - <para> - Saving from the currently used file format to a different format may reduce the - time stamp accuracy; see the <xref linkend="ChAdvTimestamps"/> for details. - </para> - </warning> - <para> - The following file formats can be saved by <application>Wireshark</application> (with the known file extensions): - <itemizedlist> - <listitem><para>libpcap, tcpdump and various other tools using tcpdump's capture format (*.pcap,*.cap,*.dmp)</para></listitem> - <listitem><para>Accellent 5Views (*.5vw)</para></listitem> - <listitem><para>HP-UX's nettl (*.TRC0,*.TRC1)</para></listitem> - <listitem><para>Microsoft Network Monitor - NetMon (*.cap)</para></listitem> - <listitem><para>Network Associates Sniffer - DOS (*.cap,*.enc,*.trc,*fdc,*.syc)</para></listitem> - <listitem><para>Network Associates Sniffer - Windows (*.cap)</para></listitem> - <listitem><para>Network Instruments Observer version 9 (*.bfr)</para></listitem> - <listitem><para>Novell LANalyzer (*.tr1)</para></listitem> - <listitem><para>Sun snoop (*.snoop,*.cap)</para></listitem> - <listitem><para>Visual Networks Visual UpTime traffic (*.*)</para></listitem> - <listitem><para>... new file formats are added from time to time</para></listitem> - </itemizedlist> - </para> - <para> - If the above tools will be more helpful than Wireshark is a different question ;-) - </para> - <note><title>Third party protocol analyzers may require specific file extensions!</title> - <para> - Other protocol analyzers than Wireshark may require that the file has a - certain file extension in order to read the files you generate with Wireshark, e.g.: - </para> - <para> - ".cap" for Network Associates Sniffer - Windows - </para> - </note> - </section> - </section> - - <section id="ChIOMergeSection"><title>Merging capture files</title> - <para> - 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). - </para> - <para> - Merging capture files can be done in three ways: - <itemizedlist> - <listitem><para> - Use the <command>menu item "Merge"</command> from the "File" menu, - to open the merge dialog, see <xref linkend="ChIOMergeDialog"/>. - This menu item will be disabled, until you have loaded a capture file. - </para></listitem> - <listitem><para> - Use <command>drag-and-drop</command> 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 only a single file, it will simply replace a (maybe) existing - one. - </para></listitem> - <listitem><para> - Use the <command>mergecap</command> tool, which is a command - line tool to merge capture files. This tool provides the most options - to merge capture files, see <xref linkend="AppToolsmergecap"/>. - </para></listitem> - </itemizedlist> - </para> - <section id="ChIOMergeDialog"> - <title>The "Merge with Capture File" dialog box</title> - <para> - - This dialog box let you select a file to be merged into the currently - loaded file. - </para> - <note><title>You will be prompted for an unsaved file first!</title> - <para>If your current data wasn't saved before, you will be asked to save - it first, before this dialog box is shown.</para> - </note> - - <para> - Most controls of this dialog will work the same way as described in the - "Open Capture File" dialog box, see <xref linkend="ChIOOpen"/>. - </para> - <para> - Specific controls of this merge dialog are: - </para> - - <variablelist> - <varlistentry> - <term><command>Prepend packets to existing file</command></term> - <listitem> - <para> - Prepend the packets from the selected file before the currently loaded - packets. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><command>Merge packets chronologically</command></term> - <listitem> - <para> - Merge both the packets from the selected and currently loaded file in - chronological order. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><command>Append packets to existing file</command></term> - <listitem> - <para> - Append the packets from the selected file after the currently loaded - packets. - </para> - </listitem> - </varlistentry> - </variablelist> - - <table id="ChIOMergeFileTab"> - <title>The system specific "Merge Capture File As" dialog box</title> - <tgroup cols="2"> - <tbody> - <row> - <entry valign="top"> - <para> - <figure id="ChIOMergeFileWin32"> - <title>"Merge" on native Windows</title> - <graphic entityref="WiresharkMergeDialogWin32" format="PNG"/> - </figure> - </para> - </entry> - <entry valign="top"> - <para><command>Microsoft Windows</command></para> - <para> - This is the common Windows file open dialog - - plus some Wireshark extensions. - </para> - </entry> - </row> - <row> - <entry valign="top"> - <para> - <figure id="ChIOMergeFile2"> - <title>"Merge" - new GTK version</title> - <graphic entityref="WiresharkMergeDialog24" format="PNG"/> - </figure> - </para> - </entry> - <entry valign="top"> - <para><command>Unix/Linux: GTK version >= 2.4</command></para> - <para> - This is the common Gimp/GNOME file open dialog - - plus some Wireshark extensions. - </para> - </entry> - </row> - <row> - <entry valign="top"> - <para> - <figure id="ChIOMergeFile1"> - <title>"Merge" - old GTK version</title> - <graphic entityref="WiresharkMergeDialog20" format="PNG"/> - </figure> - </para> - </entry> - <entry valign="top"> - <para><command>Unix/Linux: GTK version < 2.4</command></para> - <para> - This is the file open dialog of former Gimp/GNOME versions - - plus some Wireshark extensions. - </para> - </entry> - </row> - </tbody> - </tgroup> - </table> - - </section> - </section> - - <section id="ChIOImportSection"><title>Import hex dump</title> - <para> - Wireshark can read in an ASCII 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. - </para> - <para> - Wireshark understands a hexdump of the form generated by - <command>od -Ax -tx1 -v</command>. - In other words, each byte is individually displayed and surrounded with a space. - Each line begins with an offset describing the position in the file. The offset - is a hex number (can also be octal or decimal), of more than two hex - digits. Here is a sample dump that can be imported: - </para> - <programlisting> - 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 ........ - </programlisting> - <para> - There is no limit on the width or number of bytes per line. Also the text dump at - the end of the line is ignored. Bytes/hex numbers can be uppercase or lowercase. - Any text before the offset is ignored, including email forwarding characters '>'. - Any lines of text between the bytestring lines are ignored. The offsets are used - to track the bytes, so offsets must be correct. Any line which has only bytes - without a leading offset is ignored. An offset is recognized as being a hex - number longer than two characters. Any text after the bytes is ignored (e.g. the - character dump). Any hex numbers in this text are also ignored. An offset of zero - is indicative of starting a new packet, so a 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 read in with timestamps differing by one - microsecond 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.) - </para> - <para> - There are a couple of other special features to note. Any line where the first - 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. - </para> - <section id="ChIOImportDialog"> - <title>The "Import from Hex Dump" dialog box</title> - <para> - This dialog box lets you select a text file, containing a hex dump - of packet data, to be imported and set import parameters. - </para> - <para> - <figure id="ChIOFileImportDialog"> - <title>The "Import from Hex Dump" dialog</title> - <graphic entityref="WiresharkFileImportDialog" format="PNG"/> - </figure> - </para> - <para> - Specific controls of this import dialog are split in two sections: - <variablelist> - <varlistentry> - <term>Input</term> - <listitem><para>Determine which input file has to be imported and - how it is to be interpreted. - </para></listitem> - </varlistentry> - <varlistentry> - <term>Import</term> - <listitem><para>Determine how the data is to be imported.</para></listitem> - </varlistentry> - </variablelist> - </para> - <para> - The input parameters are as follows: - </para> - <variablelist> - <varlistentry> - <term><command>Filename / Browse</command></term> - <listitem> - <para> - Enter the name of the text file to import. You can use - <command>Browse</command> to browse for a file. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><command>Offsets</command></term> - <listitem> - <para> - Select the radix of the offsets given in the text file to import. - This is usually hexadecimal, but decimal and octal are also supported. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><command>Date/Time</command></term> - <listitem> - <para> - Tick this checkbox if there are timestamps associated with the frames - in the text file to import you would like to use. Otherwise the current time - is used for timestamping the frames. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><command>Format</command></term> - <listitem> - <para> - This is the format specifier used to parse the timestamps in the text file - to import. It uses a simple syntax to describe the format of the timestamps, - using %H for hours, %M for minutes, %S for seconds, etc. The straightforward - HH:MM:SS format is covered by %T. For a full definition of the syntax look for - <command>strptime(3)</command>. - </para> - </listitem> - </varlistentry> - </variablelist> - <para> - The import parameters are as follows: - </para> - <variablelist> - <varlistentry> - <term><command>Encapsulation type</command></term> - <listitem> - <para> - Here you can select which type of frames you are importing. This all depends on - from what type of medium the dump to import was taken. It lists all types that - Wireshark understands, so as to pass the capture file contents to the right dissector. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><command>Dummy header</command></term> - <listitem> - <para> - When Ethernet encapsulation is selected you have to option to prepend dummy - headers to the frames to import. These headers can provide artificial Ethernet, IP, - UDP or TCP or SCTP headers and SCTP data chunks. When selecting a type of dummy - header the applicable entries are enabled, others are grayed out and default values - are used. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><command>Max. frame length</command></term> - <listitem> - <para> - You may not be interested in the full frames from the text file, just the first part. - Here you can define how much data from the start of the frame you want to import. - If you leave this open the maximum is set to 65535 bytes. - </para> - </listitem> - </varlistentry> - </variablelist> - <para> - Once all input and import parameters are setup click <command>OK</command> - to start the import. - </para> - <para> - <note><title>You will be prompted for an unsaved file first!</title> - <para>If your current data wasn't saved before, you will be asked to save - it first, before this dialog box is shown.</para> - </note> - </para> - <para> - When completed there will be a new capture file loaded with the frames imported - from the text file. - </para> - </section> - </section> - - <section id="ChIOFileSetSection"><title>File Sets</title> - <para> - When using the "Multiple Files" option while doing a capture - (see: <xref linkend="ChCapCaptureFiles"/>), - the capture data is spread over several capture files, called a file - set. - </para> - <para> - As it can become tedious to work with a file set by hand, Wireshark - provides some features to handle these file sets in a convenient way. - </para> - <sidebar><title>How does Wireshark detect the files of a file set?</title> - <para> - A filename in a file set uses the format Prefix_Number_DateTimeSuffix - which might look like this: "test_00001_20060420183910.pcap". - All files of a file set share the same prefix (e.g. "test") and suffix - (e.g. ".pcap") and a varying middle part. - </para> - <para> - To find the files of a file set, Wireshark scans the directory where the - currently loaded file resides and checks for files matching the filename - pattern (prefix and suffix) of the currently loaded file. - </para> - <para> - This simple mechanism usually works well, but has its drawbacks. If several - file sets were captured with the same prefix and suffix, Wireshark will detect - them as a single file set. If files were renamed or spread over several - directories the mechanism will fail to find all files of a set. - </para> - </sidebar> - <para> - The following features in the "File Set" submenu of the "File" menu are - available to work with file sets in a convenient way: - </para> - <itemizedlist> - <listitem><para> - The <command>List Files</command> dialog box will list the files - Wireshark has recognized as being part of the current file set. - </para></listitem> - <listitem><para> - <command>Next File</command> closes the current and opens the next - file in the file set. - </para></listitem> - <listitem><para> - <command>Previous File</command> closes the current and opens the - previous file in the file set. - </para></listitem> - </itemizedlist> - <section id="ChIOFileSetListDialog"> - <title>The "List Files" dialog box</title> - <figure> - <title>The "List Files" dialog box</title> - <graphic entityref="WiresharkFileSetDialog" format="PNG"/> - </figure> - <para> - Each line contains information about a file of the file set: - <itemizedlist> - <listitem><para> - <command>Filename</command> the name of the file. If you click on - the filename (or the radio button left to it), the current file will - be closed and the corresponding capture file will be opened. - </para></listitem> - <listitem><para> - <command>Created</command> the creation time of the file - </para></listitem> - <listitem><para> - <command>Last Modified</command> the last time the file was modified - </para></listitem> - <listitem><para> - <command>Size</command> the size of the file - </para></listitem> - </itemizedlist> - The last line will contain info about the currently used directory where - all of the files in the file set can be found. - </para> - <para> - The content of this dialog box is updated each time a capture file is - opened/closed. - </para> - <para> - The Close button will, well, close the dialog box. - </para> - </section> - </section> - <section id="ChIOExportSection"><title>Exporting data</title> - <para> - Wireshark provides several ways and formats to export packet data. This - section describes general ways to export data from Wireshark. - </para> - <note><title>Note!</title> - <para> - There are more specialized functions to export specific data, - which will be described at the appropriate places. - </para> - </note> - <para> - XXX - add detailed descriptions of the output formats and some sample - output, too. - </para> - <section id="ChIOExportPlainDialog"> - <title>The "Export as Plain Text File" dialog box</title> - <para id="ChIOExportPlain"> - Export packet data into a plain ASCII text file, much like the format - used to print packets. - <tip><title>Tip!</title> - <para> - If you would like to be able to import any previously exported - packets from a plain text file, it is recommended that you: - <itemizedlist> - <listitem><para> - Add the "Absolute date and time" column. - </para></listitem> - <listitem><para> - Temporarily hide all other columns. - </para></listitem> - <listitem><para> - Turn off: Edit/Preferences/Protocols/Data/ - "Show not dissected data on new Packet Bytes pane". More detail is - provided in <xref linkend="ChCustPreferencesSection"/> - </para></listitem> - <listitem><para> - Include the packet summary line. - </para></listitem> - <listitem><para> - Exclude the column headings. - </para></listitem> - <listitem><para> - Exclude the packet details. - </para></listitem> - <listitem><para> - Include the packet bytes. - </para></listitem> - </itemizedlist> - </para> - </tip> - <figure> - <title>The "Export as Plain Text File" dialog box</title> - <graphic entityref="WiresharkExportPlainDialog" format="PNG"/> - </figure> - <itemizedlist> - <listitem><para> - <command>Export to file:</command> frame chooses the file to export - the packet data to. - </para></listitem> - <listitem><para> - The <command>Packet Range</command> frame is described in <xref - linkend="ChIOPacketRangeSection"/>. - </para></listitem> - <listitem><para> - The <command>Packet Details</command> frame is described in <xref - linkend="ChIOPacketFormatSection"/>. - </para></listitem> - </itemizedlist> - </para> - </section> - <section id="ChIOExportPSDialog"> - <title>The "Export as PostScript File" dialog box</title> - <para> - Export packet data into PostScript, much like the format used - to print packets. - <tip><title>Tip!</title> - <para> - You can easily convert PostScript files to PDF files using ghostscript. - For example: export to a file named foo.ps and then call: - <command>ps2pdf foo.ps</command> - </para> - </tip> - <figure> - <title>The "Export as PostScript File" dialog box</title> - <graphic entityref="WiresharkExportPSDialog" format="PNG"/> - </figure> - <itemizedlist> - <listitem><para> - <command>Export to file:</command> frame chooses the file to export - the packet data to. - </para></listitem> - <listitem><para> - The <command>Packet Range</command> frame is described in <xref - linkend="ChIOPacketRangeSection"/>. - </para></listitem> - <listitem><para> - The <command>Packet Details</command> frame is described in <xref - linkend="ChIOPacketFormatSection"/>. - </para></listitem> - </itemizedlist> - </para> - </section> - <section id="ChIOExportCSVDialog"> - <title>The "Export as CSV (Comma Separated Values) File" dialog box</title> - <para>XXX - add screenshot</para> - <para> - Export packet summary into CSV, used e.g. by spreadsheet programs to - im-/export data. - <!--<figure> - <title>The "Export as Comma Separated Values File" dialog box</title> - <graphic entityref="WiresharkExportCSVDialog" format="PNG"/> - </figure>--> - <itemizedlist> - <listitem><para> - <command>Export to file:</command> frame chooses the file to export - the packet data to. - </para></listitem> - <listitem><para> - The <command>Packet Range</command> frame is described in <xref - linkend="ChIOPacketRangeSection"/>. - </para></listitem> - </itemizedlist> - </para> - </section> - <section id="ChIOExportCArraysDialog"> - <title>The "Export as C Arrays (packet bytes) file" dialog box</title> - <para>XXX - add screenshot</para> - <para> - Export packet bytes into C arrays so you can import the stream data - into your own C program. - <!-- - <figure> - <title>The "Export as C Arrays (packet bytes) file" dialog box</title> - <graphic entityref="WiresharkExportCArraysDialog" format="PNG"/> - </figure> - --> - <itemizedlist> - <listitem><para> - <command>Export to file:</command> frame chooses the file to export - the packet data to. - </para></listitem> - <listitem><para> - The <command>Packet Range</command> frame is described in <xref - linkend="ChIOPacketRangeSection"/>. - </para></listitem> - </itemizedlist> - </para> - </section> - <section id="ChIOExportPSMLDialog"> - <title>The "Export as PSML File" dialog box</title> - <para> - Export packet data into PSML. This is an XML based format including - only the packet summary. The PSML file specification is available at: - <ulink url="http://www.nbee.org/doku.php?id=netpdl:psml_specification"/>. - <figure> - <title>The "Export as PSML File" dialog box</title> - <graphic entityref="WiresharkExportPSMLDialog" format="PNG"/> - </figure> - <itemizedlist> - <listitem><para> - <command>Export to file:</command> frame chooses the file to export - the packet data to. - </para></listitem> - <listitem><para> - The <command>Packet Range</command> frame is described in <xref - linkend="ChIOPacketRangeSection"/>. - </para></listitem> - </itemizedlist> - There's no such thing as a packet details frame for PSML export, as the - packet format is defined by the PSML specification. - </para> - </section> - <section id="ChIOExportPDMLDialog"> - <title>The "Export as PDML File" dialog box</title> - <para> - Export packet data into PDML. This is an XML based format including - the packet details. The PDML file specification is available at: - <ulink url="http://www.nbee.org/doku.php?id=netpdl:pdml_specification"/>. - <note><title></title> - <para> - The PDML specification is not officially released and Wireshark's - implementation of it is still in an early beta state, so please expect - changes in future Wireshark versions. - </para> - </note> - <figure> - <title>The "Export as PDML File" dialog box</title> - <graphic entityref="WiresharkExportPDMLDialog" format="PNG"/> - </figure> - <itemizedlist> - <listitem><para> - <command>Export to file:</command> frame chooses the file to export - the packet data to. - </para></listitem> - <listitem><para> - The <command>Packet Range</command> frame is described in <xref - linkend="ChIOPacketRangeSection"/>. - </para></listitem> - </itemizedlist> - There's no such thing as a packet details frame for PDML export, as the - packet format is defined by the PDML specification. - </para> - </section> - <section id="ChIOExportSelectedDialog"> - <title>The "Export selected packet bytes" dialog box</title> - <para> - Export the bytes selected in the "Packet Bytes" pane into a raw - binary file. - <figure> - <title>The "Export Selected Packet Bytes" dialog box</title> - <graphic entityref="WiresharkExportSelectedDialog" format="PNG"/> - </figure> - <itemizedlist> - <listitem><para> - <command>Name:</command> the filename to export the packet data to. - </para></listitem> - <listitem><para> - The <command>Save in folder:</command> field lets you select the - folder to save to (from some predefined folders). - </para></listitem> - <listitem><para> - <command>Browse for other folders</command> provides a flexible - way to choose a folder. - </para></listitem> - </itemizedlist> - </para> - </section> - <section id="ChIOExportObjectsDialog"> - <title>The "Export Objects" dialog box</title> - <para> - This feature scans through HTTP streams in the currently - open capture file or running capture and takes reassembled - objects such as HTML documents, image files, executables - and anything else that can be transferred over HTTP and - lets you save them to disk. If you have a capture - running, this list is automatically updated every few - seconds with any new objects seen. The saved objects can then be - opened with the proper viewer or executed in the case of - executables (if it is for the same platform you are - running Wireshark on) without any further work on your - part. This feature is not available when using GTK2 versions - below 2.4. - </para> - <figure> - <title>The "Export Objects" dialog box</title> - <graphic entityref="WiresharkExportObjectsDialog" format="PNG"/> - </figure> - - <itemizedlist> - <para>Columns:</para> - <listitem><para> - <command>Packet num:</command> The packet number in - which this object was found. In some cases, there can - be multiple objects in the same packet. - </para></listitem> - - <listitem><para> - <command>Hostname:</command> The hostname of the - server that sent the object as a response to an HTTP request. - </para></listitem> - - <listitem><para> - <command>Content Type:</command> The HTTP content type - of this object. - </para></listitem> - - <listitem><para> - <command>Bytes:</command> The size of this object in bytes. - </para></listitem> - - <listitem><para> - <command>Filename:</command> The final part of the URI - (after the last slash). This is typically a filename, - but may be a long complex looking string, which - typically indicates that the file was received in response to - a HTTP POST request. - </para></listitem> - </itemizedlist> - - <itemizedlist> - <para>Buttons:</para> - <listitem><para> - <command>Help:</command> Opens this section in the - user's guide. - </para></listitem> - - <listitem><para> - <command>Close:</command> Closes this dialog. - </para></listitem> - - <listitem><para> - <command>Save As:</command> Saves the currently - selected object as a filename you specify. The - default filename to save as is taken from the filename - column of the objects list. - </para></listitem> - - <listitem><para> - <command>Save All:</command> Saves all objects in the - list using the filename from the filename column. You - will be asked what directory / folder to save them - in. If the filename is invalid for the operating system / - file system you are running Wireshark on, then an error - will appear and that object will not be saved (but all - of the others will be). - </para></listitem> - </itemizedlist> - </section> - </section> - - <section id="ChIOPrintSection"><title>Printing packets</title> - <para> - To print packets, select the "Print..." menu item from the File menu. - When you do this, Wireshark pops up the Print dialog box as shown in - <xref linkend="ChIOPrintDialogBox"/>. - </para> - <section><title>The "Print" dialog box</title> - <figure id="ChIOPrintDialogBox"> - <title>The "Print" dialog box</title> - <graphic entityref="WiresharkPrint" format="PNG"/> - </figure> - <para> - The following fields are available in the Print dialog box: - <variablelist> - <varlistentry><term><command>Printer</command></term> - <listitem> - <para> - This field contains a pair of mutually exclusive radio buttons: - <itemizedlist> - <listitem> - <para> - <command>Plain Text</command> specifies that - the packet print should be in plain text. - </para> - </listitem> - <listitem> - <para> - <command>PostScript</command> specifies that - the packet print process should use PostScript to - generate a better print output on PostScript aware printers. - </para> - </listitem> - <listitem> - <para> - <command>Output to file:</command> specifies that printing - be done to a file, using the filename entered in the field or selected - with the browse button. - </para> - <para> - This field is where you enter the <command>file</command> to - print to if you have selected Print to a file, or you can click the - button to browse the filesystem. It is greyed out if Print to a file - is not selected. - </para> - </listitem> - <listitem> - <para> - <command>Print command</command> specifies that a - command be used for printing. - </para> - <note><title>Note!</title> - <para> - These <command>Print command</command> fields are not available on - windows platforms. - </para> - </note> - <para> - This field specifies the command to use for printing. It - is typically <command>lpr</command>. You would change it - to specify a particular queue if you need to print to a - queue other than the default. An example might be: - <programlisting> -lpr -Pmypostscript - </programlisting> - This field is greyed out if <command>Output to file:</command> is - checked above. - </para> - </listitem> - </itemizedlist> - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><command>Packet Range</command></term> - <listitem> - <para> - Select the packets to be printed, see <xref - linkend="ChIOPacketRangeSection"/> - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><command>Packet Format</command></term> - <listitem> - <para> - Select the output format of the packets to be printed. You can - choose, how each packet is printed, see - <xref linkend="ChIOPacketFormatFrame"/> - </para> - </listitem> - </varlistentry> - </variablelist> - </para> - </section> - </section> - - <section id="ChIOPacketRangeSection"><title>The Packet Range frame</title> - <para> - The packet range frame is a part of various output related dialog boxes. - It provides options to select which packets should be processed by the - output function. - <figure id="ChIOPacketRangeFrame"> - <title>The "Packet Range" frame</title> - <graphic entityref="WiresharkPacketRangeFrame" format="PNG"/> - </figure> - </para> - <para> - If the <command>Captured</command> button is set (default), all packets - from the selected rule will be processed. If the <command>Displayed - </command> button is set, only the currently displayed packets are taken - into account to the selected rule. - </para> - <para> - <itemizedlist> - <listitem> - <para> - <command>All packets</command> will process all packets. - </para> - </listitem> - <listitem> - <para> - <command>Selected packet only</command> process only the selected - packet. - </para> - </listitem> - <listitem> - <para> - <command>Marked packets only</command> process only the marked - packets. - </para> - </listitem> - <listitem> - <para> - <command>From first to last marked packet</command> process the - packets from the first to the last marked one. - </para> - </listitem> - <listitem> - <para> - <command>Specify a packet range</command> process a user specified - range of packets, e.g. specifying <command>5,10-15,20-</command> will - process the packet number five, the packets from packet number ten - to fifteen (inclusive) and every packet from number twenty to the - end of the capture. - </para> - </listitem> - </itemizedlist> - </para> - </section> - - <section id="ChIOPacketFormatSection"><title>The Packet Format frame</title> - <para> - The packet format frame is a part of various output related dialog boxes. - It provides options to select which parts of a packet should be used for - the output function. - <figure id="ChIOPacketFormatFrame"> - <title>The "Packet Format" frame</title> - <graphic entityref="WiresharkPacketFormatFrame" format="PNG"/> - </figure> - <itemizedlist> - <listitem> - <para> - <command>Packet summary line</command> enable the output of the - summary line, just as in the "Packet List" pane. - </para> - </listitem> - <listitem> - <para> - <command>Packet details</command> enable the output of the packet - details tree. - </para> - <itemizedlist> - <listitem> - <para> - <command>All collapsed</command> the info from the "Packet Details" - pane in "all collapsed" state. - </para> - </listitem> - <listitem> - <para> - <command>As displayed</command> the info from the "Packet Details" - pane in the current state. - </para> - </listitem> - <listitem> - <para> - <command>All expanded</command> the info from the "Packet Details" - pane in "all expanded" state. - </para> - </listitem> - </itemizedlist> - </listitem> - <listitem> - <para> - <command>Packet bytes</command> enable the output of the packet - bytes, just as in the "Packet Bytes" pane. - </para> - </listitem> - <listitem> - <para> - <command>Each packet on a new page</command> put each packet on a - separate page (e.g. when saving/printing to a text file, this will - put a form feed character between the packets). - </para> - </listitem> - </itemizedlist> - </para> - </section> - -</chapter> -<!-- End of WSUG Chapter IO --> - - |
