1 <!-- EUG Chapter IO -->
4 <chapter id="ChapterIO">
5 <title>File Input / Output and Printing</title>
7 <section id="ChIOIntroductionSection"><title>Introduction</title>
9 This chapter will describe input and output of capture data.
13 Open/Import capture files in various capture file formats
18 Save/Export capture files in various capture file formats
23 Merge capture files together
35 <section id="ChIOOpenSection"><title>Open capture files</title>
37 Ethereal can read in previously saved capture files.
38 To read them, simply select the <command>Open</command>
39 menu item from the <command>File</command> menu.
40 Ethereal will then pop up the File
41 Open dialog box, which is discussed in more detail in
42 <xref linkend="ChIOOpen"/>.
44 <note><title>Note!</title>
46 You can also use <command>drag-and-drop </command> to open a file, by
47 simply dropping the desired file from your file manager onto Ethereal's
48 main window. However, drag-and-drop is not available/won't work in all
53 If you didn't save the current capture file before, you will be asked
54 to do so, to prevent data loss (this behaviour can be disabled in the
58 In addition to its native file format (libpcap format, also used by
59 tcpdump/WinDump and other libpcap/WinPcap-based programs), Ethereal can
60 read capture files from a large number of other packet capture programs
61 as well. See <xref linkend="ChIOInputFormatsSection"/> for the list of
62 capture formats Ethereal understands.
65 <section id="ChIOOpen"><title>The "Open Capture File" dialog box</title>
67 The "Open Capture File" dialog box allows you to search for a
68 capture file containing previously captured packets for display in
69 Ethereal. <xref linkend="ChIOOpenFileDialog"/> shows an example
70 of the Ethereal Open File Dialog box.
75 Ethereal uses the open dialog box from the version of the GTK+
76 toolkit that it's using. This dialog was completely redesigned in
77 GTK version 2.4. Depending on the installed GTK version,
78 your dialog box might look different. However, as the
79 functionality remains almost the same, much of this description
80 will work with your version of Ethereal.
83 <figure id="ChIOOpenFileDialog">
84 <title>The "Open Capture File" Dialog box</title>
85 <graphic entityref="EtherealOpen" format="PNG"/>
88 With this dialog box, you can perform the following actions:
92 The "+ Add" button allows you to add a directory, selected in the
93 right-hand pane, to the favorites (bookmarks?) list. Those changes
99 The "- Remove" button allows you to remove a selected directory from
100 that list again (the items like: "Home", "Desktop", and "Filesystem"
106 Select files and directories with the list boxes.
111 View file preview information (like the filesize, the number of
112 packets, ...), while browsing the filesystem.
117 Specify a display filter with the Filter button and filter
118 field. This filter will be used when opening the new file.
119 Clicking on the Filter button causes Ethereal to pop up
120 the Filters dialog box (which is discussed further in
121 <xref linkend="ChWorkDisplayFilterSection"/>).
126 Specify which name resolution is to be performed for all packets by
127 clicking on one of the "Enable name resolution" check buttons.
128 Details about name resolution can be found in
129 <xref linkend="ChAdvNameResolutionSection"/>.
134 Click the Open button to accept your selected file and open it.
135 If Ethereal doesn't recognize the capture format, it will grey out
141 Click the Cancel button to go back to Ethereal and not load a capture
146 You can change the display filter and name resolution settings later while
147 viewing the packets. However, for very large capture files it can take a
148 significant amount of time changing these settings, so it might be
149 a good idea to set them in advance here.
153 <section id="ChIOInputFormatsSection">
154 <title>Input File Formats</title>
156 The following file formats from other capture tools can be opened by
157 <application>Ethereal</application>:
159 <listitem><para>libpcap, tcpdump and various other tools using tcpdump's capture format</para></listitem>
160 <listitem><para>Sun snoop and atmsnoop</para></listitem>
161 <listitem><para>Shomiti/Finisar <emphasis>Surveyor</emphasis> captures</para></listitem>
162 <listitem><para>Novell <emphasis>LANalyzer</emphasis> captures</para></listitem>
163 <listitem><para>Microsoft Network Monitor captures</para></listitem>
164 <listitem><para>AIX's iptrace captures</para></listitem>
165 <listitem><para>Cinco Networks NetXray captures</para></listitem>
166 <listitem><para>Network Associates Windows-based Sniffer and Sniffer Pro captures</para></listitem>
167 <listitem><para>Network General/Network Associates DOS-based Sniffer (compressed or uncompressed) captures</para></listitem>
168 <listitem><para>AG Group/WildPackets EtherPeek/TokenPeek/AiroPeek/EtherHelp/PacketGrabber captures</para></listitem>
169 <listitem><para>RADCOM's WAN/LAN Analyzer captures</para></listitem>
170 <listitem><para>Network Instruments Observer version 9 captures</para></listitem>
171 <listitem><para>Lucent/Ascend router debug output</para></listitem>
172 <listitem><para>HP-UX's nettl</para></listitem>
173 <listitem><para>Toshiba's ISDN routers dump output</para></listitem>
174 <listitem><para>ISDN4BSD <emphasis>i4btrace</emphasis> utility</para></listitem>
175 <listitem><para>traces from the EyeSDN USB S0</para></listitem>
176 <listitem><para>IPLog format from the Cisco Secure Intrusion Detection System</para></listitem>
177 <listitem><para>pppd logs (pppdump format)</para></listitem>
178 <listitem><para>the output from VMS's TCPIPtrace/TCPtrace/UCX$TRACE utilities</para></listitem>
179 <listitem><para>the text output from the DBS Etherwatch VMS utility</para></listitem>
180 <listitem><para>Visual Networks' Visual UpTime traffic capture</para></listitem>
181 <listitem><para>the output from CoSine L2 debug</para></listitem>
182 <listitem><para>the output from Accellent's 5Views LAN agents</para></listitem>
183 <listitem><para>Endace Measurement Systems' ERF format captures</para></listitem>
184 <listitem><para>Linux Bluez Bluetooth stack hcidump -w traces</para></listitem>
187 <note><title>Note!</title>
189 It may not be possible to read some formats dependent on the packet types
190 captured. Ethernet captures are usually supported for most file formats,
191 but other packet types (e.g. token ring packets) may not be possible to
192 read from all file formats.
200 <section id="ChIOSaveSection"><title>Saving captured packets</title>
202 You can save captured packets simply by using the Save As... menu
203 item from the File menu under Ethereal. You can choose which
204 packets to save and which file format to be used.
206 <section id="ChIOSaveAs">
207 <title>The "Save Capture File As" dialog box</title>
209 The "Save Capture File As" dialog box allows you to save
210 the current capture to a file.
211 <xref linkend="ChIOSaveCaptureFileAs"/> shows an example of this
217 Ethereal uses the open dialog box from the version of the GTK+
218 toolkit that it's using. This dialog was completely redesigned in
219 the GTK version 2.4. Depending on the installed GTK version,
220 your dialog box might look different. However, as the
221 functionality remains almost the same, much of this description
222 will work with your version of Ethereal.
225 <figure id="ChIOSaveCaptureFileAs">
226 <title>The "Save Capture File As" dialog box</title>
227 <graphic entityref="EtherealSaveAs" format="PNG"/>
230 With this dialog box, you can perform the following actions:
234 Type in the name of the file you wish to save the captured
235 packets in, as a standard file name in your file system.
240 Select the directory to save the file into.
245 Select the range of the packets to be saved, see
246 <xref linkend="ChIOPacketRangeSection"/>
251 Specify the format of the saved capture file by clicking on
252 the File type drop down box. You can choose from the
253 types, described in <xref linkend="ChIOInputFormatsSection"/>.
258 Some capture formats may not be available, depending on the
259 packet types captured.
265 You can convert capture files from one format to another
266 by reading in a capture file and writing it out using a
273 Use "Browse for other folders" to browse files and folders in your
279 Click on the Save button to accept your selected file and save to
280 it. If Ethereal has a problem saving the captured packets to
281 the file you specified, it will display an error dialog box.
282 After clicking OK on this error dialog box, you can try again.
287 Click on the Cancel button to go back to Ethereal and not save the
294 <section id="ChIOOutputFormatsSection">
295 <title>Output File Formats</title>
297 The following file formats can be saved by <application>Ethereal</application>,
298 so other capture tools can read the capture data from:
300 <listitem><para>libpcap (tcpdump)</para></listitem>
301 <listitem><para>Novell LANalyzer</para></listitem>
302 <listitem><para>Network Associates Sniffer</para></listitem>
303 <listitem><para>Sun snoop</para></listitem>
304 <listitem><para>Microsoft Network Monitor</para></listitem>
305 <listitem><para>Visual Networks Visual UpTime traffic</para></listitem>
306 <listitem><para>Accellent 5Views</para></listitem>
307 <listitem><para>Networks Instruments Observer version 9</para></listitem>
310 <note><title></title>
312 Other protocol analyzers may require that the file has a certain suffix
313 in order to read the files you generate with Ethereal, e.g.:
316 ".DMP" for Tcpdump/libpcap
319 ".CAP" for Network Assosciates Sniffer Windows
325 <section id="ChIOMergeSection"><title>Merging capture files</title>
327 Sometimes you need to merge several capture files into one. For example
328 this can be useful, if you have captured simultaneously from multiple
329 interfaces at once (e.g. using multiple instances of Ethereal).
332 Merging capture files can be done in three ways:
335 Use the <command>menu item "Merge"</command> from the "File" menu,
336 to open the merge dialog, see <xref linkend="ChIOMergeDialog"/>.
337 This menu item will be disabled, until you have loaded a capture file.
340 Use <command>drag-and-drop</command> to drop multiple files on the
341 main window. Ethereal will try to merge the packets in chronological
342 order from the dropped files into a newly created temporary file. If
343 you drop only a single file, it will simply replace a (maybe) existing
347 Use the <command>mergecap</command> tool, which is a command
348 line tool to merge capture files. This tool provides the most options
349 to merge capture files, see <xref linkend="AppToolsmergecap"/>.
353 <section><title>The "Merge with Capture File" dialog box</title>
355 This dialog box let you select a file to be merged into the currently
358 <note><title>Note!</title>
359 <para>If your current data wasn't saved before, you will be asked to save
360 it first, before this dialog box is shown.</para>
362 <figure id="ChIOMergeDialog">
363 <title>The "Merge with Capture File" dialog box</title>
364 <graphic entityref="EtherealMergeDialog" format="PNG"/>
368 <term><command>Prepend packets to existing file</command></term>
371 Prepend the packets from the selected file before the currently loaded
377 <term><command>Merge packets chronologically</command></term>
380 Merge both the packets from the selected and currently loaded file in
386 <term><command>Append packets to existing file</command></term>
389 Append the packets from the selected file after the currently loaded
396 All other controls will work the same way as in the "Open Capture File"
397 dialog box, see <xref linkend="ChIOOpen"/>.
402 <section id="ChIOExportSection"><title>Exporting data</title>
404 Ethereal provides several ways and formats to export packet data. This
405 section describes general ways to export data from Ethereal.
407 <note><title>Note!</title>
409 There are more specialized functions to export specific data,
410 which will be described at the appropriate places.
414 XXX - add detailed descriptions of the output formats and some sample
417 <section id="ChIOExportPlainDialog">
418 <title>The "Export as Plain Text File" dialog box</title>
419 <para id="ChIOExportPlain">
420 Export packet data into a plain ASCII text file, much like the format
421 used to print packets.
423 <title>The "Export as Plain Text File" dialog box</title>
424 <graphic entityref="EtherealExportPlainDialog" format="PNG"/>
428 <command>Export to file:</command> frame chooses the file to export
432 The <command>Packet Range</command> frame is described in <xref
433 linkend="ChIOPacketRangeSection"/>.
436 The <command>Packet Details</command> frame is described in <xref
437 linkend="ChIOPacketFormatSection"/>.
442 <section id="ChIOExportPSDialog">
443 <title>The "Export as PostScript File" dialog box</title>
445 Export packet data into PostScript, much like the format used
447 <tip><title>Tip!</title>
449 You can easily convert PostScript files to PDF files using ghostscript.
450 For example: export to a file named foo.ps and then call:
451 <command>ps2pdf foo.ps</command>
455 <title>The "Export as PostScript File" dialog box</title>
456 <graphic entityref="EtherealExportPSDialog" format="PNG"/>
460 <command>Export to file:</command> frame chooses the file to export
464 The <command>Packet Range</command> frame is described in <xref
465 linkend="ChIOPacketRangeSection"/>.
468 The <command>Packet Details</command> frame is described in <xref
469 linkend="ChIOPacketFormatSection"/>.
474 <section id="ChIOExportPSMLDialog">
475 <title>The "Export as PSML File" dialog box</title>
477 Export packet data into PSML. This is an XML based format including
478 only the packet summary.
480 <title>The "Export as PSML File" dialog box</title>
481 <graphic entityref="EtherealExportPSMLDialog" format="PNG"/>
485 <command>Export to file:</command> frame chooses the file to export
489 The <command>Packet Range</command> frame is described in <xref
490 linkend="ChIOPacketRangeSection"/>.
493 There's no such thing as a packet details frame for PSML export, as the
494 packet format is defined by the PSML specification.
497 <section id="ChIOExportPDMLDialog">
498 <title>The "Export as PDML File" dialog box</title>
500 Export packet data into PDML. This is an XML based format including
501 the packet details. The PDML file specification is available at:
502 <ulink url="http://analyzer.polito.it/30alpha/docs/dissectors/PDMLSpec.htm">
503 PDML specification</ulink>.
504 <note><title></title>
506 The PDML specification is not officially released and Ethereal's
507 implementation of it is still in an early beta state, so please expect
508 changes in future Ethereal versions.
512 <title>The "Export as PDML File" dialog box</title>
513 <graphic entityref="EtherealExportPDMLDialog" format="PNG"/>
517 <command>Export to file:</command> frame chooses the file to export
521 The <command>Packet Range</command> frame is described in <xref
522 linkend="ChIOPacketRangeSection"/>.
525 There's no such thing as a packet details frame for PDML export, as the
526 packet format is defined by the PDML specification.
529 <section id="ChIOExportSelectedDialog">
530 <title>The "Export selected packet bytes" dialog box</title>
532 Export the bytes selected in the "Packet Bytes" pane into a raw
535 <title>The "Export Selected Packet Bytes" dialog box</title>
536 <graphic entityref="EtherealExportSelectedDialog" format="PNG"/>
540 <command>Name:</command> the filename to export the packet data to.
543 The <command>Save in folder:</command> field lets you select the
544 folder to save to (from some predefined folders).
547 <command>Browse for other folders</command> provides a flexible
548 way to choose a folder.
555 <section id="ChIOPrintSection"><title>Printing packets</title>
557 To print packets, select the "Print..." menu item from the File menu.
558 When you do this, Ethereal pops up the Print dialog box as shown in
559 <xref linkend="ChIOPrintDialogBox"/>.
561 <section><title>The "Print" dialog box</title>
562 <figure id="ChIOPrintDialogBox">
563 <title>The "Print" dialog box</title>
564 <graphic entityref="EtherealPrint" format="PNG"/>
567 The following fields are available in the Print dialog box:
569 <varlistentry><term><command>Printer</command></term>
572 This field contains a pair of mutually exclusive radio buttons:
576 <command>Plain Text</command> specifies that
577 the packet print should be in plain text.
582 <command>PostScipt</command> specifies that
583 the packet print process should use PostScript to
584 generate a better print output on PostScript aware printers.
589 <command>Output to file:</command> specifies that printing
590 be done to a file, which name is entered in the field or selected
591 using the browse button.
594 This field is where you enter the <command>file</command> to
595 print to if you have selected Print to a file, or you can click the
596 button to browse the filesystem. It is greyed out if Print to a file
602 <command>Print command</command> specifies that a
603 command be used for printing.
605 <note><title>Note!</title>
607 These <command>Print command</command> fields are not available on
612 This field specifies the command to use for printing. It
613 is typically <command>lpr</command>. You would change it
614 to specify a particular queue if you need to print to a
615 queue other than the default. An example might be:
619 This field is greyed out if <command>Output to file:</command> is
628 <term><command>Packet Range</command></term>
631 Select the packets to be printed, see <xref
632 linkend="ChIOPacketRangeSection"/>
637 <term><command>Packet Format</command></term>
640 Select the output format of the packets to be printed. You can
641 choose, how each packet is printed, see
642 <xref linkend="ChIOPacketFormatFrame"/>
651 <section id="ChIOPacketRangeSection"><title>The Packet Range frame</title>
653 The packet range frame is a part of various output related dialog boxes.
654 It provides options to select which packets should be processed for the
656 <figure id="ChIOPacketRangeFrame">
657 <title>The "Packet Range" frame</title>
658 <graphic entityref="EtherealPacketRangeFrame" format="PNG"/>
662 If the <command>Captured</command> button is set (default), all packets
663 from the selected rule will be processed. If the <command>Displayed
664 </command> button is set, only the currently displayed packets are taken
665 into account to the selected rule.
671 <command>All packets</command> will process all packets.
676 <command>Selected packet only</command> process only the selected
682 <command>Marked packets only</command> process only the marked
688 <command>From first to last marked packet</command> process the
689 packets from the first to the last marked one.
694 <command>Specify a packet range</command> process a user specified
695 range of packets, e.g. specifying <command>5,10-15,20-</command> will
696 process the packet number five, the packets from packet number ten
697 to fifteen (inclusive) and every packet from number twenty to the
705 <section id="ChIOPacketFormatSection"><title>The Packet Format frame</title>
707 The packet format frame is a part of various output related dialog boxes.
708 It provides options to select which parts of a packet should be used for
710 <figure id="ChIOPacketFormatFrame">
711 <title>The "Packet Format" frame</title>
712 <graphic entityref="EtherealPacketFormatFrame" format="PNG"/>
717 <command>Packet summary line</command> enable the output of the
718 summary line, just as in the "Packet List" pane.
723 <command>Packet details</command> enable the output of the packet
729 <command>All collapsed</command> the info from the "Packet Details"
730 pane in "all collapsed" state.
735 <command>As displayed</command> the info from the "Packet Details"
736 pane in the current state.
741 <command>All expanded</command> the info from the "Packet Details"
742 pane in "all expanded" state.
749 <command>Packet bytes</command> enable the output of the packet
750 bytes, just as in the "Packet Bytes" pane.
755 <command>Each packet on a new page</command> put each packet on a
756 separate page (e.g. when saving/printing to a text file, this will
757 put a form feed character between the packets).
765 <!-- End of EUG Chapter IO -->