diff options
author | Ulf Lamping <ulf.lamping@web.de> | 2004-09-25 08:36:07 +0000 |
---|---|---|
committer | Ulf Lamping <ulf.lamping@web.de> | 2004-09-25 08:36:07 +0000 |
commit | db97602184b2dbd2c84543422f22b9e34e9b033f (patch) | |
tree | ace7e193f99b58f407faa562f3ee0c0ff39b3f88 /docbook/eug_src | |
parent | ffb879cb166b0a8bf907cac82aee0d770b8813a5 (diff) |
renamed dirs dg-src and ug-src to match output dirnames
svn path=/trunk/; revision=12097
Diffstat (limited to 'docbook/eug_src')
-rw-r--r-- | docbook/eug_src/EUG_app_files.xml | 292 | ||||
-rw-r--r-- | docbook/eug_src/EUG_app_howitworks.xml | 106 | ||||
-rw-r--r-- | docbook/eug_src/EUG_app_messages.xml | 34 | ||||
-rw-r--r-- | docbook/eug_src/EUG_app_protocols.xml | 25 | ||||
-rw-r--r-- | docbook/eug_src/EUG_app_tools.xml | 947 | ||||
-rw-r--r-- | docbook/eug_src/EUG_chapter_advanced.xml | 283 | ||||
-rw-r--r-- | docbook/eug_src/EUG_chapter_build_install.xml | 588 | ||||
-rw-r--r-- | docbook/eug_src/EUG_chapter_capture.xml | 950 | ||||
-rw-r--r-- | docbook/eug_src/EUG_chapter_customize.xml | 824 | ||||
-rw-r--r-- | docbook/eug_src/EUG_chapter_introduction.xml | 572 | ||||
-rw-r--r-- | docbook/eug_src/EUG_chapter_io.xml | 766 | ||||
-rw-r--r-- | docbook/eug_src/EUG_chapter_statistics.xml | 497 | ||||
-rw-r--r-- | docbook/eug_src/EUG_chapter_troubleshoot.xml | 129 | ||||
-rw-r--r-- | docbook/eug_src/EUG_chapter_use.xml | 1860 | ||||
-rw-r--r-- | docbook/eug_src/EUG_chapter_work.xml | 1383 | ||||
-rw-r--r-- | docbook/eug_src/EUG_meta_info.xml | 38 | ||||
-rw-r--r-- | docbook/eug_src/EUG_preface.xml | 170 |
17 files changed, 9464 insertions, 0 deletions
diff --git a/docbook/eug_src/EUG_app_files.xml b/docbook/eug_src/EUG_app_files.xml new file mode 100644 index 0000000000..5e70ab5bbe --- /dev/null +++ b/docbook/eug_src/EUG_app_files.xml @@ -0,0 +1,292 @@ +<!-- EUG Appendix Files --> +<!-- $Id$ --> + +<appendix id="AppFiles"> + <title>Configuration Files and Folders</title> + <para> + Ethereal uses a number of files while it is running. Some of these + reside in the personal configuration folder and are used to maintain + information between runs of Ethereal, while some of them are maintained + in system areas. + </para> + <para> + XXX - Add info about "temporary capture file" folders. + </para> + <tip><title>Tip</title> + <para>A list of the folders Ethereal actually uses can be found under the + "Folders" tab in the "About" dialog box. + </para> + </tip> + <para> + The content format of the configuration files is the same on all platforms. + However, to match the different policies for unix and windows platforms, + different folders for these files are used. + </para> + <table id="AppFilesTabFolders" frame="none"><title>Configuration files overview</title> + <tgroup cols="4"> + <colspec colnum="1" colwidth="72pt"/> + <colspec colnum="2" colwidth="80pt"/> + <colspec colnum="3" colwidth="80pt"/> + <thead> + <row> + <entry>File</entry> + <entry>Description</entry> + <entry>Unix folders</entry> + <entry>Windows folders</entry> + </row> + </thead> + <tbody> + <row> + <entry><command>preferences</command></entry> + <entry>Settings from the Preferences dialog box.</entry> + <entry>$HOME/.ethereal/preferences</entry> + <entry>%ETHEREAL%\preferences, %APPDATA%\Ethereal\preferences</entry> + </row> + <row> + <entry><command>recent</command></entry> + <entry>Recent GUI settings (e.g. recent files lists).</entry> + <entry>$HOME/.ethereal/recent</entry> + <entry>%APPDATA%\Ethereal\recent</entry> + </row> + <row> + <entry><command>cfilters</command></entry> + <entry>Capture filters.</entry> + <entry>$HOME/.ethereal/cfilters</entry> + <entry>%ETHEREAL%\cfilters, %APPDATA%\Ethereal\cfilters</entry> + </row> + <row> + <entry><command>dfilters</command></entry> + <entry>Display filters.</entry> + <entry>$HOME/.ethereal/dfilters</entry> + <entry>%ETHEREAL%\dfilters, %APPDATA%\Ethereal\dfilters</entry> + </row> + <row> + <entry><command>colorfilters</command></entry> + <entry>Coloring rules.</entry> + <entry>$HOME/.ethereal/colorfilters</entry> + <entry>%ETHEREAL%\colorfilters, %APPDATA%\Ethereal\colorfilters</entry> + </row> + <row> + <entry><command>disabled_protos</command></entry> + <entry>Disabled protocols.</entry> + <entry>$HOME/.ethereal/disabled_protos</entry> + <entry>%APPDATA%\Ethereal\disabled_protos</entry> + </row> + <row> + <entry><command>ethers</command></entry> + <entry>Ethernet name resolution.</entry> + <entry>/etc/ethers, $HOME/.ethereal/ethers</entry> + <entry>%ETHEREAL%\ethers, %APPDATA%\Ethereal\ethers</entry> + </row> + <row> + <entry><command>manuf</command></entry> + <entry>Ethernet name resolution.</entry> + <entry>/usr/local/etc/manuf</entry> + <entry>%ETHEREAL%\manuf</entry> + </row> + <row> + <entry><command>ipxnets</command></entry> + <entry>IPX name resolution.</entry> + <entry>$HOME/.ethereal/ipxnets</entry> + <entry>%ETHEREAL%\ipxnets</entry> + </row> + <row> + <entry><command>plugins</command></entry> + <entry>Plugin directories.</entry> + <entry>/usr/share/ethereal/plugins, + /usr/local/share/ethereals/plugins, + $HOME/.ethereal/plugins + </entry> + <entry>%ETHEREAL%\plugins\<version>, + %APPDATA%\Ethereal\plugins</entry> + </row> + </tbody> + </tgroup> + </table> + <note><title>Windows folders</title> + <para> + %APPDATA% points to the personal configuration folder, typically + "C:\Documents and Settings\<username>\Application Data", + %ETHEREAL% points to the Ethereal program folder, typically + "C:\Program Files\Ethereal" + </para> + </note> + <para> + <variablelist> + <varlistentry> + <term><command>preferences</command></term> + <listitem> + <para> + This file contains your Ethereal preferences, + including defaults for capturing and displaying packets. + It is a simple text file containing statements of the form: + <programlisting> +variable: value + </programlisting> + The settings from this file are + read in at program start and written to disk when you press the + Save button in the "Preferences" dialog box. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><command>recent</command></term> + <listitem> + <para> + This file contains various GUI related settings like the main window + position and size, the recent files list and such. + It is a simple text file containing statements of the form: + <programlisting> +variable: value + </programlisting> + It is read at program start and written at program exit. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>cfilters</command></term> + <listitem> + <para> + This file contains all the capture filters that you have defined + and saved. It consists of one or more lines, where each + line has the following format: + <programlisting> +"<filter name>" <filter string> + </programlisting> + The settings from this file are read in at program start and written + to disk when you press the Save button in the "Capture Filters" dialog + box. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>dfilters</command></term> + <listitem> + <para> + This file contains all the display filters that you have defined + and saved. It consists of one or more lines, where each + line has the following format: + <programlisting> +"<filter name>" <filter string> + </programlisting> + The settings from this file are read in at program start and written + to disk when you press the Save button in the "Display Filters" dialog + box. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><command>colorfilters</command></term> + <listitem> + <para> + This file contains all the color filters that you have + defined and saved. It consists of one or more lines, + where each line has the following format: + <programlisting> +@<filter name>@<filter string> +@[<bg RGB(16-bit)>][<fg RGB(16-bit)>] + </programlisting> + </para> + <para> + The settings from this file are read in at program start and written + to disk when you press the Save button in the "Coloring Rules" dialog + box. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><command>disabled_protos</command></term> + <listitem> + <para> + Each line in this file specifies a disabled protocol name. The + following are some examples: + <programlisting> +tcp +udp + </programlisting> + </para> + <para> + The settings from this file are read in at program start and written + to disk when you press the Save button in the "Enabled Protocols" + dialog box. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <command>ethers</command> + </term> + <listitem> + <para> + When Ethereal is trying to translate Ethernet hardware + addresses to names, it consults the files listed in + <xref linkend="AppFilesTabFolders"/>. + If an address is not found in /etc/ethers, + Ethereal looks in $HOME/.ethereal/ethers + </para> + <para> + Each line in these files consists of one hardware address and + name separated by whitespace. The digits of hardware + addressses are separated by colons (:), dashes (-) or + periods(.). The following are some examples: + <programlisting> +ff-ff-ff-ff-ff-ff Broadcast +c0-00-ff-ff-ff-ff TR_broadcast +00.2b.08.93.4b.a1 Freds_machine + </programlisting> + The settings from this file are read in at program start and never + written by Ethereal. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><command>manuf</command></term> + <listitem> + <para> + Ethereal uses the files listed in <xref linkend="AppFilesTabFolders"/> + to translate the first three bytes of an Ethernet address into a + manufacturers name. This file has the same format as the ethers + file, except addresses are three bytes long. + </para> + <para> + The settings from this file are read in at program start and never + written by Ethereal. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><command>ipxnets</command></term> + <listitem> + <para> + Ethereal uses the files listed in <xref linkend="AppFilesTabFolders"/> + to translate IPX network numbers into names. + </para> + <para> + An example is: + <programlisting> +C0.A8.2C.00 HR +c0-a8-1c-00 CEO +00:00:BE:EF IT_Server1 +110f FileServer3 + </programlisting> + </para> + <para> + The settings from this file are read in at program start and never + written by Ethereal. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><command>plugins</command></term> + <listitem> + <para> + Ethereal searches for plugins in the directories listed in + <xref linkend="AppFilesTabFolders"/>. + They are searched in the order listed. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> +<!-- </section> --> + +</appendix> +<!-- End of EUG Appendix Files --> diff --git a/docbook/eug_src/EUG_app_howitworks.xml b/docbook/eug_src/EUG_app_howitworks.xml new file mode 100644 index 0000000000..83e33beeff --- /dev/null +++ b/docbook/eug_src/EUG_app_howitworks.xml @@ -0,0 +1,106 @@ +<!-- EUG Appendix How it Works --> +<!-- $Id$ --> + +<appendix id="AppHowItWorks"> + <title>How Ethereal Works</title> + <para> + When using such a complex program like Ethereal, it's sometimes useful to + understand the mechanisms and concepts behind the surface. This is an + approach to shed some light on the inner workings of Ethereal. + </para> + + <section><title>Program start</title> + <para> + When Etheral starts, a lot of things are done: + <itemizedlist> + <listitem> + initialize the dissectors (register the protocol tree), including plugins + </listitem> + <listitem> + load and set values from the preferences file + </listitem> + <listitem> + load the capture filters from the cfilters file + </listitem> + <listitem> + load the display filters from the dfilters file + </listitem> + <listitem> + load and set the disabled protocols from the disabled_protos file + </listitem> + <listitem> + init libpcap/winpcap (the capturing engine) + </listitem> + <listitem> + process command line parameters + </listitem> + <listitem> + load and set the recently used GUI settings from the recent file + </listitem> + <listitem> + init and show the main screen + </listitem> + <listitem> + if specified by command line, load a capture file or start capturing + </listitem> + </itemizedlist> + </para> + <para> + + </para> + </section> + + <section><title>Protocol dissectors</title> + <para> + Each protocol has it's own protocol dissector. A dissector is called from + Ethereal, if the packet data seems to be of that corresponding protocol. The + dissector will then process the packet data and call back Ethereal if it + couldn't dissect all the data in that packet to do any further dissections. + </para> + <para> + So Ethereal will dissect a packet from the lowest to the highest protocol + layers. + </para> + <para> + But how does Ethereal know, which dissector to choose? + </para> + <para> + At program start, the dissector registers itself at the appropriate place(s). + There are two ways, how a dissector can register itself for packet data: + <itemizedlist> + <listitem> + <command>static</command> if the dissector knows a specific value + of a lower layer, if can directly register itself there (e.g. the HTTP + dissector "knows", that typically the well known TCP port 80 is used to + transport HTTP data). + </listitem> + <listitem> + <command>heuristic</command> if no such well known way exists, the dissector + can register itself for the heuristic mechanism. If a lower layer dissector + has to handle some packet data where no well known way exists, it can + handover the packet to Ethereal's heuristic mechanism. This will ask all + registered upper layer dissectors, if they "like" that data. Each of these + dissectors will typically look into the first few bytes of the packet, if it + contains some characteristic data of that protocol. So the dissector can + accept or reject to dissect that packet. + </listitem> + </itemizedlist> + </para> + <para> + Let's look at an example: We'll assume, Ethereal loads a TCP/IP/Ethernet + packet. Ethereal will call the Ethernet dissector, which will dissect the + Ethernet related data (usually the first 6+6+2 bytes). Then this dissector + calls back into Ethereal and will pass the rest of the data back to + Ethereal. Ethereal in turn will call the next related dissector, in our case + the IP dissector (because of the value 0x800 in the Ethernet type field). + This game will continue, until no more data has to be dissected, or the data + is just unknown to Ethereal. + </para> + <para> + You can control the way how Ethereal calls it's dissectors, see <xref + linkend="ChAdvProtocolDissectionSection"/> for details. + </para> + </section> + +</appendix> +<!-- End of EUG Appendix How it Works --> diff --git a/docbook/eug_src/EUG_app_messages.xml b/docbook/eug_src/EUG_app_messages.xml new file mode 100644 index 0000000000..602d867a29 --- /dev/null +++ b/docbook/eug_src/EUG_app_messages.xml @@ -0,0 +1,34 @@ +<!-- EUG Appendix Messages --> +<!-- $Id$ --> + +<appendix id="AppMessages"> + <title>Ethereal Warnings and Messages</title> + <section> + <title>Capture file format not understood</title> + <para> + If <application>Ethereal</application> cannot decode the capture + file format of the file you have asked it to load, you will receive + a warning box similar to that shown in <xref linkend="AppErr01"/>. + <figure id="AppErr01"> + <title>Read File Format warning</title> + <graphic entityref="EtherealFormatError" format="PNG"/> + </figure> + </para> + </section> + + <section> + <title>Save file error</title> + <para> + If <application>Ethereal</application> cannot open the file you + requested it to save captured packets in, you will receive a + warning box similar to that shown in <xref linkend="AppErr02"/>. + <figure id="AppErr02"><title>Save Error warning</title> + <graphic scale="60" entityref="EtherealSaveError" format="JPG"/> + </figure> + </para> + </section> + + <!-- Simply add more sections above here ... --> + +</appendix> +<!-- End of EUG Appendix Messages --> diff --git a/docbook/eug_src/EUG_app_protocols.xml b/docbook/eug_src/EUG_app_protocols.xml new file mode 100644 index 0000000000..a8985346ab --- /dev/null +++ b/docbook/eug_src/EUG_app_protocols.xml @@ -0,0 +1,25 @@ +<!-- EUG Appendix Protocols --> +<!-- $Id$ --> + +<appendix id="AppProtocols"> + <title>Protocols and Protocol Fields</title> + <para> + Ethereal distinguishes between protocols (e.g. tcp) and protocol fields + (e.g. tcp.port). + </para> + <para> + A comprehensive list of all protocols and protocol fields can be found + at: <ulink url="&EtherealProtocolsPage;">&EtherealProtocolsPage;</ulink> + </para> + + <para> + XXX - update this protocols list. + </para> + + <para> + For a quick reference, the list of available protocols is following: + &ProtoList; + </para> + +</appendix> +<!-- End of EUG Appendix Protocols --> diff --git a/docbook/eug_src/EUG_app_tools.xml b/docbook/eug_src/EUG_app_tools.xml new file mode 100644 index 0000000000..c23c811ef4 --- /dev/null +++ b/docbook/eug_src/EUG_app_tools.xml @@ -0,0 +1,947 @@ +<!-- EUG Appendix Tools --> + +<!-- $Id$ --> + +<appendix id="AppTools"> + <title>Related command line tools</title> + + <section id="AppToolsIntroduction"> + <title>Introduction</title> + <para> + Beside the Ethereal GUI application, there are some command line tools, + which can be helpful for doing some more specialized things. These tools + will be described in this chapter. + </para> + </section> + + <section id="AppToolstcpdump"> + <title>tcpdump: Capturing with tcpdump for viewing with Ethereal</title> + <para> + There are occasions when you want to capture packets using + <command>tcpdump</command> rather than <command>ethereal</command>, + especially when you want to do a remote capture and do not want the + network load associated with running Ethereal remotely (not to + mention all the X traffic polluting your capture). + </para> + <para> + However, the default <command>tcpdump</command> parameters result in a + capture file where each packet is truncated, because + <command>tcpdump</command>, by default, does only capture the first 68 + bytes of each packet. + </para> + <para> + To ensure that you capture complete packets, use the following command: + <programlisting> +tcpdump -i <interface> -s 1500 -w <some-file> + </programlisting> + You will have to specify the correct <command>interface</command> and + the name of a <command>file</command> to save into. In addition, + you will have to terminate the capture with ^C when you believe you + have captured enough packets. + </para> + <note><title>Note!</title> + <para> + tcpdump is not part of the Ethereal distribution. You can get it from: + <ulink url="http://www.tcpdump.org">http://www.tcpdump.org</ulink> for various + platforms. + </para> + </note> + </section> + + <section id="AppToolstethereal"> + <title>tethereal: Terminal-based Ethereal</title> + <para> + <application>Tethereal</application> is a terminal oriented version + of ethereal designed for capturing and displaying packets when an + interactive user interface isn't necessary or available. It supports + the same options as <command>ethereal</command>. For more + information on <command>tethereal</command>, see the manual pages + (<command>man tethereal</command>). + </para> + </section> + + <section id="AppToolscapinfo"> + <title>capinfo: Print information about capture files</title> + <para> + Included with Ethereal is a small utility called + <command>capinfo</command>, which is a command-line utility to + print information about binary capture files. + </para> + <para> + <example id="AppToolscapinfoEx"> + <title>Help information available from capinfo</title> + <programlisting> +$ capinfo -h +Usage: capinfo [-t] [-c] [-s] [-d] [-u] [-a] [-e] [-y] + [-i] [-z] [-h] <capfile> + where -t display the capture type of <capfile> + -c count the number of packets + -s display the size of the file + -d display the total length of all packets in the file + (in bytes) + -u display the capture duration (in seconds) + -a display the capture start time + -e display the capture end time + -y display average data rate (in bytes) + -i display average data rate (in bits) + -z display average packet size (in bytes) + -h produces this help listing. + + If no data flags are given, default is to display all statistics + </programlisting> + </example> + </para> + </section> + + <section id="AppToolseditcap"> + <title>editcap: Edit capture files</title> + <para> + Included with Ethereal is a small utility called + <command>editcap</command>, which is a command-line utility for + working with capture files. Its main function is to remove + packets from capture files, but it can also be used to convert + capture files from one format to another, as well as print + information about capture files. + </para> + <para> + + <example id="AppToolseditcapEx"> + <title>Help information available from editcap</title> + <programlisting> +$ editcap.exe -h +Usage: editcap [-r] [-h] [-v] [-T <encap type>] [-F <capture type>] + [-s <snaplen>] [-t <time adjustment>] + <infile> <outfile> [ <record#>[-<record#>] ... ] + where -r specifies that the records specified should be kept, not deleted, + default is to delete + -v specifies verbose operation, default is silent + -h produces this help listing. + -T <encap type> specifies the encapsulation type to use: + ether - Ethernet + tr - Token Ring + slip - SLIP + ppp - PPP + fddi - FDDI + fddi-swapped - FDDI with bit-swapped MAC addresses + rawip - Raw IP + arcnet - ARCNET + arcnet_linux - Linux ARCNET + atm-rfc1483 - RFC 1483 ATM + linux-atm-clip - Linux ATM CLIP + lapb - LAPB + atm-pdus - ATM PDUs + atm-pdus-untruncated - ATM PDUs - untruncated + null - NULL + ascend - Lucent/Ascend access equipment + isdn - ISDN + ip-over-fc - RFC 2625 IP-over-Fibre Channel + ppp-with-direction - PPP with Directional Info + ieee-802-11 - IEEE 802.11 Wireless LAN + prism - IEEE 802.11 plus Prism II monitor mode header + ieee-802-11-radio - IEEE 802.11 Wireless LAN with radio information + ieee-802-11-bsd - IEEE 802.11 plus BSD WLAN header + ieee-802-11-avs - IEEE 802.11 plus AVS WLAN header + linux-sll - Linux cooked-mode capture + frelay - Frame Relay + frelay-with-direction - Frame Relay with Directional Info + chdlc - Cisco HDLC + ios - Cisco IOS internal + ltalk - Localtalk + pflog-old - OpenBSD PF Firewall logs, pre-3.4 + hhdlc - HiPath HDLC + docsis - Data Over Cable Service Interface Specification + cosine - CoSine L2 debug log + whdlc - Wellfleet HDLC + sdlc - SDLC + tzsp - Tazmen sniffer protocol + enc - OpenBSD enc(4) encapsulating interface + pflog - OpenBSD PF Firewall logs + chdlc-with-direction - Cisco HDLC with Directional Info + bluetooth-h4 - Bluetooth H4 + mtp2 - SS7 MTP2 + mtp3 - SS7 MTP3 + irda - IrDA + user0 - USER 0 + user1 - USER 1 + user2 - USER 2 + user3 - USER 3 + user4 - USER 4 + user5 - USER 5 + user6 - USER 6 + user7 - USER 7 + user8 - USER 8 + user9 - USER 9 + user10 - USER 10 + user11 - USER 11 + user12 - USER 12 + user13 - USER 13 + user14 - USER 14 + user15 - USER 15 + symantec - Symantec Enterprise Firewall + ap1394 - Apple IP-over-IEEE 1394 + bacnet-ms-tp - BACnet MS/TP + default is the same as the input file + -F <capture type> specifies the capture file type to write: + libpcap - libpcap (tcpdump, Ethereal, etc.) + rh6_1libpcap - RedHat Linux 6.1 libpcap (tcpdump) + suse6_3libpcap - SuSE Linux 6.3 libpcap (tcpdump) + modlibpcap - modified libpcap (tcpdump) + nokialibpcap - Nokia libpcap (tcpdump) + lanalyzer - Novell LANalyzer + ngsniffer - Network Associates Sniffer (DOS-based) + snoop - Sun snoop + netmon1 - Microsoft Network Monitor 1.x + netmon2 - Microsoft Network Monitor 2.x + ngwsniffer_1_1 - Network Associates Sniffer (Windows-based) 1.1 + ngwsniffer_2_0 - Network Associates Sniffer (Windows-based) 2.00x + visual - Visual Networks traffic capture + 5views - Accellent 5Views capture + niobserverv9 - Network Instruments Observer version 9 + default is libpcap + -s <snaplen> specifies that packets should be truncated to + <snaplen> bytes of data + -t <time adjustment> specifies the time adjustment + to be applied to selected packets + + A range of records can be specified as well + </programlisting> + </example> + + Where each option has the following meaning: + <variablelist> + <varlistentry><term><command>-r</command></term> + <listitem> + <para> + This option specifies that the frames listed should be kept, + not deleted. The default is to delete the listed frames. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>-h</command></term> + <listitem><para>This option provides help.</para></listitem> + </varlistentry> + <varlistentry><term><command>-v</command></term> + <listitem> + <para> + This option specifies verbose operation. The default is + silent operation. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>-T {encap type}</command></term> + <listitem> + <para> + This option specifies the frame encapsulation type to use. + </para> + <para> + It is mainly for converting funny captures to something + that Ethereal can deal with. + </para> + <para> + The default frame + encapsulation type is the same as the input encapsulation. + </para> + </listitem> + </varlistentry> + + <varlistentry><term><command>-F {capture type}</command></term> + <listitem> + <para> + This option specifies the capture file format to write + the output file in. + </para> + <para> + The default is libpcap format. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>-s {snaplen}</command></term> + <listitem> + <para> + Specifies that packets should be truncated to {snaplen} bytes of data. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>-t {time adjustment}</command></term> + <listitem> + <para> + Specifies the time adjustment to be applied to selected packets. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>{infile}</command></term> + <listitem> + <para> + This parameter specifies the input file to use. It must be + present. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>{outfile}</command></term> + <listitem> + <para> + This parameter specifies the output file to use. It must + be present. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><command>[record#[-][record# ...]]</command></term> + <listitem> + <para> + This optional parameter specifies the records to include + or exclude (depending on the <command>-r</command> option. + You can specify individual records or a range of records. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </section> + + <section id="AppToolsmergecap"> + <title>mergecap: + Merging multiple capture files into one with + <command>mergecap</command> + </title> + <para> + Mergecap is a program that combines multiple saved capture files + into a single output file specified by the -w argument. Mergecap + knows how to read libpcap capture files, including those of tcpdump. + In addition, Mergecap can read capture files from snoop (including + Shomiti) and atmsnoop, LanAlyzer, Sniffer (compressed or + uncompressed), Microsoft Network Monitor, AIX's iptrace, NetXray, + Sniffer Pro, RADCOM's WAN/LAN analyzer, Lucent/Ascend router debug + output, HP-UX's nettl, and the dump output from Toshiba's ISDN + routers. There is no need to tell Mergecap what type of file you are + reading; it will determine the file type by itself. Mergecap is also + capable of reading any of these file formats if they are compressed + using gzip. Mergecap recognizes this directly from the file; the '.gz' + extension is not required for this purpose. + </para> + <para> + By default, it writes the capture file in libpcap format, and writes + all of the packets in both input capture files to the output file. + The -F flag can be used to specify the format in which to write the + capture file; it can write the file in libpcap format (standard + libpcap format, a modified format used by some patched versions of + libpcap, the format used by Red Hat Linux 6.1, or the format used + by SuSE Linux 6.3), snoop format, uncompressed Sniffer format, + Microsoft Network Monitor 1.x format, and the format used by + Windows-based versions of the Sniffer software. + </para> + <para> + Packets from the input files are merged in chronological order based + on each frame's timestamp, unless the -a flag is specified. Mergecap + assumes that frames within a single capture file are already stored + in chronological order. When the -a flag is specified, packets are + copied directly from each input file to the output file, independent + of each frame's timestamp. + </para> + <para> + If the -s flag is used to specify a snapshot length, frames in the + input file with more captured data than the specified snapshot length + will have only the amount of data specified by the snapshot length + written to the output file. This may be useful if the program that + is to read the output file cannot handle packets larger than a + certain size (for example, the versions of snoop in Solaris 2.5.1 and + Solaris 2.6 appear to reject Ethernet frames larger than the standard + Ethernet MTU, making them incapable of handling gigabit Ethernet + captures if jumbo frames were used). + </para> + + <para> + If the -T flag is used to specify an encapsulation type, the + encapsulation type of the output capture file will be forced to + the specified type, rather than being the type appropriate to the + encapsulation type of the input capture file. Note that this merely + forces the encapsulation type of the output file to be the specified + type; the packet headers of the packets will not be translated from the + encapsulation type of the input capture file to the specified + encapsulation type (for example, it will not translate an Ethernet + capture to an FDDI capture if an Ethernet capture is read + and '-T fddi' is specified). + </para> + <example id="AppToolsmergecapEx"> + <title>Help information available from mergecap</title> + <programlisting> +$ mergecap.exe -h +mergecap version 0.10.5 +Usage: mergecap [-hva] [-s <snaplen>] [-T <encap type>] + [-F <capture type>] -w <outfile> <infile> [...] + + where -h produces this help listing. + -v verbose operation, default is silent + -a files should be concatenated, not merged + Default merges based on frame timestamps + -s <snaplen>: truncate packets to <snaplen> bytes of data + -w <outfile>: sets output filename to <outfile> + -T <encap type> encapsulation type to use: + ether - Ethernet + tr - Token Ring + slip - SLIP + ppp - PPP + fddi - FDDI + fddi-swapped - FDDI with bit-swapped MAC addresses + rawip - Raw IP + arcnet - ARCNET + arcnet_linux - Linux ARCNET + atm-rfc1483 - RFC 1483 ATM + linux-atm-clip - Linux ATM CLIP + lapb - LAPB + atm-pdus - ATM PDUs + atm-pdus-untruncated - ATM PDUs - untruncated + null - NULL + ascend - Lucent/Ascend access equipment + isdn - ISDN + ip-over-fc - RFC 2625 IP-over-Fibre Channel + ppp-with-direction - PPP with Directional Info + ieee-802-11 - IEEE 802.11 Wireless LAN + prism - IEEE 802.11 plus Prism II monitor mode header + ieee-802-11-radio - IEEE 802.11 Wireless LAN with radio information + ieee-802-11-bsd - IEEE 802.11 plus BSD WLAN header + ieee-802-11-avs - IEEE 802.11 plus AVS WLAN header + linux-sll - Linux cooked-mode capture + frelay - Frame Relay + frelay-with-direction - Frame Relay with Directional Info + chdlc - Cisco HDLC + ios - Cisco IOS internal + ltalk - Localtalk + pflog-old - OpenBSD PF Firewall logs, pre-3.4 + hhdlc - HiPath HDLC + docsis - Data Over Cable Service Interface Specification + cosine - CoSine L2 debug log + whdlc - Wellfleet HDLC + sdlc - SDLC + tzsp - Tazmen sniffer protocol + enc - OpenBSD enc(4) encapsulating interface + pflog - OpenBSD PF Firewall logs + chdlc-with-direction - Cisco HDLC with Directional Info + bluetooth-h4 - Bluetooth H4 + mtp2 - SS7 MTP2 + mtp3 - SS7 MTP3 + irda - IrDA + user0 - USER 0 + user1 - USER 1 + user2 - USER 2 + user3 - USER 3 + user4 - USER 4 + user5 - USER 5 + user6 - USER 6 + user7 - USER 7 + user8 - USER 8 + user9 - USER 9 + user10 - USER 10 + user11 - USER 11 + user12 - USER 12 + user13 - USER 13 + user14 - USER 14 + user15 - USER 15 + symantec - Symantec Enterprise Firewall + ap1394 - Apple IP-over-IEEE 1394 + bacnet-ms-tp - BACnet MS/TP + default is the same as the first input file + -F <capture type> capture file type to write: + libpcap - libpcap (tcpdump, Ethereal, etc.) + rh6_1libpcap - RedHat Linux 6.1 libpcap (tcpdump) + suse6_3libpcap - SuSE Linux 6.3 libpcap (tcpdump) + modlibpcap - modified libpcap (tcpdump) + nokialibpcap - Nokia libpcap (tcpdump) + lanalyzer - Novell LANalyzer + ngsniffer - Network Associates Sniffer (DOS-based) + snoop - Sun snoop + netmon1 - Microsoft Network Monitor 1.x + netmon2 - Microsoft Network Monitor 2.x + ngwsniffer_1_1 - Network Associates Sniffer (Windows-based) 1.1 + ngwsniffer_2_0 - Network Associates Sniffer (Windows-based) 2.00x + visual - Visual Networks traffic capture + 5views - Accellent 5Views capture + niobserverv9 - Network Instruments Observer version 9 + default is libpcap + </programlisting> + </example> + <variablelist> + <varlistentry><term><command>-h</command></term> + <listitem> + <para>Prints the version and options and exits.</para> + </listitem> + </varlistentry> + <varlistentry><term><command>-v</command></term> + <listitem> + <para> + Causes <command>mergecap</command> to print a number of messages + while it's working. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>-a</command></term> + <listitem> + <para> + Causes the frame timestamps to be ignored, writing all packets + from the first input file followed by all packets from the second + input file. By default, when <command>-a</command> is not + specified, the contents + of the input files are merged in chronological order based on + each frame's timestamp. Note: when merging, mergecap assumes + that packets within a capture file are already in chronological + order. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>-s</command></term> + <listitem> + <para>Sets the snapshot length to use when writing the data.</para> + </listitem> + </varlistentry> + <varlistentry><term><command>-w</command></term> + <listitem> + <para>Sets the output filename.</para> + </listitem> + </varlistentry> + <varlistentry><term><command>-T</command></term> + <listitem> + <para> + Sets the packet encapsulation type of the output capture file. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>-F</command></term> + <listitem> + <para>Sets the file format of the output capture file.</para> + </listitem> + </varlistentry> + </variablelist> + <para> + A simple example merging <filename>dhcp-capture.libpcap</filename> + and <filename>imap-1.libpcap</filename> into + <filename>outfile.libpcap</filename> is shown below. + </para> + <example id="AppToolsmergecapExSimple"> + <title>Simple example of using mergecap</title> + <programlisting>$ mergecap -w outfile.libpcap dhcp-capture.libpcap imap-1.libpcap + </programlisting> + </example> + </section> + + <section id="AppToolstext2pcap" > + <title>text2pcap: Converting ASCII hexdumps to network captures with + <command>text2pcap</command> + </title> + <para> + There may be some occasions when you wish to convert a hex dump of some + network traffic into a libpcap file.</para> + <para> + <command>Text2pcap</command> is a program that reads in an ASCII hex + dump and writes the data described into a libpcap-style capture file. + text2pcap can read hexdumps withmultiple packets in them, and build a + capture file of multiple packets. text2pcap is also capable of + generating dummy Ethernet, IP and UDP headers, in order to build fully + processable packet dumps from hexdumps of application-level data only. + </para> + <para> + Text2pcap understands a hexdump of the form generated by od -t x1. 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 - see -o), of + more than two hex digits. Here is a sample dump that text2pcap can + recognize: + </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 is 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. Multiple + packets are read in with timestamps differing by one second each. + In general, short of these restrictions, text2pcap 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 text2pcap. + 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. + </para> + <para> + Text2pcap 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 headers before each packet. This allows Ethereal + or any other full-packet decoder to handle these dumps. + </para> + <example id="AppToolstext2pcapEx"> + <title>Help information available for text2pcap</title> + <programlisting> +$ text2pcap.exe -h + +Usage: text2pcap.exe [-h] [-d] [-q] [-o h|o] [-l typenum] [-e l3pid] [-i proto] + [-m max-packet] [-u srcp,destp] [-T srcp,destp] [-s srcp,destp,tag] + [-S srcp,destp,tag] [-t timefmt] <input-filename> <output-filename> + +where <input-filename> specifies input filename (use - for standard input) + <output-filename> specifies output filename (use - for standard output) + +[options] are one or more of the following + + -h : Display this help message + -d : Generate detailed debug of parser states + -o hex|oct : Parse offsets as (h)ex or (o)ctal. Default is hex + -l typenum : Specify link-layer type number. Default is 1 (Ethernet). + See net/bpf.h for list of numbers. + -q : Generate no output at all (automatically turns off -d) + -e l3pid : Prepend dummy Ethernet II header with specified L3PID (in + HEX) + Example: -e 0x800 + -i proto : Prepend dummy IP header with specified IP protocol (in + DECIMAL). + Automatically prepends Ethernet header as well. + Example: -i 46 + -m max-packet : Max packet length in output, default is 64000 + -u srcp,destp : Prepend dummy UDP header with specified dest and source ports + (in DECIMAL). + Automatically prepends Ethernet and IP headers as well + Example: -u 30,40 + -T srcp,destp : Prepend dummy TCP header with specified dest and source ports + (in DECIMAL). + Automatically prepends Ethernet and IP headers as well + Example: -T 50,60 + -s srcp,dstp,tag: Prepend dummy SCTP header with specified dest/source ports + and verification tag (in DECIMAL). + Automatically prepends Ethernet and IP headers as well + Example: -s 30,40,34 + -S srcp,dstp,ppi: Prepend dummy SCTP header with specified dest/source ports + and verification tag 0. It also prepends a dummy SCTP DATA + chunk header with payload protocol identifier ppi. + Example: -S 30,40,34 + -t timefmt : Treats the text before the packet as a date/time code; the + specified argument is a format string of the sort supported + by strptime. + Example: The time "10:15:14.5476" has the format code + "%H:%M:%S." + NOTE: The subsecond component delimiter must be specified + (.) but no pattern is required; the remaining number + is assumed to be fractions of a second. + </programlisting> + </example> + <variablelist> + <varlistentry><term><command>-w <filename></command></term> + <listitem> + <para> + Write the capture file generated by <command>text2pcap</command> + to <filename>. The default is to write to standard + output. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>-h</command></term> + <listitem> + <para>Display the help message</para> + </listitem> + </varlistentry> + <varlistentry><term><command>-d</command></term> + <listitem> + <para> + Displays debugging information during the process. Can be + used multiple times to generate more debugging information. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>-q</command></term> + <listitem> + <para>Be completely quiet during the process.</para> + </listitem> + </varlistentry> + <varlistentry><term><command>-o hex|oct</command></term> + <listitem> + <para> Specify the radix for the offsets (hex or octal). Defaults to + hex. This corresponds to the <command>-A</command> option for od. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>-l</command></term> + <listitem> + <para> + Specify the link-layer type of this packet. Default is + Ethernet(1). See net/bpf.h for the complete list of possible + encapsulations. Note that this option should be used if your + dump is a complete hex dump of an encapsulated packet and you + wish to specify the exact type of encapsulation. Example: -l 7 + for ARCNet packets. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>-e l3pid</command></term> + <listitem> + <para> + Include a dummy Ethernet header before each packet. Specify the + L3PID for the Ethernet header in hex. Use this option if your + dump has Layer 3 header and payload (e.g. IP header), but no + Layer 2 encapsulation. Example: -e 0x806 to specify an ARP + packet. + </para> + <para> + For IP packets, instead of generating a fake Ethernet header you + can also use -l 12 to indicate a raw IP packet to Ethereal. Note + that -l 12 does not work for any non-IP Layer 3 packet (e.g. + ARP), whereas generating a dummy Ethernet header with -e works + for any sort of L3 packet. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>-u srcport destport</command></term> + <listitem> + <para> + Include dummy UDP headers before each packet. Specify the + source and destination UDP ports for the packet in decimal. + Use this option if your dump is the UDP payload of a packet but + does not include any UDP, IP or Ethernet headers. Note that this + automatically includes appropriate Ethernet and IP headers with + each packet. Example: -u 1000 69 to make the packets look like + TFTP/UDP packets. + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + + <section id="AppToolsidl2eth" > + <title>idl2eth: + Creating dissectors from Corba IDL files with + <command>idl2eth</command> + </title> + <para> + In an ideal world idl2eth would be mentioned in the users guide + in passing and documented in the developers guide. As the + developers guide + has not yet been completed it will be documented here. + </para> + <section> + <title>What is it?</title> + <para> + As you have probably guessed from the name, + <command>idl2eth</command> takes a + user specified IDL file and attempts to build a dissector that + can decode the IDL traffic over GIOP. The resulting file is + "C" code, that should compile okay as an ethereal dissector. + </para> + <para> + <command>idl2eth</command> basically parses the data struct given to + it by the omniidl compiler, and using the GIOP API available in + packet-giop.[ch], generates get_CDR_xxx calls to decode the + CORBA traffic on the wire. + </para> + <para>It consists of 4 main files.</para> + <variablelist> + <varlistentry><term><filename>README.idl2eth</filename></term> + <listitem> + <para>This document</para> + </listitem> + </varlistentry> + <varlistentry><term><filename>ethereal_be.py</filename></term> + <listitem> + <para>The main compiler backend</para> + </listitem> + </varlistentry> + <varlistentry><term><filename>ethereal_gen.py</filename></term> + <listitem> + <para>A helper class, that generates the C code.</para> + </listitem> + </varlistentry> + <varlistentry><term><filename>idl2eth</filename></term> + <listitem> + <para> A simple shell script wrapper that the end user should + use to generate the dissector from the IDL file(s).</para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section> + <title>Why do this?</title> + <para> + It is important to understand what CORBA traffic looks + like over GIOP/IIOP, and to help build a tool that can assist + in troubleshooting CORBA interworking. This was especially the + case after seeing a lot of discussions about how particular + IDL types are represented inside an octet stream. + </para> + <para> + I have also had comments/feedback that this tool would be good for say + a CORBA class when teaching students what CORBA traffic looks like + "on the wire". + </para> + <para> + It is also COOL to work on a great Open Source project such as + the case with "Ethereal" ( + <ulink url="http://www.ethereal.com">http://www.ethereal.com</ulink> + ) + </para> + </section> + <section><title>How to use idl2eth</title> + <para> + To use the idl2eth to generate ethereal dissectors, you + need the following: + </para> + <orderedlist> + <title>Prerequisites to using idl2eth</title> + <listitem> + <para> + Python must be installed. See + <ulink url="http://python.org/"/> + </para> + </listitem> + <listitem> + <para> + omniidl from the the omniORB package must be available. See + <ulink url="http://omniorb.sourceforge.net/"/> + </para> + </listitem> + <listitem> + <para> + Of course you need ethereal installed to compile the + code and tweak it if required. idl2eth is part of the + standard Ethereal distribution + </para> + </listitem> + </orderedlist> + <para> + To use idl2eth to generate an ethereal dissector from an idl file + use the following proceedure: + </para> + <orderedlist> + <title> + Proceedure for converting a Corba idl file into an ethereal + dissector + </title> + <listitem> + <para> + To write the C code to stdout. + <programlisting>idl2eth <your file.idl></programlisting> + eg: <programlisting>idl2eth echo.idl</programlisting> + </para> + </listitem> + <listitem> + <para> + To write to a file, just redirect the output. + <programlisting>idl2eth echo.idl > packet-test-idl.c</programlisting> + You may wish to comment out the register_giop_user_module() code + and that will leave you with heuristic dissection. + </para> + </listitem> + </orderedlist> + <para> + If you dont want to use the shell script wrapper, then try + steps 3 or 4 instead.</para> + <orderedlist continuation="continues"> + <listitem> + <para>To write the C code to stdout. + <programlisting>Usage: omniidl -p ./ -b ethereal_be <your file.idl></programlisting> + eg: + <programlisting>omniidl -p ./ -b ethereal_be echo.idl</programlisting> + </para> + </listitem> + <listitem> + <para> + To write to a file, just redirect the output. + <programlisting>omniidl -p ./ -b ethereal_be echo.idl > packet-test-idl.c</programlisting> + You may wish to comment out the register_giop_user_module() code + and that will leave you with heuristic dissection. + </para> + </listitem> + <listitem> + <para> + Copy the resulting C code to your ethereal src directory, + edit the 2 make files to include the packet-test-idl.c + <programlisting> +cp packet-test-idl.c /dir/where/ethereal/lives/ +edit Makefile.am +edit Makefile.nmake + </programlisting> + </para> + </listitem> + <listitem> + <para>Run configure + <programlisting>./configure (or ./autogen.sh)</programlisting> + </para> + </listitem> + <listitem> + <para> Compile the code + <programlisting>make</programlisting> + </para> + </listitem> + <listitem> + <para>Good Luck !!</para> + </listitem> + </orderedlist> + </section> + <section><title>TODO</title> + <orderedlist> + <listitem> + <para> + Exception code not generated (yet), but can be added manually. + </para> + </listitem> + <listitem> + <para> + Enums not converted to symbolic values (yet), but can be added + manually. + </para> + </listitem> + <listitem> + <para>Add command line options etc</para> + </listitem> + <listitem> + <para>More I am sure :-)</para> + </listitem> + </orderedlist> + </section> + <section><title>Limitations</title> + <para> + See the TODO list inside <filename>packet-giop.c</filename> + </para> + </section> + <section><title>Notes</title> + <orderedlist> + <listitem> + <para> + The "-p ./" option passed to omniidl indicates that the + ethereal_be.py and ethereal_gen.py are residing in the + current directory. This may need + tweaking if you place these files somewhere else. + </para> + </listitem> + <listitem> + <para> + If it complains about being unable to find some modules + (eg tempfile.py), + you may want to check if PYTHONPATH is set correctly. + On my Linux box, it is PYTHONPATH=/usr/lib/python1.5/ + </para> + </listitem> + </orderedlist> + </section> + </section> +</appendix> +<!-- End of EUG Appendix Tools --> + + diff --git a/docbook/eug_src/EUG_chapter_advanced.xml b/docbook/eug_src/EUG_chapter_advanced.xml new file mode 100644 index 0000000000..90b81d0889 --- /dev/null +++ b/docbook/eug_src/EUG_chapter_advanced.xml @@ -0,0 +1,283 @@ +<!-- EUG Chapter Advanced --> + +<!-- $Id: --> + +<chapter id="ChapterAdvanced"> + <title>Advanced Features</title> + + <section id="ChAdvIntroduction"><title>Introduction</title> + <para> + In this chapter some advanced features of Ethereal will be described. + </para> + </section> + + <section id="ChAdvFollowTCPSection"><title>Following TCP streams</title> + <para> + There will be occasions when you would like to see the data from a TCP + session in the order that the application layer sees it. Perhaps + you are looking for passwords in a Telnet stream, or you are + trying to make sense of a data stream. If so, Ethereal's ability to + follow a TCP stream will be useful to you. + </para> + <para> + Simply select a TCP packet in the stream/connection you are interested + in and then select the Follow TCP Stream menu item from the Ethereal + Tools menu. Ethereal will pop up a separate window with all the data + from the TCP stream laid out in order, as shown in + <xref linkend="ChAdvFollowStream"/>. + </para> + <section><title>The "Follow TCP stream" dialog box </title> + <figure id="ChAdvFollowStream"> + <title>The "Follow TCP Stream" dialog box</title> + <graphic entityref="EtherealFollowStream" format="PNG"/> + </figure> + <para> + You can choose from the following actions: + <orderedlist> + <listitem> + <para> + <command>Save As</command> Save the stream data in the currently + selected format. + </para> + </listitem> + <listitem> + <para> + <command>Print</command> Print the stream data in the currently + selected format. + </para> + </listitem> + <listitem> + <para> + <command>Direction</command> Choose the stream direction to be + displayed ("Entire conversation", "data from A to B only" or "data + from B to A only"). + </para> + </listitem> + <listitem> + <para> + <command>Filter out this stream</command> Apply a display filter + removing the current TCP stream data from the display. + </para> + </listitem> + <listitem> + <para> + <command>Close</command> Close this dialog box. + </para> + </listitem> + </orderedlist> + </para> + <para> + You can then choose to view the data in one of four formats: + <orderedlist> + <listitem> + <para> + <command>ASCII</command>. In this view you see the data from + each end in ASCII, but alternating according to when each + end sent data. Unfortunately, non-printing characters do not + print. + </para> + </listitem> + <listitem> + <para> + <command>EBCDIC</command>. For the big-iron freaks out there. + </para> + </listitem> + <listitem> + <para> + <command>HEX Dump</command>. This allows you to see all the + data, but you lose the ability to read it in ASCII. + </para> + </listitem> + <listitem> + <para> + <command>C Arrays</command>. This allows you to import the stream data + into your own C program. + </para> + </listitem> + </orderedlist> + </para> + <note> + <title>Note!</title> + <para> + It is worthwhile noting that Follow TCP Stream installs a filter + to select all the packets in the TCP stream you have selected. + </para> + </note> + </section> + </section> + + <section id="ChAdvReassemblySection"><title>Packet Reassembling/Desegmenting</title> + <para> + XXX - rework this chapter, as it's still a bit confusing. + </para> + <section><title>What is it?</title> + <para> + Often network protocols needs to transport large chunks of data, which are + complete in itself, e.g. when transferring a file. The underlying + protocol might not be able to handle that chunk size (e.g. limitation of + the network packet size), or is stream-based like TCP, which doesn't know + data chunks at all. + </para> + <para> + In that case the network protocol has to handle that chunks itself and + (if required) spreading the data over multiple packets. It also needs a + mechanism to find back the chunk boundaries on the receiving side. + </para> + <note><title>Reassembling vs. Desegmenting!</title> + <para> + Desegmenting is a slightly different mechanism compared to reassembling, + but doing the same thing. Both mechanisms combine traffic back together, + in this chapter only the term reassembling will be used. + </para> + </note> + </section> + <section><title>How Ethereal handles it</title> + <para> + For some of the network protocols Ethereal knows of, a mechanism is + implemented to find, decode and display this chunks of data. + Ethereal will try to find the corresponding packets of this chunk, + and will show the combined data as additional pages in the + "Packet Bytes" pane, see <xref linkend="ChUsePacketBytesPaneSection"/>. + </para> + <note><title>Note!</title> + <para> + Reassembling might take place in several protocol layers, so it's possible + that multiple tabs in the "Packet Bytes" pane appear. + </para> + </note> + <note><title>Note!</title> + <para> + You will find the reassembled data in the last packet of the chunk. + </para> + </note> + <para> + Some examples: + <itemizedlist> + <listitem> + <para> + In a <command>HTTP</command> GET response, the requested data (e.g. a + HTML page) is returned. Ethereal will show the hex dump of the data in + a new tab "Uncompressed entity body" in the "Packet Bytes" pane. + </para> + </listitem> + <listitem> + <para> + A <command>DCE-RPC</command> (Remote Procedure Call) client send a + request to the server and expects a response back from it. Both the + request and the response is a complete chunk of data and will be + shown as a new tab "Reassembled DCE/RPC" in the "Packet Bytes" pane. + </para> + </listitem> + </itemizedlist> + </para> + </section> + + <section><title>Reassembling is disabled!</title> + <para> + Reassembling is usually disabled in the preferences by default, as it + slows down packet processing a bit. + </para> + <para> + Enabling reassembling of a protocol typically requires two things: + <orderedlist> + <listitem> + <para> + the lower level protocol (e.g., TCP) must support + reassembly. Often this reassembly can be enabled or disabled at will + via the protocol preferences. + </para> + </listitem> + <listitem> + <para> + the higher level protocol (e.g., HTTP) must use the + reassembly mechanism to reassemble fragmented protocol data. This too + can often be enabled or disabled via the protocol preferences. + </para> + </listitem> + </orderedlist> + </para> + <para> + As a result, if reassembly of protocol Y on top of protocol X + must be enabled, it is wise to take a look at the protocol preferences for + both protocols. Check whether protocol X allows subdissectors to + reassemble, and check whether protocol Y supports reassembly + and has it enabled. + </para> + <para> + For example: if you have HTTP on top of TCP, you have to enable the TCP + preference "Allow subdissectors to reassemble" and enable the HTTP + preference "Reassemble". + </para> + </section> + </section> + + <section id="ChAdvNameResolutionSection"><title>Name Resolution</title> + <para> + Name resolution tries to resolve some of the address values to human + readable names. This conversion might fail. For example, the name might be + unknown. Some of the lookups are done with data from your local + machine, while others asking network services such as DNS. + </para> + <para> + XXX - add ipxnets name resolution explanation. + </para> + <note><title>Note!</title> + <para> + You might see packets to/from your machine in your capture file, which are + caused by name resolution network services (e.g. DNS packets). + </para> + </note> + <note><title>Note!</title> + <para> + The resolved names are not stored in the capture file or somewhere else, + so the resolved names might not be available if you open the capture file + later or on another machine. + </para> + </note> + <para> + The name resolution feature can be en-/disabled separately for the + following protocol layers: + </para> + <section><title>MAC Layer</title> + <para><command>ARP name resolution</command> + Convert an ethernet address to the corresponding IP address + (e.g. 00:09:5b:01:02:03 -> 192.168.0.1). + </para> + <para><command>Ethernet manufacturer codes</command> + If the ARP name resolution failed, Ethereal tries to convert the first 3 + bytes of an ethernet address to an abbreviated manufacturer name, which + has been assigned by the IETF (e.g. 00:09:5b:01:02:03 -> Netgear_01:02:03). + </para> + </section> + <section><title>Network Layer</title> + <para><command>DNS name resolution</command> + Convert an IP address to the hostname associated with it + (e.g. 65.208.228.223 -> www.ethereal.com). + </para> + <warning> + <title>Warning!</title> + <para> + Enabling network name resolution when your name server is + unavailable may significantly slow Ethereal while it waits + for all of the name server requests to time out. Use ADNS in that + case. + </para> + </warning> + </section> + <section><title>Transport Layer</title> + <para><command>TCP/UDP port conversion</command> + Convert a TCP or UDP port to its well known name (e.g. 80 -> http). + </para> + </section> + <section><title>ADNS</title> + <para> + As noted, DNS lookups can significantly slow down Ethereal and make it + appear frozen, which can be very annoying. To solve this, Ethereal can use + the ADNS library, which handles DNS calls asynchronously. + </para> + </section> + </section> + +</chapter> +<!-- End of EUG Chapter Advanced --> + diff --git a/docbook/eug_src/EUG_chapter_build_install.xml b/docbook/eug_src/EUG_chapter_build_install.xml new file mode 100644 index 0000000000..d18f2ca1fc --- /dev/null +++ b/docbook/eug_src/EUG_chapter_build_install.xml @@ -0,0 +1,588 @@ +<!-- EUG Chapter BuildInstall --> +<!-- $Id$ --> + +<chapter id="ChapterBuildInstall"> + <title>Building and Installing Ethereal</title> + <section id="ChBuildInstallIntro"> + <title>Introduction</title> + <para> + As with all things, there must be a beginning, and so it is with + Ethereal. To use Ethereal, you must: + <itemizedlist> + <listitem> + <para> + Obtain a binary package for your operating system, or + </para> + </listitem> + <listitem> + <para> + Obtain the source and build Ethereal for your operating system. + </para> + </listitem> + </itemizedlist> + </para> + <para> + Currently, only two or three Linux distributions ship Ethereal, and + they are commonly shipping an out-of-date version. No other versions + of UNIX ship Ethereal so far, and Microsoft does not ship it with any + version of Windows. For that reason, you will need to know where to + get the latest version of Ethereal and how to install it. + </para> + <para> + This chapter shows you how to obtain source and binary packages, + and how to build Ethereal from source, should you choose to do so. + </para> + <para> + The following are the general steps you would use: + <orderedlist> + <listitem> + <para> + Download the relevant package for your needs, e.g. source or + binary distribution. + </para> + </listitem> + <listitem> + <para> + Build the source into a binary, if you have downloaded the + source. + </para> + <para> + This may involve building and/or installing other necessary packages. + </para> + </listitem> + <listitem> + <para> + Install the binaries into their final destinations. + </para> + </listitem> + </orderedlist> + </para> + </section> + + <section id="ChBuildInstallDistro"> + <title>Obtaining the source and binary distributions</title> + <para> + You can obtain both source and binary distributions from the Ethereal + web site: <ulink url="&EtherealWebSite;">&EtherealWebSite;</ulink>. + Simply select the download link, and then select either the source + package or binary package of your choice from the mirror site closest + to you. + </para> + <note> + <title>Download all the needed files</title> + <para> + In general, unless you have already downloaded Ethereal + before, you will most likely need to download several source + packages if you are building Ethereal from source. This is + covered in more detail below. <!-- Make a ref --> + </para> + </note> + <para> + Once you have downloaded the relevant files, you can go on to the + next step. + </para> + <note> + <title>Note!</title> + <para> + While you will find a number of binary packages available on the + Ethereal web site, you might not find one for your platform, and + they often tend to be several versions behind the current released + version, as they are contributed by people who have the platforms + they are built for. + </para> + <para> + For this reason, you might want to pull down the source distribution + and build it, as the process is relatively simple. + </para> + </note> + </section> + + <section id="ChBuildInstallBeforeBuild"> + <title>Before you build <application>Ethereal</application> under UNIX</title> + <para> + Before you build Ethereal from sources, or install a binary package, + you must ensure that you have the following other packages installed: + <itemizedlist> + <listitem> + <para>GTK+, The GIMP Tool Kit.</para> + <para> + You will also need Glib. Both can be obtained from + <ulink url="http://www.gtk.org">www.gtk.org</ulink> + </para> + </listitem> + <listitem> + <para> + libpcap, the packet capture software that Ethereal uses. + </para> + <para> + You can obtain libpcap from + <ulink url="http://www.tcpdump.org">www.tcpdump.org</ulink> + </para> + </listitem> + </itemizedlist> + Depending on your system, you may be able to install these from + binaries, e.g. RPMs, or you may need to obtain them in source code + form and build them. + </para> + <para> + If you have downloaded the source for GTK+, the instructions shown + in <xref linkend="Ch02Ex1"/> may provide some help in building it: + <example id="Ch02Ex1"> + <title>Building GTK+ from source</title> + <programlisting> +gzip -dc gtk+-1.2.10.tar.gz | tar xvf - +<much output removed> +cd gtk+-1.2.10 +./configure +<much output removed> +make +<much output removed> +make install +<much output removed> + </programlisting> + </example> + <note> + <title>Note!</title> + <para> + You may need to change the version number of gtk+ in + <xref linkend="Ch02Ex1"/> to match the version of GTK+ you have + downloaded. The directory you change to will change if the + version of GTK+ changes, and in all cases, + <command>tar xvf -</command> will show you the name of the + directory you should change to. + </para> + </note> + <note> + <title>Note!</title> + <para> + If you use Linux, or have GNU <command>tar</command> installed, + you can use <command>tar zxvf gtk+-1.2.10.tar.gz</command>. It + is also possible to use <command>gunzip -c</command> or + <command>gzcat</command> rather than <command>gzip -dc</command> + on many UNIX systems. + </para> + </note> + <note> + <title>Note!</title> + <para> + If you downloaded gtk+ or any other tar file using Windows, + you may find your file called gtk+-1_2_8_tar.gz. + </para> + </note> + </para> + <para> + You should consult the GTK+ web site if any errors occur in carrying + out the instructions in <xref linkend="Ch02Ex1"/>. + </para> + <para> + If you have downloaded the source to libpcap, the general instructions + shown in <xref linkend="Ch2Ex2"/> will assist in building it. Also, + if your operating system does not support <command>tcpdump</command>, + you might also want to download it from the + <ulink url="http://www.tcpdump.org">tcpdump</ulink> web site and + install it. + <example id="Ch2Ex2"> + <title>Building and installing libpcap</title> + <programlisting> +gzip -dc libpcap-0.8.3.tar.Z | tar xvf - +<much output removed> +cd libpcap_0_8_3 +./configure +<much output removed> +make +<much output removed> +make install +<much output removed> +make install-incl +<much output removed> + </programlisting> + </example> + </para> + <note> + <title>Note!</title> + <para> + The directory you should change to will depend on the version of + libpcap you have downloaded. In all cases, + <command>tar xvf -</command> will show you the name of the + directory that has been unpacked. + </para> + </note> + <para> + When installing the include files, you might get the error shown + in <xref linkend="Ch02Ex3"/> when you submit the command + <command>make install-incl</command>. + <example id="Ch02Ex3"> + <title>Errors while installing the libpcap include files</title> + <programlisting> +/usr/local/include/pcap.h +/usr/bin/install -c -m 444 -o bin -g bin ./pcap-namedb.h \ +/usr/local/include/pcap-namedb.h +/usr/bin/install -c -m 444 -o bin -g bin ./net/bpf.h \ +/usr/local/include/net/bpf.h +/usr/bin/install: cannot create regular file \ +`/usr/local/include/net/bpf.h': No such file or directory +make: *** [install-incl] Error 1 + </programlisting> + </example> + If you do, simply create the missing directory with the following + command: + <programlisting> +mkdir /usr/local/include/net + </programlisting> + and rerun the command <command>make install-incl</command>. + </para> + <para> + Under RedHat 6.x and beyond (and distributions based on it, like + Mandrake) you can simply install each of the packages you need from + RPMs. Most Linux systems will install GTK+ and Glib in anycase, + however, you will probably need to install the devel versions of + each of these packages. The commands shown in <xref linkend="Ch02Ex4"/> + will install all the needed RPMs if they are not already installed. + <example id="Ch02Ex4"> + <title> + Installing required RPMs under RedHat Linux 6.2 and beyond + </title> + <programlisting> +cd /mnt/cdrom/RedHat/RPMS +rpm -ivh glib-1.2.6-3.i386.rpm +rpm -ivh glib-devel-1.2.6-3.i386.rpm +rpm -ivh gtk+-1.2.6-7.i386.rpm +rpm -ivh gtk+-devel-1.2.6-7.i386.rpm +rpm -ivh libpcap-0.4-19.i386.rpm + </programlisting> + </example> + </para> + <note> + <para> + If you are using a version of RedHat later than 6.2, the required + RPMs have most likely changed. Simply use the correct RPMs from your + distribution. + </para> + </note> + <para> + Under Debian you can install Ethereal using apt-get. apt-get will + handle any dependency issues for you. <xref linkend="Ch02Ex5"/> shows + how to do this. + <example id="Ch02Ex5"> + <title>Installing debs under Debian</title> + <programlisting> +apt-get install ethereal + </programlisting> + </example> + </para> + </section> + + <section id="ChBuildInstallUnixBuild"> + <title>Building Ethereal from source under UNIX</title> + <para> + Use the following general steps if you are building Ethereal from + source under a UNIX operating system: + <orderedlist> + <listitem> + <para> + Unpack the source from its <command>gzip</command>'d + <command>tar</command> file. If you are using Linux, or your + version of UNIX uses GNU <command>tar</command>, you can use the + following command: + <programlisting> +tar zxvf ethereal-&EtherealCurrentVersion;-tar.gz + </programlisting> + </para> + <para> + For other versions of UNIX, You will want to use the following + commands: + <programlisting> +gzip -d ethereal-&EtherealCurrentVersion;-tar.gz +tar xvf ethereal-&EtherealCurrentVersion;-tar + </programlisting> + <note> + <title>Note!</title> + <para> + The pipeline + <command> + gzip -dc ethereal-&EtherealCurrentVersion;-tar.gz | tar xvf - + </command> will work here as well. + </para> + </note> + <note> + <title>Note!</title> + <para> + If you have downloaded the Ethereal tarball under Windows, + you may find that your browser has created a file with + underscores rather than periods in its file name. + </para> + </note> + </para> + </listitem> + <listitem> + <para> + Change directory to the Ethereal source directory. + </para> + </listitem> + <listitem> + <para> + Configure your source so it will build correctly for your + version of UNIX. You can do this with the following command: + <programlisting> +./configure + </programlisting> + </para> + <para> + If this step fails, you will have to rectify the problems and + rerun <command>configure</command>. Troubleshooting hints are + provided in <xref linkend="ChBuildInstallUnixTrouble"/>. + </para> + </listitem> + <listitem> + <para> + Build the sources into a binary, with the <command>make</command> + command. For example: + <programlisting> +make + </programlisting> + </para> + </listitem> + <listitem> + <para> + Install the software in its final destination, using the command: + <programlisting> +make install + </programlisting> + </para> + </listitem> + </orderedlist> + </para> + <para> + Once you have installed Ethereal with <command>make install</command> + above, you should be able to run it by entering + <command>ethereal</command>. + </para> + </section> + + <section id="ChBuildInstallUnixInstallBins"> + <title>Installing the binaries under UNIX</title> + <para> + In general, installing the binary under your version of UNIX will be + specific to the installation methods used with your version of UNIX. + For example, under AIX, you would use <command>smit</command> to + install the Ethereal binary package, while under Tru64 UNIX + (formerly Digital UNIX) you would use <command>setld</command>. + </para> + + <section> + <title>Installing from rpm's under RedHat and alike</title> + <para> + Use the following command to install the Ethereal RPM that you have + downloaded from the Ethereal web site: + <programlisting> +rpm -ivh ethereal-0.10.5-0.2.2.i386.rpm + </programlisting> + If the above step fails because of missing dependencies, install the + dependencies first, and then retry the step above. See + <xref linkend="Ch02Ex4"/> for information on what RPMs you will need + to have installed. + </para> + </section> + + <section> + <title>Installing from deb's under Debian</title> + <para> + Use the following command to install Ethereal under Debian: + <programlisting> +apt-get install ethereal + </programlisting> + apt-get should take care of all of the dependency issues for you. + </para> + </section> + </section> + + <section id="ChBuildInstallUnixTrouble"> + <title>Troubleshooting during the install on Unix</title> + <para> + A number of errors can occur during the installation process. + Some hints on solving these are provided here. + </para> + <para> + If the <command>configure</command> stage fails, you will need to find + out why. You can check the file <filename>config.log</filename> in the + source directory to find out what failed. The last few lines of this + file should help in determining the problem. + </para> + <para> + The standard problems are that you do not have GTK+ on your system, + or you do not have a recent enough version of GTK+. The + <command>configure</command> will also fail if you do not have libpcap + (at least the required include files) on your system. + </para> + <para> + Another common problem is for the final compile and link stage to + terminate with a complaint of: <errorname>Output too long.</errorname> + This is likely to be caused by an antiquated <command>sed</command> + (such as the one shipped with Solaris). Since <command>sed</command> is + used by the <command>libtool</command> script to construct the final + link command, this leads to mysterious problems. This can be + resolved by downloading a recent version of sed from + <ulink url="http://directory.fsf.org/GNU/sed.html"/>. + </para> + <para> + If you cannot determine what the problems are, send mail to the + <command>ethereal-dev</command> mailing list explaining your problem, + and including the output from <filename>config.log</filename> and + anything else you think is relevant, like a trace of the + <command>make</command> stage. + </para> + </section> + + <section id="ChBuildInstallWinBuild"> + <title>Building from source under Windows</title> + <para> + It is recommended to use the binary installer for Windows, + until you want to start developing Ethereal on this platform. + </para> + <para> + For further information how to build Ethereal for Windows from the + sources, have a look at the file Readme.win32, which + can be found in the doc directory of the sources. + </para> + </section> + + <section id="ChBuildInstallWinInstall"> + <title>Installing Ethereal under Windows</title> + <para> + In this section we explore installing Ethereal under Windows from the + binary packages. You must follow two steps: + <orderedlist> + <listitem> + <para> + <command>Install WinPcap</command>. + You will find a single installer exe called something + like "auto-installer", which can be installed under various Windows + systems, including 9x/Me/NT4.0/2000/XP. This installer is located at: + <ulink url="&WinPcapDownloadWebsite;">&WinPcapDownloadWebsite;</ulink>. + You should download the latest released version (the latest one not + marked "beta") and execute it. + </para> + </listitem> + <listitem> + <para> + <command>Install Ethereal</command>. + You may acquire a binary installable of Ethereal at + <ulink url="&EtherealBinariesPage;">&EtherealBinariesPage;</ulink>. + Download the installer and execute it. + </para> + </listitem> + </orderedlist> + Both steps are extremely simply, as you only have to download and + install the two exe files. + </para> + <section id="ChBuildInstallComponents"> + <title>Installable Components</title> + <para> + Beside the usual installer options like where to install the program, + there are several optional components (if you are unsure, just keep the + default settings). + </para> + <para> + The programs being installed + (both Ethereal GTK1 and 2 cannot be installed at the same time): + <itemizedlist> + <listitem><para> + <command>Etheral GTK1</command> - Ethereal is a GUI network protocol + analyzer. + </para></listitem> + <listitem><para> + <command>Etheral GTK2</command> - Ethereal is a GUI network protocol + analyzer (using the modern GTK2 GUI toolkit). + </para></listitem> + <listitem><para> + <command>GTK-Wimp</command> - GTKWimp is the GTK2 windows impersonator + (native Win32 look and feel). + </para></listitem> + <listitem><para> + <command>Tethereal</command> - Tethereal is a command-line based network + protocol analyzer. + </para></listitem> + <listitem><para> + <command>Editcap</command> - Editcap is a program that reads a capture + file and writes some or all of the packets into another capture file. + </para></listitem> + <listitem><para> + <command>Text2Pcap</command> - Text2pcap is a program that reads in an + ASCII hex dump and writes the data into a libpcap-style capture file. + </para></listitem> + <listitem><para> + <command>Mergecap</command> - Mergecap is a program that combines multiple + saved capture files into a single output file. + </para></listitem> + <listitem><para> + <command>Capinfo</command> - Capinfo is a program that provides + information on capture files. + </para></listitem> + </itemizedlist> + The dissection extensions for Ethereal and Tethereal: + <itemizedlist> + <listitem><para> + <command>Plugins</command> - Plugins with some extended dissections. + </para></listitem> + <listitem><para> + <command>SNMP MIBs</command> - SNMP MIBs for a more detailed SNMP + dissection. + </para></listitem> + </itemizedlist> + The environment related things: + <itemizedlist> + <listitem><para> + <command>Start Menu Shortcuts</command> - Some start menu shortcuts. + </para></listitem> + <listitem><para> + <command>Desktop Icon</command> - Ethereal desktop icon. + </para></listitem> + <listitem><para> + <command>Associate file extensions to Ethereal</command> - Associate + standard network trace files to Ethereal. + </para></listitem> + </itemizedlist> + </para> + </section> + <section id="ChBuildInstallWinUpdate"> + <title>Update</title> + <para> + From time to time you may want to update your installed Ethereal to a more + recent version. If you join Ethereal's announce mailing list, you will be + informed about new Ethereal versions, see <xref + linkend="ChIntroMailingLists"/> for details how to subscribe to this list. + <itemizedlist> + <listitem> + <para> + <command>Update Ethereal</command>. + New versions of Ethereal usually become available every 4-8 weeks. + Updating Ethereal is done the same way as installing it, you simply + download and start the installer exe. A reboot is usually not required and + all your personal settings remain unchanged. + </para> + </listitem> + <listitem> + <para> + <command>Update WinPcap</command>. + New versions of WinPcap are less frequently available, maybe only once a + year. You will find WinPcap update instructions where you can download new + versions. Usually you have to reboot the machine after installing a new + WinPcap version. + </para> + </listitem> + </itemizedlist> + </para> + </section> + + <section id="ChBuildInstallWinUninstall"> + <title>Uninstall Ethereal</title> + <para> + You can uninstall Ethereal the usual way, using the Software option + inside the Control Panel. You will find two entries, one for Ethereal + itself and one for WinPcap. + </para> + </section> + </section> + +</chapter> +<!-- End of EUG Chapter 2 --> diff --git a/docbook/eug_src/EUG_chapter_capture.xml b/docbook/eug_src/EUG_chapter_capture.xml new file mode 100644 index 0000000000..10a4297593 --- /dev/null +++ b/docbook/eug_src/EUG_chapter_capture.xml @@ -0,0 +1,950 @@ +<!-- EUG Chapter Capture --> +<!-- $Id$ --> + +<chapter id="ChapterCapture"> + <title>Capturing Live Network Data</title> + + <section id="ChCapIntroduction"> + <title>Introduction</title> + <para> + Capturing live network data is one of the major features of Ethereal. + </para> + <para> + The Ethereal capture engine provides the following features: + </para> + <para> + <itemizedlist> + <listitem><para> + Capture from different kinds of network hardware (Ethernet, Token Ring, + ATM, ...). + </para></listitem> + <listitem><para> + Stop the capture on different triggers like: amount of captured data, + captured time, captured number of packets. + </para></listitem> + <listitem><para> + Simultaneously show decoded packets while keep on capturing. + </para></listitem> + <listitem><para> + Filter packets, reducing the amount of data to be captured, see <xref + linkend="ChCapCaptureFilterSection"/>. + </para></listitem> + <listitem><para> + Capturing into multiple files while doing a long term capture, and in + addition the option to form a ringbuffer of these files, keeping only + the last x files, useful for a "very long term" capture, see <xref + linkend="ChCapCaptureFiles"/>. + </para></listitem> + </itemizedlist> + The capture engine still lacks the following features: + <itemizedlist> + <listitem><para> + Simultaneous capturing from multiple network interfaces (however, you + can start multiple instances of Ethereal and merge capture files later). + </para></listitem> + <listitem><para> + Stop capturing (or doing some other action), depending on the captured + data. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id="ChCapCapturingSection"><title>Start Capturing</title> + <para> + There are three methods you can use to start capturing packets with + Ethereal: + <orderedlist> + <listitem> + <para> + You can get an overview of the available local interfaces using the + "Capture interfaces" dialog box, see + <xref linkend="ChCapCaptureInterfacesDialog"/>. You can also start a + capture from this dialog box, using (one of) the "Capture" button. + </para> + </listitem> + <listitem> + <para> + You can start capturing using the "Capture Options" dialog box, see + <xref linkend="ChCapCaptureOptionsDialog"/>. + </para> + </listitem> + <listitem> + <para> + If you already know the name of the capture interface, you can start + Ethereal from the command line and use the following: + <programlisting> +ethereal -i eth0 -k + </programlisting> + This will start Ethereal capturing on interface eth0. + </para> + </listitem> + </orderedlist> + </para> + </section> + + <section id="ChCapInterfaceSection"> + <title>The "Capture Interfaces" dialog box</title> + <para> + When you select "Interfaces..." from the Capture menu, Ethereal pops + up the "Capture Interfaces" dialog box as shown in + <xref linkend="ChCapCaptureInterfacesDialog"/>. + <warning><title>Warning!</title> + <para> + As the "Capture Interfaces" dialog is showing live captured data, it is + consuming a lot of system ressources. Close this dialog as soon as + possible to prevent excessive system load. + </para> + </warning> + <note><title>Note!</title> + <para> + This dialog box will only show the local interfaces Ethereal knows + of. As Ethereal might not be able to detect all local interfaces, and it + cannot detect the remote interfaces available, there could be more capture + interfaces available than listed. + </para> + </note> + <figure id="ChCapCaptureInterfacesDialog"> + <title>The "Capture Interfaces" dialog box</title> + <graphic entityref="EtherealCaptureInterfacesDialog" format="PNG"/> + </figure> + <variablelist> + <varlistentry><term><command>Description</command></term> + <listitem> + <para> + The interface description provided by the operating system. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>IP</command></term> + <listitem> + <para> + The first IP address Ethereal could resolve from this interface. + If no address could be resolved (e.g. no DHCP server available), + "unknown" will be displayed. If more than one IP address could be + resolved, only the first is shown (unpredictable which one in that + case). + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Packets</command></term> + <listitem> + <para> + The number of packets captured from this interface, since this + dialog was opened. Will be greyed out, if no packet was captured + in the last second. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Packets/s</command></term> + <listitem> + <para> + Number of packets captured in the last second. Will be greyed out, + if no packet was captured in the last second. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Stop</command></term> + <listitem> + <para> + Stop a currently running capture. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Capture</command></term> + <listitem> + <para> + Start a capture on this interface immediately, using the settings + from the last capture. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Prepare</command></term> + <listitem> + <para> + Open the Capture Options dialog with this interface selected, see + <xref linkend="ChCapCaptureOptions"/>. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Close</command></term> + <listitem> + <para> + Close this dialog box. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </section> + + <section id="ChCapCaptureOptions"> + <title>The "Capture Options" dialog box</title> + <para> + When you select Start... from the Capture menu (or use the corresponding + item in the "Main" toolbar), Ethereal pops + up the "Capture Options" dialog box as shown in + <xref linkend="ChCapCaptureOptionsDialog"/>. + </para> + <figure id="ChCapCaptureOptionsDialog"> + <title>The "Capture Options" dialog box</title> + <graphic entityref="EtherealCaptureOptionsDialog" format="JPG"/> + </figure> + <tip><title>Tip!</title> + <para> + If you are unsure which options to choose in this dialog box, just try + keeping the defaults as this should work well in many cases. + </para> + </tip> + <para> + You can set the following fields in this dialog box: + </para> + <section><title>Capture frame</title> + <variablelist> + <varlistentry><term><command>Interface</command></term> + <listitem> + <para> + This field specifies the interface you want to capture on. + You can only capture on one interface, and you can only + capture on interfaces that Ethereal has found on the + system. It is a drop-down list, so simply click on the + button on the right hand side and select the interface you + want. It defaults to the first non-loopback interface that + supports capturing, and if there are none, the first + loopback interface. On some systems, loopback interfaces + cannot be used for capturing (loopback interfaces are not available + on Windows platforms). + </para> + <para> + This field performs the same function as the + <command>-i <interface></command> command line option. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>IP address</command></term> + <listitem> + <para> + The IP address(es) of the selected interface. If no address could + be resolved from the system, "unknown" will be shown. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Link-layer header type</command></term> + <listitem> + <para> + Unless you are in the rare situation that you need this, just keep + the default. For a detailed description, see + <xref linkend="ChCapLinkLayerHeader"/> + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Buffer size: n megabyte(s)</command></term> + <listitem> + <para> + Enter the buffer size to be used while capturing. This is the size + of the kernel buffer which will keep the captured packets, until + they are written to disk. If you encounter packet drops, try + increasing this value. + </para> + <note> + <title>Note</title> + <para>This option is only available on Windows platforms.</para> + </note> + </listitem> + </varlistentry> + <varlistentry> + <term> + <command>Capture packets in promiscuous mode</command> + </term> + <listitem> + <para> + This checkbox allows you to specify that Ethereal + should put the interface in promiscuous mode when capturing. + If you do not specify this, Ethereal will only capture the + packets going to or from your computer (not + all packets on your LAN segment). + </para> + <note> + <title>Note</title> + <para> + If some other process has put the interface in + promiscuous mode you may be capturing in promiscuous + mode even if you turn off this option + </para> + </note> + <note> + <title>Note</title> + <para> + Even in promiscuous mode you still won't necessarily see all packets + on your LAN segment, see <ulink url="&EtherealFAQPromiscPage;"/> for + some more explanations. + </para> + </note> + </listitem> + </varlistentry> + <varlistentry><term><command>Limit each packet to n bytes</command></term> + <listitem> + <para> + This field allows you to specify the maximum amount of + data that will be captured for each packet, and is + sometimes referred to as the <command>snaplen</command>. If disabled, + the default is 65535, which will be sufficient for most + protocols. Some rules of thumb: + </para> + <itemizedlist> + <listitem> + <para> + If you are unsure, just keep the default value. + </para> + </listitem> + <listitem> + <para> + If you don't need all of the data in a packet - for example, if you + only need the link-layer, IP, and TCP headers - you might want to + choose a small snapshot length, as less CPU time is required for + copying packets, less buffer space is required for packets, and thus + perhaps fewer packets will be dropped if traffic is very heavy. + </para> + </listitem> + <listitem> + <para> + If you don't capture all of the data in a packet, you might find that + the packet data you want is in the part that's dropped, or that + reassembly isn't possible as the data required for reassembly is + missing. + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry><term><command>Capture Filter</command></term> + <listitem> + <para> + This field allows you to specify a capture filter. + Capture filters are discussed in more details in + <xref linkend="ChCapCaptureFilterSection"/>. It defaults to empty, or + no filter. + </para> + <para> + You can also click on the button labelled Capture Filter, and Ethereal + will bring up the Capture Filters dialog box and allow you to create + and/or select a filter. Please see + <xref linkend="ChWorkDefineFilterSection"/> + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section><title>Capture File(s) frame</title> + <para> + An explanation about capture file usage can be found in <xref + linkend="ChCapCaptureFiles"/>. + </para> + <variablelist> + <varlistentry><term><command>File</command></term> + <listitem> + <para> + This field allows you to specify the file name that will be + used for the capture file. This field is left blank by default. + If the field is left blank, the capture data will be stored in a + temporary file, see <xref linkend="ChCapCaptureFiles"/> for + details. + </para> + <para> + You can also click on the button to the right of this field to + browse through the filesystem. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Use multiple files</command></term> + <listitem> + <para> + Instead of using a single file, Ethereal will automatically switch + to a new one, if a specific trigger condition is reached. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Next file every n megabyte(s)</command></term> + <listitem> + <para> + Multiple files only: Switch to the next file after the given + number of byte(s)/kilobyte(s)/megabyte(s)/gigabyte(s) have been + captured. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Next file every n minute(s)</command></term> + <listitem> + <para> + Multiple files only: Switch to the next file after the given + number of second(s)/minutes(s)/hours(s)/days(s) have elapsed. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Ring buffer with n files</command></term> + <listitem> + <para> + Multiple files only: Form a ring buffer of the capture files, with + the given number of files. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Stop capture after n file(s)</command></term> + <listitem> + <para> + Multiple files only: Stop capturing after switching to the next + file the given number of times. + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section><title>Stop Capture... frame</title> + <variablelist> + <varlistentry><term><command>... after n packet(s)</command></term> + <listitem> + <para> + Stop capturing after the given number of packets have been + captured. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>... after n megabytes(s)</command></term> + <listitem> + <para> + Stop capturing after the given number of + byte(s)/kilobyte(s)/megabyte(s)/gigabyte(s) have been captured. + This option is greyed out, if "Use multiple files" is selected. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>... after n minute(s)</command></term> + <listitem> + <para> + Stop capturing after the given number of + second(s)/minutes(s)/hours(s)/days(s) have elapsed. + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section><title>Display Options frame</title> + <variablelist> + <varlistentry> + <term> + <command>Update list of packets in real time</command> + </term> + <listitem> + <para> + This option allows you to specify that Ethereal + should update the packet list pane in real time. If you + do not specify this, Ethereal does not display any + packets until you stop the capture. When you check this, + Ethereal captures in a separate process + and feeds the captures to the display process. + </para> + <note> + <title>Note</title> + <para> + If this option is checked, it will disable the "Use multiple files" + option. + </para> + </note> + </listitem> + </varlistentry> + <varlistentry> + <term> + <command>Automatic scrolling in live capture</command> + </term> + <listitem> + <para> + This option allows you to specify that Ethereal + should scroll the packet list pane as new packets come + in, so you are always looking at the last packet. If you + do not specify this, Ethereal simply adds new packets onto + the end of the list, but does not scroll the packet list + pane. This option is greyed out if + "Update list of packets in real time" is disabled. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <command>Hide capture info dialog</command> + </term> + <listitem> + <para> + If this option is checked, the following capture info dialog will be + hidden. This option is greyed out, if "Update list of packets in real + time" is disabled. + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section><title>Name Resolution frame</title> + <variablelist> + <varlistentry> + <term><command>Enable MAC name resolution</command></term> + <listitem> + <para> + This option allows you to control whether or not + Ethereal translates MAC addresses into names, see + <xref linkend="ChAdvNameResolutionSection"/>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><command>Enable network name resolution</command></term> + <listitem> + <para> + This option allows you to control whether or not + Ethereal translates network addresses into names, see + <xref linkend="ChAdvNameResolutionSection"/>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><command>Enable transport name resolution</command></term> + <listitem> + <para> + This option allows you to control whether or not + Ethereal translates transport addresses into protocols, see + <xref linkend="ChAdvNameResolutionSection"/>. + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section><title>Buttons</title> + <para> + Once you have set the values you desire and have selected the + options you need, simply click on <command>OK</command> to commence the + capture, or <command>Cancel</command> to cancel the capture. + </para> + <para> + If you start a capture, Ethereal pops up a dialog box that shows you + the progress of the capture and allows you to stop capturing when + you have enough packets captured, see + <xref linkend="ChCapRunningSection"/>. + </para> + </section> + </section> + + <section id="ChCapCaptureFiles"><title>Capture files and file modes</title> + <para> + While capturing, the underlying libpcap capturing engine will grab the + packets from the network card and keep the packet data in a (relatively) + small kernel buffer. This data is read by Ethereal and saved into + the capture file(s) the user specified. + </para> + + <para> + Different modes of operation are available when saving this packet data to + the capture file(s). + </para> + + <tip><title>Tip!</title> + <para> + Working with large files (several 100 MB's) can be quite slow. If you plan + to do a long term capture or capturing from a high traffic network, think + about using one of the "Multiple files" options. This will spread the + captured packets over several smaller files which can be much more + pleasant to work with. + </para> + </tip> + <note><title>Note!</title> + <para> + Using Multiple files may cut context related information. + Ethereal keeps context information of the loaded packet data, so it can + report context related problems (like a stream error) and keeps information + about context related protocols (e.g. where data is exchanged at the + establishing phase and only referred to in later packets). + As it keeps this information only for the loaded file, using one of + the multiple file modes may cut these contexts, If the establishing phase + is saved in one file and the things you would like to see is in another, + you might not see some of the valuable context related information. + </para> + </note> + <tip><title>Tip!</title> + <para> + Information about the folders used for the capture file(s), can be found + in <xref linkend="AppFiles"/>. + </para> + </tip> + + <table id="ChCapTabCaptureFiles"><title>Capture file mode selected by capture options</title> + <tgroup cols="4"> + <colspec colnum="1" colwidth="72pt"/> + <colspec colnum="2" colwidth="80pt"/> + <colspec colnum="3" colwidth="80pt"/> + <thead> + <row> + <entry>Mode</entry> + <entry>"File" option</entry> + <entry>"Use multiple files" option</entry> + <entry>"Ring buffer with n files" option</entry> + <entry>Resulting filename(s) used</entry> + </row> + </thead> + <tbody> + <row> + <entry><command>Single temporary file</command></entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>etherXXXXXX (where XXXXXX is a unique number)</entry> + </row> + <row> + <entry><command>Single named file</command></entry> + <entry>foo.cap</entry> + <entry>-</entry> + <entry>-</entry> + <entry>foo.cap</entry> + </row> + <row> + <entry><command>Multiple files, continuous</command></entry> + <entry>foo.cap</entry> + <entry>x</entry> + <entry>-</entry> + <entry>foo_00001_20040205110102.cap, foo_00002_20040205110102.cap, ...</entry> + </row> + <row> + <entry><command>Multiple files, ring buffer</command></entry> + <entry>foo.cap</entry> + <entry>x</entry> + <entry>x</entry> + <entry>foo_00001_20040205110102.cap, foo_00002_20040205110102.cap, ...</entry> + </row> + </tbody> + </tgroup> + </table> + <variablelist> + <varlistentry> + <term><command>Single temporary file</command></term> + <listitem> + <para> + A temporary file will be created and used (this is the default). After the + capturing is stopped, this file can be saved later under a user specified + name. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><command>Single named file</command></term> + <listitem> + <para> + A single capture file will be used. If you want to place the new capture + file to a specific folder, choose this mode. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><command>Multiple files, continuous</command></term> + <listitem> + <para> + Like the "Single named file" mode, but a new file is created and used, + after reaching one of the multiple file switch conditions (one of the + "Next file every ..." values). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><command>Multiple files, ring buffer</command></term> + <listitem> + <para> + Much like "Multiple files continuous", reaching one of the multiple files + switch conditions (one of the "Next file every ..." values) will switch + to the next file. This will be a newly created file if value of "Ring + buffer with n files" is not reached, otherwise it will replace the oldest + of the formerly used files (thus forming a "ring"). + </para> + <para> + This mode will limit the maximum disk usage, even for an unlimited amount of + capture input data, keeping the latest captured data. + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + + <section id="ChCapLinkLayerHeader"><title>Link-layer header type</title> + <para> + In the usual case, you won't have to choose this link-layer header type. + The following paragraphs describe the exceptional cases, where + selecting this type is possible, so you will have a guide what to do: + </para> + <para> + If you are capturing on an 802.11 device on some versions of BSD, this + might offer a choice of "Ethernet" or "802.11". "Ethernet" will cause + the captured packets to have fake Ethernet headers; "802.11" will cause + them to have IEEE 802.11 headers. Unless the capture needs to be read by + an application that doesn't support 802.11 headers, you should select + "802.11". + </para> + <para> + If you are capturing on an Endace DAG card connected to a synchronous + serial line, this might offer a choice of "PPP over serial" or + "Cisco HDLC"; if the protocol on the serial line is PPP, select + "PPP over serial", and if the protocol on the serial line is Cisco HDLC, + select "Cisco HDLC". + </para> + <para> + If you are capturing on an Endace DAG card connected to an ATM network, + this might offer a choice of "RFC 1483 IP-over-ATM" or "Sun raw ATM". + If the only traffic being captured is RFC 1483 LLC-encapsulated IP, or if + the capture needs to be read by an application that doesn't support SunATM + headers, select "RFC 1483 IP-over-ATM", otherwise select "Sun raw ATM". + </para> + <para> + If you are capturing on an Ethernet device, this might offer a choice of + "Ethernet" or "DOCSIS". If you are capturing traffic from a Cisco Cable + Modem Termination System that is putting DOCSIS traffic onto the Ethernet + to be captured, select "DOCSIS", otherwise select "Ethernet". + </para> + </section> + + <section id="ChCapCaptureFilterSection"><title>Filtering while capturing</title> + <para> + Ethereal uses the libpcap filter language for capture filters. + This is explained in the tcpdump man page, which can be hard to + understand, so it's explained here to some extent. + </para> + <para> + You enter the capture filter into the Filter field of the Ethereal + Capture Options dialog box, as shown in + <xref linkend="ChCapCaptureOptionsDialog"/>. The following is an outline + of the syntax of the <command>tcpdump</command> capture filter language. + See the expression option at the tcpdump manual page for details: + <ulink url="http://www.tcpdump.org/tcpdump_man.html"/> + </para> + <para> + A capture filter takes the form of a series of primitive expressions + connected by conjuctions (<command>and/or</command>) and optionally + preceded by <command>not</command>: + <programlisting> +[not] <command>primitive</command> [and|or [not] <command>primitive</command> ...] + </programlisting> + An example is shown in <xref linkend="ChCapExFilt1"/>. + + <example id="ChCapExFilt1"> + <title> + A capture filter for telnet than captures traffic to and from a + particular host + </title> + <programlisting> +tcp port 23 and host 10.0.0.5 + </programlisting> + </example> + This example captures telnet traffic to and from the host + 10.0.0.5, and shows how to use two primitives and the + <command>and</command> conjunction. Another example is shown in + <xref linkend="ChCapExFilt2"/>, and shows how to capture all + telnet traffic except that from 10.0.0.5. + <example id="ChCapExFilt2"> + <title> + Capturing all telnet traffic not from 10.0.0.5</title> + <programlisting> +tcp port 23 and not host 10.0.0.5 + </programlisting> + </example> + </para> + + <para> + XXX - add examples to the following list. + </para> + <para> + A primitive is simply one of the following: + <variablelist> + <varlistentry> + <term><command>[src|dst] host <host></command></term> + <listitem> + <para> + This primitive allows you to filter on a host IP + address or name. You can optionally precede the + primitive with the keyword <command>src|dst</command> + to specify that you are only interested in source or + destination addresses. If these are not present, + packets where the specified address appears as either + the source or the destination address will be selected. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <command>ether [src|dst] host <ehost></command> + </term> + <listitem> + <para> + This primitive allows you to filter on Ethernet host + addresses. You can optionally include the keyword + <command>src|dst</command> between the keywords + <command>ether</command> and <command>host</command> + to specify that you are only interested in source + or destination addresses. If these are not present, + packets where the specified address appears in either + the source or destination address will be selected. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><command>gateway host <host></command></term> + <listitem> + <para> + This primitive allows you to filter on packets that + used <command>host</command> as a gateway. That is, where + the Ethernet source or destination was + <command>host</command> but neither the source nor + destination IP address was <command>host</command>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <command> + [src|dst] net <net> [{mask <mask>}|{len <len>}] + </command> + </term> + <listitem> + <para> + This primitive allows you to filter on network numbers. + You can optionally precede this primitive with the + keyword <command>src|dst</command> to specify that you + are only interested in a source or destination network. + If neither of these are present, packets will be + selected that have the specified network in either the + source or destination address. In addition, you can + specify either the netmask or the CIDR prefix for the + network if they are different from your own. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <command>[tcp|udp] [src|dst] port <port></command> + </term> + <listitem> + <para> + This primitive allows you to filter on TCP and UDP port + numbers. You can optionally precede this primitive with + the keywords <command>src|dst</command> and + <command>tcp|udp</command> which allow you to specify + that you are only interested in source or destination + ports and TCP or UDP packets respectively. The + keywords <command>tcp|udp</command> must appear before + <command>src|dst</command>. + </para> + <para> + If these are not specified, packets will be selected + for both the TCP and UDP protocols and when the + specified address appears in either the source or + destination port field. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><command>less|greater <length></command></term> + <listitem> + <para> + This primitive allows you to filter on packets whose + length was less than or equal to the specified length, + or greater than or equal to the specified length, + respectively. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><command>ip|ether proto <protocol></command></term> + <listitem> + <para> + This primitive allows you to filter on the specified + protocol at either the Ethernet layer or the IP layer. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><command>ether|ip broadcast|multicast</command></term> + <listitem> + <para> + This primitive allows you to filter on either + Ethernet or IP broadcasts or multicasts. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><command><expr> relop <expr></command></term> + <listitem> + <para> + This primitive allows you to create complex filter + expressions that select bytes or ranges of bytes in + packets. Please see the tcpdump man pages for more + details. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </section> + + <section id="ChCapRunningSection"><title>While a Capture is running ...</title> + <para> + While a capture is running, the following dialog box is shown: + <figure id="ChCapCaptureInfoDialog"> + <title>The "Capture Info" dialog box</title> + <graphic entityref="EtherealCaptureInfoDialog" format="JPG"/> + </figure> + This dialog box will inform you about the number of captured packets and + the time since the capture was started. The selection which protocols + are counted cannot be changed. + </para> + <tip><title>Tip!</title> + <para> + This Capture Info dialog box can be hidden, using the "Hide capture info + dialog" option in the Capture Options dialog box. + </para> + </tip> + <section id="ChCapStopSection"><title>Stop the running capture</title> + <para> + A running capture session will be stopped in one of the following ways: + <orderedlist> + <listitem> + <para>Using the Stop button from the <command>Capture Info dialog box + </command>. + </para> + <note><title>Note!</title> + <para> + The Capture Info dialog box might be hidden, if the option "Hide capture + info dialog" is used. + </para> + </note> + </listitem> + <listitem> + <para>Using the <command>menu item</command> "Capture/Stop Capture" or + the corresponding Stop Capture <command>toolbar icon</command> + <inlinegraphic entityref="EtherealToolbarStop" format="PNG"/>. + </para> + <note><title>Note!</title> + <para> + These are only available, if the option "Update list of packets in real + time" is used. + </para> + </note> + </listitem> + <listitem> + <para>Pressing the accelerator keys: <command>Ctrl+E</command>. + </para> + </listitem> + <listitem> + <para>The capture will be automatically stopped, if one of the + <command>Stop Conditions</command> is exceeded, e.g. the maximum amount + of data was captured. + </para> + </listitem> + </orderedlist> + </para> + </section> + </section> + +</chapter> +<!-- End of EUG Chapter Capture --> + diff --git a/docbook/eug_src/EUG_chapter_customize.xml b/docbook/eug_src/EUG_chapter_customize.xml new file mode 100644 index 0000000000..9ab976b1f2 --- /dev/null +++ b/docbook/eug_src/EUG_chapter_customize.xml @@ -0,0 +1,824 @@ +<!-- EUG Chapter Customizing --> +<!-- $Id$ --> + +<chapter id="ChapterCustomize"> + <title>Customizing Ethereal</title> + + <section id="ChCustIntroduction"><title>Introduction</title> + <para> + Ethereal's default behaviour will usually suit your needs pretty well. + However, as you become more familiar with Ethereal, it can be customized + in various ways to suit your needs even better. In this chapter we explore: + <itemizedlist> + <listitem> + <para> + How to start Ethereal with command line parameters + </para> + </listitem> + <listitem> + <para> + How to colorize the <application>Ethereal</application> display + </para> + </listitem> + <listitem> + <para> + How to use the various preference settings + </para> + </listitem> + </itemizedlist> + </para> + </section> + + <section id="ChCustCommandLine"><title>Start Ethereal from the command line</title> + <para> + You can start <application>Ethereal</application> from the command + line, but it can also be started from most Window managers + as well. In this section we will look at starting it from the command + line. + </para> + <para> + <application>Ethereal</application> supports a large number of + command line parameters. To see what they are, simply enter the + command <command> ethereal -h</command> and the help information + shown in <xref linkend="ChCustEx1"/> (or something similar) should be + printed. + <example id="ChCustEx1"> + <title>Help information available from Ethereal</title> + <programlisting> +This is GNU ethereal 0.10.5 +Compiled with GTK+ 2.4.3, with GLib 2.4.2, with WinPcap (version unknown), +with libz 1.2.1, with libpcre 4.4, with Net-SNMP 5.1, with ADNS. + +Running with WinPcap version 3.0 (packet.dll version 3, 1, 0, 20), based +on libpcap version 0.8 on Windows XP Service Pack 1, build 2600. + +ethereal [ -vh ] [ -klLnpQS ] [ -a <capture autostop condition> ] ... + [ -b <number of ringbuffer files>[:<duration>] ] + [ -B <byte view height> ] [ -c <count> ] [ -f <capture filter> ] + [ -i <interface> ] [ -m <medium font> ] [ -N <resolving> ] + [ -o <preference setting> ] ... [ -P <packet list height> ] + [ -r <infile> ] [ -R <read filter> ] [ -s <snaplen> ] + [ -t <time stamp format> ] [ -T <tree view height> ] + [ -w <savefile> ] [ -y <link type> ] [ -z <statistics string> ] + [ <infile> ] + </programlisting> + </example> + + We will examine each of the command line options in turn. + </para> + <para> + The first thing to notice is that issuing the command + <command>ethereal</command> by itself will bring up + <application>Ethereal</application>. + However, you can include as many of the command line parameters as + you like. Their meanings are as follows ( in alphabetical order ): + XXX - is the alphabetical order a good choice? Maybe better task based? + <variablelist> + <varlistentry><term><command>-a <capture autostop condition></command></term> + <listitem> + <para> + Specify a criterion that specifies when Ethereal is to stop writing + to a capture file. The criterion is of the form test:value, where test + is one of: + <variablelist> + <varlistentry><term><command>duration</command></term> + <listitem><para> + Stop writing to a capture file after value of seconds have elapsed. + </para></listitem> + </varlistentry> + <varlistentry><term><command>filesize</command></term> + <listitem><para> + Stop writing to a capture file after it reaches a size of value + kilobytes (where a kilobyte is 1000 bytes, not 1024 bytes). + </para></listitem> + </varlistentry> + </variablelist> + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>-b <number of ringbuffer files></command></term> + <listitem> + <para> + If a maximum capture file size was specified, cause Ethereal to run + in "ring buffer" mode, with the specified number of files. In "ring + buffer" mode, Ethereal will write to several capture files. Their + name is based on the number of the file and on the creation date and + time. + </para> + <para> + When the first capture file fills up, Ethereal will switch to writing + to the next file, until it fills up the last file, at which point + it'll discard the data in the first file (unless 0 is specified, in + which case, the number of files is unlimited) and start writing to + that file and so on. + </para> + <para> + If the optional duration is specified, Ethereal will switch also to + the next file when the specified number of seconds has elapsed even + if the current file is not completely fills up. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>-B <byte view height></command></term> + <listitem> + <para> + This option sets the initial height of the "Packet Bytes" pane. + This pane is usually the bottom pane in the Ethereal display. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>-c <count></command></term> + <listitem> + <para> + This option specifies the maximum number of packets to capture + when capturing live data. It would be used in conjunction + with the <command>-k</command> option. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>-f <capture filter></command></term> + <listitem> + <para> + This option sets the initial capture filter expression to + be used when capturing packets. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>-h</command></term> + <listitem> + <para> + The <command>-h</command> option requests Ethereal to print + its version and usage instructions (as shown above) and exit. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>-i <interface></command></term> + <listitem> + <para> + The <command>-i</command> option allows you to specify, + from the command line, which interface packet capture should + occur on if capturing packets. + </para> + <para> + An example would be: <command>ethereal -i eth0</command>. + </para> + <para> + To get a listing of all the interfaces you can capture on, + use the command <command>ifconfig -a</command> or + <command>netstat -i</command>. Unfortunately, some versions of + UNIX do not support <command>ifconfig -a</command>, so you + will have to use <command>netstat -i</command> in these cases. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>-k</command></term> + <listitem> + <para> + The <command>-k</command> option specifies that Ethereal + should start capturing packets immediately. This option + requires the use of the <command>-i</command> parameter to + specify the interface that packet capture will occur from. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>-l</command></term> + <listitem> + <para> + This option turns on automatic scrolling if the packet + list pane is being updated automatically as packets arrive + during a capture ( as specified by the <command>-S</command> + flag). + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>-L</command></term> + <listitem> + <para> + List the data link types supported by the interface and exit. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>-m <medium font></command></term> + <listitem> + <para> + This option sets the name of the font used for most text + displayed by Ethereal. XXX - add an example! + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>-n</command></term> + <listitem> + <para> + Disable network object name resolution (such as hostname, TCP and UDP + port names). + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>-N <resolving></command></term> + <listitem> + <para> + Turns on name resolving for particular types of addresses + and port numbers; the argument is a string that may contain + the letters <command>m</command> to enable MAC address + resolution, <command>n</command> to enable network address + resolution, and <command>t</command> to enable transport-layer + port number resolution. This overrides <command>-n</command> + if both <command>-N</command> and <command>-n</command> are + present. The letter C enables concurrent (asynchronous) DNS lookups. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><command>-o <preference settings></command></term> + <listitem> + <para> + Sets a preference value, overriding the default value and + any value read from a preference file. The argument to the + flag is a string of the form prefname:value, where prefname + is the name of the preference (which is the same name that + would appear in the preference file), and value is the value + to which it should be set. Multiple instances of + <command>-o <preference settings> </command> can be + given on a single command line. + </para> + <para>An example of setting a single preference would be: </para> + <para> + <command> + ethereal -o mgcp.display_dissect_tree:TRUE + </command> + </para> + <para> + An example of setting multiple preferences would be: + </para> + <para> + <command> + ethereal -o mgcp.display_dissect_tree:TRUE -o mgcp.udp.callagent_port:2627 + </command> + </para> + <tip><title>Tip!</title> + <para> + You can get a list of all available preference strings from the + preferences file, see <xref linkend="AppFiles"/>. + </para> + </tip> + </listitem> + </varlistentry> + <varlistentry><term><command>-p</command></term> + <listitem> + <para> + Don't put the interface into promiscuous mode. Note that + the interface might be in promiscuous mode for some other + reason; hence, -p cannot be used to ensure that the only + traffic that is captured is traffic sent to or from the + machine on which Ethereal is running, broadcast traffic, and + multicast traffic to addresses received by that machine. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><command>-P <packet list height></command></term> + <listitem> + <para> + This option sets the initial height of the "Packet List" pane, + ie, the top pane. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>-Q</command></term> + <listitem> + <para> + This option forces Ethereal to exit when capturing is + complete. It can be used with the <command>-c</command> option. + It must be used in conjunction with the + <command>-i</command> and <command>-w</command> options. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>-r <infile></command></term> + <listitem> + <para> + This option provides the name of a capture file for Ethereal + to read and display. This capture file can be in one of the + formats Ethereal understands. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>-R <read filter></command></term> + <listitem> + <para> + This option specifies a display filter to be applied when + reading packets from a capture file. The syntax of this + filter is that of the display filters discussed in + <xref linkend="ChWorkDisplayFilterSection"/>. Packets not + matching the filter are discarded. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>-s <snaplen></command></term> + <listitem> + <para> + This option specifies the snapshot length to use when + capturing packets. Ethereal will only capture + <command><snaplen></command> bytes of data for each packet. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>-S</command></term> + <listitem> + <para> + This option specifies that Ethereal will display packets as + it captures them. This is done by capturing in one process + and displaying them in a separate process. This is the same + as "Update list of packets in real time" in the Capture Options + dialog box. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><command>-t <time stamp format></command></term> + <listitem> + <para> + This option sets the format of packet timestamps that are + displayed in the packet list window. The format can be one of: + <itemizedlist> + <listitem> + <para> + <command>r</command> relative, which specifies timestamps are + displayed relative to the first packet captured. + </para> + </listitem> + <listitem> + <para> + <command>a</command> absolute, which specifies that actual times + be displayed for all packets. + </para> + </listitem> + <listitem> + <para> + <command>ad</command> absolute with date, which specifies that + actual dates and times be displayed for all packets. + </para> + </listitem> + <listitem> + <para> + <command>d</command> delta, which specifies that timestamps + are relative to the previous packet. + </para> + </listitem> + </itemizedlist> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><command>-T <tree view height></command></term> + <listitem> + <para> + This option sets the initial height of the "Packet Details" pane. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>-v</command></term> + <listitem> + <para> + The <command>-v</command> option requests + Ethereal to print out its version information and exit. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>-w <savefile></command></term> + <listitem> + <para> + This option sets the name of the <command>savefile</command> + to be used when saving a capture file. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>-y <link type></command></term> + <listitem> + <para> + If a capture is started from the command line with -k, set the data + link type to use while capturing packets. The values reported by -L + are the values that can be used. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>-z <statistics-string></command></term> + <listitem> + <para> + Get Ethereal to collect various types of statistics and display the + result in a window that updates in semi-real time. + XXX - add more details here! + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </section> + + <section id="ChCustColorizationSection"><title>Packet colorization</title> + <para> + A very useful mechanism available in Ethereal is packet colorization. + You can set Ethereal up so that it colorizes packets according to a + filter. This allows you to emphasize the packets you are interested in. + </para> + <para> + To colorize packets, select the Coloring Rules... menu item from + the View menu, and Ethereal will pop up the "Coloring Rules" + dialog box as shown in <xref linkend="ChCustColoringRulesDialog"/>. + </para> + <figure id="ChCustColoringRulesDialog"> + <title>The "Coloring Rules" dialog box</title> + <graphic entityref="EtherealColoringRulesDialog" format="PNG"/> + </figure> + <para> + Once the Coloring Rules dialog box is up, there are a number + of buttons you can use, depending on whether or not you have any + color filters installed already. + </para> + <note><title>Note!</title> + <para> + You will need to carefully select the order that rules are listed + (and thus applied) as they are applied in order from top to bottom. + So, more specific rules need to be listed before more general rules. + For example, if you have a color rule for UDP before the one for DNS, + the color rule for DNS will never be applied (as DNS uses UDP, so the + UDP rule will be matching first). + </para> + </note> + <para> + If this is the first time you have used Coloring Rules, click on the New + button which will bring up the Edit color filter dialog box as shown in + <xref linkend="ChCustEditColorDialog"/>. + </para> + <figure id="ChCustEditColorDialog"> + <title>The "Edit Color Filter" dialog box</title> + <graphic entityref="EtherealEditColorDialog" format="PNG"/> + </figure> + <para> + In the Edit Color dialog box, simply enter a name for the color filter, + and enter a filter string in the Filter text field. + <xref linkend="ChCustEditColorDialog"/> shows the values + <command>arp</command> and <command>arp</command> which means that + the name of the color filter is <command>arp</command> and the filter + will select protocols of type <command>arp</command>. Once you have + entered these values, you can choose a foreground and background + color for packets that match the filter expression. Click on + <command>Foreground color...</command> or + <command>Background color...</command> to achieve this and + Ethereal will pop up the Choose foreground/background color for + protocol dialog box as shown in + <xref linkend="ChCustChooseColorDialog"/>. + </para> + <figure id="ChCustChooseColorDialog"> + <title>The "Choose color" dialog box</title> + <graphic entityref="EtherealChooseColorDialog" format="PNG"/> + </figure> + <para> + Select the color you desire for the selected packets and click on OK. + </para> + <note> + <title>Note!</title> + <para> + You must select a color in the colorbar next to the colorwheel to + load values into the RGB values. Alternatively, you can set the + values to select the color you want. + </para> + </note> + <para> + <xref linkend="ChCustColorFilterMany"/> shows an example of several color + filters being used in Ethereal. You may not like the color choices, + however, feel free to choose your own. + </para> + <figure id="ChCustColorFilterMany"> + <title>Using color filters with Ethereal</title> + <graphic entityref="EtherealThreePane1" format="PNG"/> + </figure> + </section> + + <section id="ChCustProtocolDissectionSection"> + <title>Control Protocol dissection</title> + <para> + There are some ways, to let the user control how protocols are + dissected. + </para> + <para> + Each protocol has its own dissector, so dissecting a packet will + typically involve several dissectors. As Ethereal tries to find the + right dissector for each packet (using static "routes" and heuristics + "guessing"), it might choose the wrong dissector in your specific + case. For example, Ethereal won't know if you use a common protocol + on an uncommon TCP port, e.g. using HTTP on TCP port 800 instead of + the standard port 80. + </para> + <para> + There are two ways to control the relations between protocol + dissectors: disable a protocol dissector completely or temporarily + divert the way Ethereal calls the dissectors. + </para> + <section id="ChAdvEnabledProtocols"><title>The "Enabled Protocols" dialog + box</title> + <para> + The Enabled Protocols dialog box lets you enable or + disable specific protocols, all protocols are enabled by default. + When a protocol is disabled, Ethereal stops processing a packet + whenever that protocol is encountered. + </para> + <note><title>Note!</title> + <para> + Disabling a protocol will prevent information about higher-layer + protocols from being displayed. For example, + suppose you disabled the IP protocol and selected + a packet containing Ethernet, IP, TCP, and HTTP + information. The Ethernet information would be + displayed, but the IP, TCP and HTTP information + would not - disabling IP would prevent it and + the other protocols from being displayed. + </para> + </note> + <figure id="ChAdvEnabledProtocolsFig"> + <title>The "Enabled Protocols" dialog box</title> + <graphic entityref="EtherealEnabledProtocols" format="PNG"/> + </figure> + <para> + To disable or enable a protocol, simply click on it using the + mouse or press the space bar when the protocol is highlighted. + </para> + <warning><title>Warning!</title> + <para> + You have to use the Save button to save your settings. The OK or Apply + buttons will not save your changes, so they will be lost when Ethereal + is closed. + </para> + </warning> + <para> + You can choose from the following actions: + <orderedlist> + <listitem> + <para> + <command>Enable All</command> Enable all protocols in the list. + </para> + </listitem> + <listitem> + <para> + <command>Disable All</command> Disable all protocols in the list. + </para> + </listitem> + <listitem> + <para> + <command>Invert</command> Toggle the state of all protocols in the + list. + </para> + </listitem> + <listitem> + <para> + <command>OK</command> Apply the changes and close the dialog box. + </para> + </listitem> + <listitem> + <para> + <command>Apply</command> Apply the changes and keep the dialog box + open. + </para> + </listitem> + <listitem> + <para> + <command>Save</command> Save the settings to the disabled_protos, see + <xref linkend="AppFiles"/> for details. + </para> + </listitem> + <listitem> + <para> + <command>Cancel</command> Cancel the changes and close the dialog box. + </para> + </listitem> + </orderedlist> + </para> + </section> + + <section id="ChAdvDecodeAs"><title>User Specified Decodes</title> + <para> + The "Decode As" functionality let you temporarily divert specific + protocol dissections. This might be useful for example, if you do some + uncommon things on your network. + </para> + <para> + <figure id="ChAdvDecodeAsFig"> + <title>The "Decode As" dialog box</title> + <graphic scale="100" entityref="EtherealDecodeAs" format="PNG"/> + </figure> + The content of this dialog box depends on the selected packet when it + was opened. + <warning><title>Warning!</title> + <para> + The user specified decodes can not be saved. If you quit Ethereal, + these settings will be lost. + </para> + </warning> + <orderedlist> + <listitem> + <para> + <command>Decode</command> Decode packets the selected way. + </para> + </listitem> + <listitem> + <para> + <command>Do not decode</command> Do not decode packets the selected + way. + </para> + </listitem> + <listitem> + <para> + <command>Link/Network/Transport</command> Specify the way to decode + packets. Which of these pages are available, depends on the content + of the selected packet when this dialog box was opened. + </para> + </listitem> + <listitem> + <para> + <command>Show Current</command> Open a dialog box showing the + current list of user specified decodes. + </para> + </listitem> + <listitem> + <para> + <command>OK</command> Apply the currently selected decode and close + the dialog box. + </para> + </listitem> + <listitem> + <para> + <command>Apply</command> Apply the currently selected decode and keep + the dialog box open. + </para> + </listitem> + <listitem> + <para> + <command>Cancel</command> Cancel the changes and close the dialog box. + </para> + </listitem> + </orderedlist> + </para> + </section> + + <section id="ChAdvDecodeAsShow"><title>Show User Specified Decodes</title> + <para> + This dialog box shows the currently active user specified decodes. + <figure id="ChAdvDecodeAsShowFig"> + <title>The "Decode As: Show" dialog box</title> + <graphic entityref="EtherealDecodeAsShow" format="PNG"/> + </figure> + <orderedlist> + <listitem> + <para> + <command>OK</command> Close this dialog box. + </para> + </listitem> + <listitem> + <para> + <command>Clear</command> Removes all user specified decodes. + </para> + </listitem> + </orderedlist> + </para> + </section> + </section> + + <section id="ChCustPreferencesSection"><title>Preferences</title> + <para> + There are a number of preferences you can set. Simply + select the Preferences... menu item from the Edit menu, and Ethereal + will pop up the Preferences dialog box as shown in + <xref linkend="ChCustGUIPrefPage"/>, with the "User Interface" page as + default. On the left side is a tree where you can select the page to be + shown. XXX - add detailed descriptions of all the preferences pages. + <warning> + <title>Warning!</title> + <para> + The OK or Apply button will not save the preference settings, + you'll have to save the settings by clicking the Save button. + </para> + </warning> + <itemizedlist> + <listitem> + <para> + The <command>OK</command> button will apply the preferences + settings and close the dialog. + </para> + </listitem> + <listitem> + <para> + The <command>Apply</command> button will apply the preferences + settings and keep the dialog open. + </para> + </listitem> + <listitem> + <para> + The <command>Save</command> button will apply the preferences + settings, save the settings on the harddisk and keep the dialog open. + </para> + </listitem> + <listitem> + <para> + The <command>Cancel</command> button will restore all preferences + settings to the last saved state. + </para> + </listitem> + </itemizedlist> + </para> + <section><title>The "User Interface" page</title> + <figure id="ChCustGUIPrefPage"> + <title>The "User Interface" preferences page</title> + <graphic entityref="EtherealGUIPreferences" format="PNG"/> + </figure> + <para> + This page allows you to configure various characteristics + of the GUI. + </para> + </section> + <section><title>The "User Interface: Layout" page</title> + <figure id="ChCustGUILayoutPrefPage"> + <title>The "User Interface: Layout" preferences page</title> + <graphic entityref="EtherealGUILayoutPreferences" format="PNG"/> + </figure> + <para> + This page selects the GUI layout of the main window. + </para> + </section> + <section><title>The "User Interface: Columns" page</title> + <para> + <figure id="ChCustGUIColumnsPrefPage"> + <title>The "User Interface: Columns" preferences page</title> + <graphic entityref="EtherealGUIColumnsPreferences" format="PNG"/> + </figure> + This page allows you to select which columns appear in the + "Packet List" Pane. + </para> + <note><title>Note!</title> + <para> + Unlike all other preference changes, you will have to save the + preferences and restart Ethereal in order for column changes to + take effect! + </para> + </note> + </section> + + <section><title>The "User Interface: Font" page</title> + <para> + <figure id="ChCustGUIFontPrefPage"> + <title>The "User Interface: Font" preferences page</title> + <graphic entityref="EtherealGUIFontPreferences" format="PNG"/> + </figure> + This page allows you to select which font to use. + </para> + </section> + + <section><title>The "User Interface: Colors" page</title> + <para> + <figure id="ChCustGUIColrsPrefPage"> + <title>The "User Interface: Colors" preferences page</title> + <graphic entityref="EtherealGUIColorsPreferences" format="PNG"/> + </figure> + This page allows you to select which colors to use. + </para> + </section> + + <section><title>The "Capture" page</title> + <para> + <figure id="ChCustCapturePrefPage"> + <title>The "Capture" preferences page</title> + <graphic entityref="EtherealCapturePreferences" format="PNG"/> + </figure> + This page allows you to select some defaults for the capture options dialog. + </para> + </section> + + <section><title>The "Printing" page</title> + <para> + <figure id="ChCustPrintingPrefPage"> + <title>The "Printing" preferences page</title> + <graphic entityref="EtherealPrintingPreferences" format="PNG"/> + </figure> + This page allows you to select some defaults for the print dialog. + </para> + </section> + + <section><title>The "Name Resolution" page</title> + <para> + <figure id="ChCustNameResolutionPrefPage"> + <title>The "Name Resolution" preferences page</title> + <graphic entityref="EtherealNameResolutionPreferences" format="PNG"/> + </figure> + This page allows you to select some defaults for the name resolution. + </para> + </section> + + <section id="ChCustProtocolsPrefPages"><title>The "Protocols" pages</title> + <para> + These pages allows you to select settings for various protocols. + </para> + </section> + </section> + +</chapter> +<!-- End of EUG Chapter Customizing --> + diff --git a/docbook/eug_src/EUG_chapter_introduction.xml b/docbook/eug_src/EUG_chapter_introduction.xml new file mode 100644 index 0000000000..bb2e279e1d --- /dev/null +++ b/docbook/eug_src/EUG_chapter_introduction.xml @@ -0,0 +1,572 @@ +<!-- EUG Chapter Introduction --> +<!-- $Id$ --> + +<chapter id="ChapterIntroduction"> + <title>Introduction</title> + <!-- Introduction --> + <section id="ChIntroWhatIs"> + <title>What is <application>Ethereal?</application></title> + <para> + Ethereal is a network packet analyzer. A network packet + analyzer will try to capture network packets and tries to display + that packet data as detailed as possible. + </para> + <para> + You could think of a network packet analyzer as a measuring device used to + examine what's going on inside a network cable, just like a voltmeter is + used by an electrician to examine what's going on inside an electric cable + (but at a higher level, of course). + </para> + <para> + In the past, such tools were either very expensive, proprietary, or both. + However, with the advent of Ethereal, all that has changed. + </para> + <para> + <application>Ethereal</application> is perhaps one of the best open + source packet analyzers available today. + </para> + + <section id="ChIntroPurposes"><title>Some intended purposes</title> + <para> + Here are some examples people use Ethereal for: + <itemizedlist> + <listitem><para> + network administrators use it to <command>troubleshoot network + problems</command> + </para></listitem> + <listitem><para> + network security engineers use it to <command>examine security + problems</command> + </para></listitem> + <listitem><para> + developers use it to <command>debug protocol implementations</command> + </para></listitem> + <listitem><para> + people use it to <command>learn network protocol</command> + internals + </para></listitem> + </itemizedlist> + Beside these examples, Ethereal can be helpful in many other situations + too. + </para> + </section> + + <section id="ChIntroFeatures"><title>Features</title> + <para> + The following are some of the many features Ethereal provides: + <itemizedlist> + <listitem> + <para>Available for <command>UNIX</command> and <command>Windows</command>.</para> + </listitem> + <listitem> + <para> + <command>Capture</command> live packet data from a network interface. + </para> + </listitem> + <listitem> + <para> + Display packets with <command>very detailed protocol information</command>. + </para> + </listitem> + <listitem> + <para> + <command>Open and Save</command> packet data captured. + </para> + </listitem> + <listitem> + <para> + <command>Import and Export</command> packet data from and to a lot of + other capture programs. + </para> + </listitem> + <listitem> + <para><command>Filter packets</command> on many criteria.</para> + </listitem> + <listitem> + <para><command>Search</command> for packets on many criteria.</para> + </listitem> + <listitem> + <para><command>Colorize</command> packet display based on filters.</para> + </listitem> + <listitem> + <para>Create various <command>statistics</command>.</para> + </listitem> + <listitem> + <para>... and <command>a lot more!</command></para> + </listitem> + </itemizedlist> + However, to really appreciate its power, you have to start using it. + </para> + <para> + <xref linkend="ChIntroFig1"/> shows <application>Ethereal</application> + having captured some packets and waiting for you to examine + them. + <figure id="ChIntroFig1"> + <title> + <application>Ethereal</application> captures packets and allows + you to examine their content. + </title> + <graphic entityref="EtherealMain1" format="PNG"/> + </figure> + </para> + </section> + + <section> + <title>Live capture from many different network media</title> + <para> + Despite its name, Ethereal can capture traffic from + network media other than Ethernet. Which media types are + supported, depends on many things like the operating system you are + using. An overview of the supported media types can be found at: + <ulink url="&EtherealMediaPage;"/>. + </para> + </section> + + <section><title>Import files from many other capture programs</title> + <para> + Ethereal can open packets captured from a large number of + other capture programs. For a list of input formats see + <xref linkend="ChIOInputFormatsSection"/>. + </para> + </section> + <section><title>Export files for many other capture programs</title> + <para> + Ethereal can save packets captured in a large number of formats of + other capture programs. For a list of output formats see + <xref linkend="ChIOOutputFormatsSection"/>. + </para> + </section> + + <section> + <title>Many protocol decoders</title> + <para> + There are protocol decoders (or dissectors, as they are + known in Ethereal) for a great many protocols: + see <xref linkend="AppProtocols"/>. + </para> + </section> + + <section><title>Open Source Software</title> + <para> + Ethereal is an open source software project, and is released under + the <ulink url="&GPLWebsite;">GNU General Public Licence</ulink> (GPL). + You can freely use Ethereal on any number of computers you like, without + worrying about license keys or fees or such. In addition, all source + code is freely available under the GPL. Because of that, it is very easy + for people to add new protocols to Ethereal, either as plugins, or built + into the source, and they often do! + </para> + </section> + + <section id="ChIntroNoFeatures"><title>What Ethereal is not</title> + <para> + Here are some things Ethereal does not provide: + <itemizedlist> + <listitem><para> + Ethereal isn't an intrusion detection system. It will not warn you when + someone does strange things on your network that he/she isn't allowed to + do. However, if strange things happen, Ethereal might help you figure + out what is really going on. + </para></listitem> + <listitem><para> + Ethereal will not manipulate things on the network, it will only + "measure" things from it. Ethereal doesn't send packets on the network + or do other active things (except for name resolutions, but even + that can be disabled). + </para></listitem> + </itemizedlist> + </para> + </section> + </section> + + <section id="ChIntroPlatforms"> + <title>Platforms Ethereal runs on</title> + <para> + Ethereal currently runs on most UNIX platforms and various Windows + platforms. It requires GTK+, GLib, libpcap and some other libraries in + order to run. + </para> + <para> + If a binary package is not available for your platform, you should + download the source and try to build it. Please report your experiences + to <ulink url="mailto:&EtherealDevMailList;">&EtherealDevMailList;</ulink>. + </para> + <para> + Binary packages are available for at least the following platforms: + </para> + + <section><title>Unix</title> + <para> + <itemizedlist> + <listitem><para>Apple Mac OS X</para></listitem> + <listitem><para>BeOS</para></listitem> + <listitem><para>FreeBSD</para></listitem> + <listitem><para>HP-UX</para></listitem> + <listitem><para>IBM AIX</para></listitem> + <listitem><para>NetBSD</para></listitem> + <listitem><para>OpenBSD</para></listitem> + <listitem><para>SCO UnixWare/OpenUnix</para></listitem> + <listitem><para>SGI Irix</para></listitem> + <listitem><para>Sun Solaris/Intel</para></listitem> + <listitem><para>Sun Solaris/Sparc</para></listitem> + <listitem><para>Tru64 UNIX (formerly Digital UNIX)</para></listitem> + </itemizedlist> + </para> + </section> + + <section><title>Linux</title> + <para> + <itemizedlist> + <listitem><para>Debian GNU/Linux</para></listitem> + <listitem><para>Gentoo Linux</para></listitem> + <listitem><para>IBM S/390 Linux (Red Hat)</para></listitem> + <listitem><para>Mandrake Linux</para></listitem> + <listitem><para>PLD Linux</para></listitem> + <listitem><para>Red Hat Linux</para></listitem> + <listitem><para>Rock Linux</para></listitem> + <listitem><para>Slackware Linux</para></listitem> + <listitem><para>Suse Linux</para></listitem> + </itemizedlist> + </para> + </section> + + <section><title>Microsoft Windows</title> + <para> + <itemizedlist> + <listitem><para>Windows Me / 98 / 95</para></listitem> + <listitem><para>Windows Server 2003 / XP / 2000 / NT 4.0</para></listitem> + </itemizedlist> + </para> + </section> + + </section> + + <section id="ChIntroDownload"> + <title>Where to get Ethereal?</title> + <para> + You can get the latest copy of the program from the Ethereal website: + <ulink url="&EtherealDownloadPage;">&EtherealDownloadPage;</ulink>. The + website allows you to choose from among several mirrors for + downloading. + </para> + <para> + A new Ethereal version will typically become available every 4-8 weeks. + </para> + <para> + If you want to be notified about new Ethereal releases, you should + subscribe to the ethereal-announce mailing list. You will find more + details in <xref linkend="ChIntroMailingLists"/>. + </para> + </section> + + <section id="ChIntroPronounce"> + <title>A rose by any other name</title> + <para> + William Shakespeare wrote: + <emphasis> + "A rose by any other name would smell as sweet." + </emphasis> + And so it is with Ethereal, as there appears to be two different + ways that people pronounce the name. + </para> + <para> + Some people pronounce it ether-real, while others pronounce it + e-the-real, as in ghostly, insubstantial, etc. + </para> + <para> + You are welcome to call it what you like, as long as you find it + useful. The FAQ gives the official pronounciation as "e-the-real". + </para> + </section> + + <section id="ChIntroHistory"> + <title>A brief history of Ethereal</title> + <para> + In late 1997, Gerald Combs needed a tool for tracking down + networking problems and wanted to learn more about networking, so + he started writing Ethereal as a way to solve both problems. + </para> + <para> + Ethereal was initially released, after several pauses in development, + in July 1998 as version 0.2.0. Within days, patches, bug reports, + and words of encouragement started arriving, so Ethereal was on its + way to success. + </para> + <para> + Not long after that Gilbert Ramirez saw its potential and contributed + a low-level dissector to it. + </para> + <para> + In October, 1998, Guy Harris of Network Appliance was looking for + something better than tcpview, so he started applying patches and + contributing dissectors to Ethereal. + </para> + <para> + In late 1998, Richard Sharpe, who was giving TCP/IP courses, saw its + potential on such courses, and started looking at it to see if it + supported the protocols he needed. While it didn't at that point, + new protocols could be easily added. So he started contributing + dissectors and contributing patches. + </para> + <para> + The list of people who have contributed to Ethereal has become very long + since then, and almost all of them started with a protocol that they + needed that Ethereal did not already handle. So they copied an existing + dissector and contributed the code back to the team. + </para> + </section> + + <section id="ChIntroMaintenance"> + <title> + Development and maintenance of <application>Ethereal</application> + </title> + <para> + Ethereal was initially developed by Gerald Combs. Ongoing development + and maintenance of Ethereal is handled by the Ethereal team, a loose + group of individuals who fix bugs and provide new functionality. + </para> + <para> + There have also been a large number of people who have contributed + protocol dissectors to Ethereal, and it is expected that this will + continue. You can find a list of the people who have contributed + code to Ethereal by checking the about dialog box of Ethereal, or at + the <ulink url="&EtherealAuthorsPage;">authors</ulink> page on the + Ethereal web site. + </para> + <para> + Ethereal is an open source software project, and is released under + the <ulink url="&GPLWebsite;">GNU General Public Licence</ulink> (GPL). + All source code is freely available under the GPL. You are welcome to + modify Ethereal to suit your own needs, and it would be appreciated + if you contribute your improvements back to the Ethereal team. + </para> + <para> + You gain three benefits by contributing your improvements back to the + community: + <itemizedlist> + <listitem> + <para> + Other people who find your contributions useful will appreciate + them, and you will know that you have helped people in the + same way that the developers of Ethereal have helped people. + </para> + </listitem> + <listitem> + <para> + The developers of Ethereal might improve your changes even more, + as there's always room for improvements. Or they may implement some + advanced things on top of your code, which can be useful for yourself + too. + </para> + </listitem> + <listitem> + <para> + The maintainers and developers of Ethereal will maintain your + code as well, fixing it when API changes or other changes are + made, and generally keeping it in tune with what is happening + with Ethereal. So if Ethereal is updated (which is done often), + you can get a new Ethereal version from the website and your changes + will already be included without any effort for you. + </para> + </listitem> + </itemizedlist> + </para> + <para> + The Ethereal source code and binary kits for some platforms are all + available on the download page of the Ethereal website: + <ulink url="&EtherealDownloadPage;">&EtherealDownloadPage;</ulink>. + </para> + </section> + + <section id="ChIntroHelp"> + <title>Reporting problems and getting help</title> + <para> + If you have problems, or need help with Ethereal, there are several + places that may be of interest to you (well, beside this guide of + course). + </para> + + <section id="ChIntroFAQ"><title>FAQ</title> + <para> + The "Frequently Asked Questions" will list often asked questions and + the corresponding answers. + <note><title>Read the FAQ!</title> + <para> + Before sending any mail to the mailing lists below, be sure to read the + FAQ, as it will often answer the question(s) you might have. This will save + yourself and others a lot of time (keep in mind that a lot of people are + subscribed to the mailing lists). + </para> + </note> + You will find the FAQ inside Ethereal by clicking the menu item + Help/Contents and selecting the FAQ page in the upcoming dialog. + </para> + <para> + An online version is available at the ethereal website: + <ulink url="&EtherealFAQPage;">&EtherealFAQPage;</ulink>. You might + prefer this online version, as it's typically more up to date and the HTML + format is easier to use. + </para> + </section> + + <section id="ChIntroMailingLists"><title>Mailing Lists</title> + <para> + There are several mailing lists of specific Ethereal topics available: + <variablelist> + <varlistentry><term><command>ethereal-announce</command></term> + <listitem> + <para> + This mailing list will inform you about new program + releases, which usually appear about every 4-8 weeks. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>ethereal-users</command></term> + <listitem> + <para> + This list is for users of Ethereal. People post + questions about building and using Ethereal, others (hopefully) + provide answers. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>ethereal-dev</command></term> + <listitem> + <para> + This list is for Ethereal developers. If you want to start + developing a protocol dissector, join this list. + </para> + </listitem> + </varlistentry> + </variablelist> + You can subscribe to each of these lists from the Ethereal web site: + <ulink url="&EtherealWebSite;">&EtherealWebSite;</ulink>. Simply + select the <command>mailing lists</command> link on the left hand + side of the site. The lists are archived at the Ethereal web site + as well. + <tip><title>Tip!</title> + <para> + You can search in the list archives to see if someone asked the same + question some time before and maybe already got an answer. That way you + don't have to wait until someone answers your question. + </para> + </tip> + </para> + </section> + + <section><title>Reporting Problems</title> + <note><title>Note!</title> + <para> + Before reporting any problems, please make sure you have installed the + latest version of Ethereal. + </para> + </note> + <para> + When reporting problems with Ethereal, it is helpful if you supply the + following information: + <orderedlist> + <listitem> + <para> + The version number of Ethereal and the dependent libraries linked with + it, eg GTK+, etc. You can obtain this with the command + <command>ethereal -v</command>. + </para> + </listitem> + <listitem> + <para> + Information about the platform you run Ethereal on. + </para> + </listitem> + <listitem> + <para> + A detailed description of your problem. + </para> + </listitem> + <listitem> + <para> + If you get an error/warning message, copy the text of that message + (and also a few lines before and after it, if there are some), so + others may find the place where things go wrong. Please don't + give something like: "I get a warning while doing x" as this won't + give a good idea where to look at. + </para> + </listitem> + </orderedlist> + </para> + <note><title>Don't send large files!</title> + <para> + Do not send large files (>100KB) to the mailing lists, just place a note + that further data is available on request. Large files will only annoy a + lot of people on the list who are not interested in your specific problem. + If required, you will be asked for further data by the persons who really + can help you. + </para> + </note> + <note><title>Don't send confidential information!</title> + <para> + If you send captured data to the mailing lists, be sure they don't contain + any sensitive or confidential information like passwords or such. + </para> + </note> + </section> + + <section><title>Reporting Crashes on UNIX/Linux platforms</title> + <para> + When reporting crashes with Ethereal, it is helpful if you supply the + traceback information (besides the information mentioned in "Reporting + Problems"). + </para> + <para> + You can obtain this traceback information with the following commands: + <programlisting> +<![CDATA[ +$ gdb `whereis ethereal | cut -f2 -d: | cut -d' ' -f2` core >& bt.txt +backtrace +^D +$ +]]> + </programlisting> + <note> + <para> + Type the characters in the first line verbatim! Those are + back-tics there! + </para> + </note> + <note> + <para> + backtrace is a <command>gdb</command> command. You should + enter it verbatim after the first line shown above, but it will not be + echoed. The ^D + (Control-D, that is, press the Control key and the D key + together) will cause <command>gdb</command> to exit. This will + leave you with a file called + <filename>bt.txt</filename> in the current directory. + Include the file with your bug report. + </para> + </note> + <note> + <para> + If you do not have <command>gdb</command> available, you + will have to check out your operating system's debugger. + </para> + </note> + </para> + <para> + You should mail the traceback to the + <ulink url="mailto:&EtherealDevMailList;">&EtherealDevMailList;</ulink> + mailing list. + </para> + </section> + + <section><title>Reporting Crashes on Windows platforms</title> + <para> + The Windows distributions don't contain the symbol files (.pdb), because + they are very large. For this reason it's not possible to create + a meaningful backtrace file from it. You should report your crash just + like other problems, using the mechanism described above. + </para> + </section> + </section> + +</chapter> +<!-- End of EUG Chapter 1 --> diff --git a/docbook/eug_src/EUG_chapter_io.xml b/docbook/eug_src/EUG_chapter_io.xml new file mode 100644 index 0000000000..1d1fe1dc79 --- /dev/null +++ b/docbook/eug_src/EUG_chapter_io.xml @@ -0,0 +1,766 @@ +<!-- EUG Chapter IO --> +<!-- $Id$ --> + +<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/Import 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> + Print packets + </para> + </listitem> + </itemizedlist> + </para> + </section> + + <section id="ChIOOpenSection"><title>Open capture files</title> + <para> + Ethereal can read in previously saved capture files. + To read them, simply select the <command>Open</command> + menu item from the <command>File</command> menu. + Ethereal will then pop up the File + Open dialog box, which is discussed in more detail in + <xref linkend="ChIOOpen"/>. + </para> + <note><title>Note!</title> + <para> + You can also use <command>drag-and-drop </command> to open a file, by + simply dropping the desired file from your file manager onto Ethereal's + main window. However, drag-and-drop is not available/won't work in all + desktop environments. + </para> + </note> + <para> + If you didn't save the current capture file before, 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), Ethereal 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 Ethereal 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 + Ethereal. <xref linkend="ChIOOpenFileDialog"/> shows an example + of the Ethereal Open File Dialog box. + </para> + <note> + <title>Note</title> + <para> + Ethereal uses the open dialog box from the version of the GTK+ + toolkit that it's using. This dialog was completely redesigned in + GTK version 2.4. Depending on the installed GTK version, + your dialog box might look different. However, as the + functionality remains almost the same, much of this description + will work with your version of Ethereal. + </para> + </note> + <figure id="ChIOOpenFileDialog"> + <title>The "Open Capture File" Dialog box</title> + <graphic entityref="EtherealOpen" format="PNG"/> + </figure> + <para> + With this dialog box, you can perform the following actions: + <orderedlist> + <listitem> + <para> + The "+ Add" button allows you to add a directory, selected in the + right-hand pane, to the favorites (bookmarks?) list. 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> + Select files and directories with the list boxes. + </para> + </listitem> + <listitem> + <para> + View file preview information (like the filesize, the number of + packets, ...), while browsing the filesystem. + </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. + Clicking on the Filter button causes Ethereal to pop up + the Filters dialog box (which is discussed further in + <xref linkend="ChWorkDisplayFilterSection"/>). + </para> + </listitem> + <listitem> + <para> + Specify which name resolution is to be performed for all packets by + clicking on one of the "Enable name resolution" check buttons. + Details about name resolution can be found in + <xref linkend="ChAdvNameResolutionSection"/>. + </para> + </listitem> + <listitem> + <para> + Click the Open button to accept your selected file and open it. + If Ethereal doesn't recognize the capture format, it will grey out + this button. + </para> + </listitem> + <listitem> + <para> + Click the Cancel button to go back to Ethereal and not load a capture + file. + </para> + </listitem> + </orderedlist> + You can change the display filter and name resolution settings later while + viewing the packets. However, for very large capture files it can take a + significant amount of time changing these settings, so it might be + a good idea to set them in advance here. + </para> + </section> + + <section id="ChIOInputFormatsSection"> + <title>Input File Formats</title> + <para> + The following file formats from other capture tools can be opened by + <application>Ethereal</application>: + <itemizedlist> + <listitem><para>libpcap, tcpdump and various other tools using tcpdump's capture 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> + </itemizedlist> + </para> + <note><title>Note!</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 other packet types (e.g. token ring packets) may not be possible to + read 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 Ethereal. You can choose which + packets to save and which file format to be used. + </para> + <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="ChIOSaveCaptureFileAs"/> shows an example of this + dialog box. + </para> + <note> + <title>Note</title> + <para> + Ethereal uses the open dialog box from the version of the GTK+ + toolkit that it's using. This dialog was completely redesigned in + the GTK version 2.4. Depending on the installed GTK version, + your dialog box might look different. However, as the + functionality remains almost the same, much of this description + will work with your version of Ethereal. + </para> + </note> + <figure id="ChIOSaveCaptureFileAs"> + <title>The "Save Capture File As" dialog box</title> + <graphic entityref="EtherealSaveAs" format="PNG"/> + </figure> + <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="ChIOInputFormatsSection"/>. + </para> + <note> + <title>Note!</title> + <para> + Some capture formats may not be available, depending on the + packet types captured. + </para> + </note> + <tip> + <title>Tip!</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> + Use "Browse for other folders" to browse files and folders in your + file system. + </para> + </listitem> + <listitem> + <para> + Click on the Save button to accept your selected file and save to + it. If Ethereal has a problem saving the captured packets to + the file you specified, it will display an error dialog box. + After clicking OK on this error dialog box, you can try again. + </para> + </listitem> + <listitem> + <para> + Click on the Cancel button to go back to Ethereal and not save the + captured packets. + </para> + </listitem> + </orderedlist> + </para> + </section> + <section id="ChIOOutputFormatsSection"> + <title>Output File Formats</title> + <para> + The following file formats can be saved by <application>Ethereal</application>, + so other capture tools can read the capture data from: + <itemizedlist> + <listitem><para>libpcap (tcpdump)</para></listitem> + <listitem><para>Novell LANalyzer</para></listitem> + <listitem><para>Network Associates Sniffer</para></listitem> + <listitem><para>Sun snoop</para></listitem> + <listitem><para>Microsoft Network Monitor</para></listitem> + <listitem><para>Visual Networks Visual UpTime traffic</para></listitem> + <listitem><para>Accellent 5Views</para></listitem> + <listitem><para>Networks Instruments Observer version 9</para></listitem> + </itemizedlist> + </para> + <note><title></title> + <para> + Other protocol analyzers may require that the file has a certain suffix + in order to read the files you generate with Ethereal, e.g.: + </para> + <para> + ".DMP" for Tcpdump/libpcap + </para> + <para> + ".CAP" for Network Assosciates 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 Ethereal). + </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. Ethereal 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><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>Note!</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> + <figure id="ChIOMergeDialog"> + <title>The "Merge with Capture File" dialog box</title> + <graphic entityref="EtherealMergeDialog" format="PNG"/> + </figure> + <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> + <para> + All other controls will work the same way as in the "Open Capture File" + dialog box, see <xref linkend="ChIOOpen"/>. + </para> + </section> + </section> + + <section id="ChIOExportSection"><title>Exporting data</title> + <para> + Ethereal provides several ways and formats to export packet data. This + section describes general ways to export data from Ethereal. + </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. + <figure> + <title>The "Export as Plain Text File" dialog box</title> + <graphic entityref="EtherealExportPlainDialog" 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="EtherealExportPSDialog" 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="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. + <figure> + <title>The "Export as PSML File" dialog box</title> + <graphic entityref="EtherealExportPSMLDialog" 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://analyzer.polito.it/30alpha/docs/dissectors/PDMLSpec.htm"> + PDML specification</ulink>. + <note><title></title> + <para> + The PDML specification is not officially released and Ethereal's + implementation of it is still in an early beta state, so please expect + changes in future Ethereal versions. + </para> + </note> + <figure> + <title>The "Export as PDML File" dialog box</title> + <graphic entityref="EtherealExportPDMLDialog" 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="EtherealExportSelectedDialog" 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> + + <section id="ChIOPrintSection"><title>Printing packets</title> + <para> + To print packets, select the "Print..." menu item from the File menu. + When you do this, Ethereal 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="EtherealPrint" 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>PostScipt</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, which name is entered in the field or selected + using 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 for the + output function. + <figure id="ChIOPacketRangeFrame"> + <title>The "Packet Range" frame</title> + <graphic entityref="EtherealPacketRangeFrame" 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="EtherealPacketFormatFrame" 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 EUG Chapter IO --> + diff --git a/docbook/eug_src/EUG_chapter_statistics.xml b/docbook/eug_src/EUG_chapter_statistics.xml new file mode 100644 index 0000000000..72966ef63e --- /dev/null +++ b/docbook/eug_src/EUG_chapter_statistics.xml @@ -0,0 +1,497 @@ +<!-- EUG Chapter Statistics --> +<!-- $Id$ --> + +<chapter id="ChStatistics"> + <title>Statistics</title> + <section id="ChStatIntroduction"> + <title>Introduction</title> + <para> + Ethereal provides a wide range of network statistics. + </para> + <para> + These statistics range + from general information about the loaded capture file (like the number of + captured packets), to statistics about specific protocols + (e.g. statistics about the number of HTTP requests and responses captured). + <itemizedlist> + <listitem> + <para> + General statistics: + </para> + <itemizedlist> + <listitem> + <para><command>Summary</command> about the capture file.</para> + </listitem> + <listitem> + <para><command>Protocol Hierarchy</command> of the captured packets.</para> + </listitem> + <listitem> + <para><command>Endpoints</command> e.g. traffic to and from an IP + addresses.</para> + </listitem> + <listitem> + <para><command>Conversations</command> e.g. traffic between specific IP + addresses.</para> + </listitem> + <listitem> + <para><command>IO Graphs</command> visualizing the number of packets (or + similar) in time.</para> + </listitem> + </itemizedlist> + </listitem> + <listitem> + <para> + Protocol specific statistics: + </para> + <itemizedlist> + <listitem> + <para><command>Service Response Time</command> between request and response + of some protocols.</para> + </listitem> + <listitem> + <para><command>Various other</command> protocol specific statistics.</para> + </listitem> + </itemizedlist> + </listitem> + </itemizedlist> + <tip><title>Tip!</title> + <para> + The protocol specific statistics requires detailed knowledge about the + specific protocol. Unless you are familiar with that protocol, statistics + about it will be pretty hard to understand. + </para> + </tip> + </para> + </section> + + <section id="ChStatSummary"> + <title>The "Summary" window</title> + <para> + General statistics about the current capture file. + </para> + <figure><title>The "Summary" window</title> + <graphic entityref="EtherealStatsSummary" format="PNG"/> + </figure> + <itemizedlist> + <listitem> + <para><command>File</command> general information about the capture file. + </para> + </listitem> + <listitem> + <para><command>Time</command> the timestamps when the first and the + last packet were capturing (and the time between them).</para> + </listitem> + <listitem> + <para><command>Capture</command> information from the time when the + capture was done (only available if the packet data was captured from the + network and not loaded from a file).</para> + </listitem> + <listitem> + <para><command>Display</command> some display related information.</para> + </listitem> + <listitem> + <para> + <command>Traffic</command> some statistics of the network traffic seen. + If a display filter is set, you will see values in both columns. The + values in the <command>Captured</command> column will remain the same as + before, while the values in the <command>Displayed</command> column will + reflect the values corresponding to the packets shown in the display. + </para> + </listitem> + </itemizedlist> + </section> + + <section id="ChStatHierarchy"> + <title>The "Protocol Hierarchy" window</title> + <para> + The protocol hierarchy of the captured packets. + <figure><title>The "Protocol Hierarchy" window</title> + <graphic entityref="EtherealStatsHierarchy" format="PNG"/> + </figure> + This is a tree of all the protocols in the capture. You can collapse or + expand subtrees, by clicking on the plus / minus icons. By default, all + trees are expanded. + </para> + <para> + Each row contains the statistical values of one protocol. + </para> + <para> + The following columns containing the statistical values are available: + <itemizedlist> + <listitem> + <para><command>Protocol</command> this protocol's name</para> + </listitem> + <listitem> + <para><command>% Packets</command> the percentage of protocol packets, + relative to all packets in the capture</para> + </listitem> + <listitem> + <para><command>Packets</command> the absolute number of packets of this + protocol</para> + </listitem> + <listitem> + <para><command>Bytes</command> the absolute number of bytes of this + protocol</para> + </listitem> + <listitem> + <para><command>MBit/s</command> the bandwidth of this protocol, relative + to the capture time</para> + </listitem> + <listitem> + <para> + <command>End Packets</command> the absolute number of packets of this + protocol (where this protocol were the highest protocol to decode) + </para> + </listitem> + <listitem> + <para> + <command>End Bytes</command> the absolute number of bytes of this protocol + (where this protocol were the highest protocol to decode) + </para> + </listitem> + <listitem> + <para> + <command>End MBit/s</command> the bandwidth of this protocol, relative to + the capture time (where this protocol were the highest protocol to decode) + </para> + </listitem> + </itemizedlist> + </para> + <note><title>Note!</title> + <para> + Packets will usually contain multiple protocols, so more than one protocol + will be counted for each packet. + Example: In the screenshot IP has 99,17% and TCP 85,83% (which is together + much more than 100%). + </para> + </note> + </section> + + <section id="ChStatEndpoints"> + <title>Endpoints</title> + <para> + Statistics of the endpoints captured. + <tip><title>Tip!</title> + <para> + If you are looking for a feature other network tools call a <command> + hostlist</command>, here is the right place to look. The list of + Ethernet or IP endpoints is usually what you're looking for. + </para> + </tip> + </para> + <section id="ChStatEndpointDefinition"><title>What is an Endpoint?</title> + <para> + A network endpoint is the logical endpoint of separate protocol traffic of + a specific protocol layer. The endpoint statistics of Ethereal will take + the following endpoints into account: + </para> + <itemizedlist> + <listitem> + <para> + <command>Ethernet</command> an Ethernet endpoint is identical to the + Ethernet's MAC address. + </para> + </listitem> + <listitem> + <para> + <command>Fibre Channel</command> XXX - insert info here. + </para> + </listitem> + <listitem> + <para> + <command>FDDI</command> a FDDI endpoint is identical to the FDDI MAC + address. + </para> + </listitem> + <listitem> + <para> + <command>IPv4</command> an IP endpoint is identical to its IP address. + </para> + </listitem> + <listitem> + <para> + <command>IPX</command> XXX - insert info here. + </para> + </listitem> + <listitem> + <para> + <command>TCP</command> a TCP endpoint is a combination of the IP address + and the TCP port used, so different TCP ports on the same IP address are + different TCP endpoints. + </para> + </listitem> + <listitem> + <para> + <command>Token Ring</command> a Token Ring endpoint is identical to the + Token Ring MAC address. + </para> + </listitem> + <listitem> + <para> + <command>UDP</command> a UDP endpoint is a combination of the IP address + and the UDP port used, so different UDP ports on the same IP address are + different UDP endpoints. + </para> + </listitem> + </itemizedlist> + <note><title>Broadcast / multicast endpoints</title> + <para> + Broadcast / multicast traffic will be shown separately as additional + endpoints. Of course, as these endpoints are virtual endpoints, the real + traffic will be received by all (multicast: some) of the listed unicast + endpoints. + </para> + </note> + </section> + <section id="ChStatEndpointsWindow"> + <title>The "Endpoints" window</title> + <para> + This window shows statistics about the endpoints captured. + </para> + <figure><title>The "Endpoints" window</title> + <graphic entityref="EtherealStatsEndpoints" format="PNG"/> + </figure> + <para> + For each supported protocol, a tab is shown in this window. + The tab labels shows the number of endpoints captured (e.g. the + tab label "Ethernet: 5" tells you that five ethernet endpoints have been + captured). If no endpoints of a specific protocol were captured, the tab + label will be + grayed out (although the related page can still be selected). + </para> + <para> + Each row in the list shows the statistical values for exactly one endpoint. + </para> + <para> + <command>Name resolution</command> will be done if selected in the window + and if it is active for the specific protocol layer (MAC layer for the + selected Ethernet endpoints page). As you might have noticed, the first + row has a name + resolution of the first three bytes "Netgear", the second row's address was + resolved to an IP address (using ARP) and the third was resolved + to a broadcast (unresolved this would still be: ff:ff:ff:ff:ff:ff), the last two + Ethernet addresses remain unresolved. + </para> + <tip><title>Tip!</title> + <para> + This window will be updated frequently, so it will be useful, even if + you open it before (or while) you are doing a live capture. + </para> + </tip> + </section> + <section id="ChStatEndpointListWindow"> + <title>The protocol specific "Endpoint List" windows</title> + <para> + Before the combined window described above was available, each of its + pages were shown as separate windows. Even though the combined window is + much more convenient to use, these separate windows are still + available. The main reason is, they might process faster for + very large capture files. However, as the functionality is exactly the + same as in the combined window, they won't be discussed in detail here. + </para> + </section> + </section> + + <section id="ChStatConversations"> + <title>Conversations</title> + <para> + Statistics of the captured conversations. + </para> + <section><title>What is a Conversation?</title> + <para> + A network conversation is the traffic between two specific endpoints. For + example, an IP conversation is all the traffic between two IP addresses. + The description of the known endpoint types can be found in + <xref linkend="ChStatEndpointDefinition"/>. + </para> + </section> + <section id="ChStatConversationsWindow"><title>The "Conversations" window</title> + <para> + Beside the list content, the conversations window work the same way as the + endpoint ones, see <xref linkend="ChStatEndpointsWindow"/> for a + description how it works. + <figure><title>The "Conversations" window</title> + <graphic entityref="EtherealStatsConversations" format="PNG"/> + </figure> + </para> + </section> + <section id="ChStatConversationListWindow"> + <title>The protocol specific "Conversation List" windows</title> + <para> + Before the combined window described above was available, each of its + pages were shown as separate windows. Even though the combined window is + much more convenient to use, these separate windows are still + available. The main reason is, they might process faster for + very large capture files. However, as the functionality is exactly the + same as in the combined window, they won't be discussed in detail here. + </para> + </section> + </section> + + <section id="ChStatIOGraphs"> + <title>The "IO Graphs" window</title> + <para> + User configurable graph of the captured network packets. + </para> + <para> + You can define up to five differently colored graphs. + </para> + + <figure><title>The "IO Graphs" window</title> + <graphic entityref="EtherealStatsIOGraphs" format="PNG"/> + </figure> + + <para> + The user can configure the following things: + <itemizedlist> + <listitem> + <para><command>Graphs</command> + <itemizedlist> + <listitem> + <para> + <command>Graph 1-5</command> enable the graph 1-5 (only graph 1 is enabled + by default) + </para> + </listitem> + <listitem> + <para> + <command>Color</command> the color of the graph (cannot be changed) + </para> + </listitem> + <listitem> + <para> + <command>Filter:</command> a display filter for this graph (only the + packets that pass this filter will be taken into account for that graph) + </para> + </listitem> + <listitem> + <para> + <command>Style:</command> the style of the graph (Line/Impulse/FBar) + </para> + </listitem> + </itemizedlist> + </para> + </listitem> + + <listitem> + <para><command>X Axis</command> + <itemizedlist> + <listitem> + <para> + <command>Tick interval</command> an interval in x direction lasts + (10/1/0.1/0.01/0.001 seconds) + </para> + </listitem> + <listitem> + <para> + <command>Pixels per tick</command> use 10/5/2/1 pixels per tick interval + </para> + </listitem> + </itemizedlist> + </para> + </listitem> + + <listitem> + <para><command>Y Axis</command> + <itemizedlist> + <listitem> + <para> + <command>Unit</command> the unit for the y direction (Packets/Tick, + Bytes/Tick, Advanced...) + </para> + </listitem> + <listitem> + <para> + <command>Scale</command> the scale for the y unit + (10,20,50,100,200,500,...) + </para> + </listitem> + </itemizedlist> + </para> + </listitem> + + </itemizedlist> + XXX - describe the Advanced feature. + </para> + </section> + + <section id="ChStatSRT"> + <title>Service Response Time</title> + <para> + The service response time is the time between a request and the + corresponding response. This information is available for many protocols. + </para> + <para> + Service response time statistics are currently available for the following + protocols: + <itemizedlist> + <listitem> + <para><command>DCE-RPC</command></para> + </listitem> + <listitem> + <para><command>Fibre Channel</command></para> + </listitem> + <listitem> + <para><command>ITU-T H.225 RAS</command></para> + </listitem> + <listitem> + <para><command>LDAP</command></para> + </listitem> + <listitem> + <para><command>MGCP</command></para> + </listitem> + <listitem> + <para><command>ONC-RPC</command></para> + </listitem> + <listitem> + <para><command>SMB</command></para> + </listitem> + </itemizedlist> + As an example, the DCE-RPC service response time is described in more + detail. + <note><title>Note!</title> + <para> + The other Service Response Time windows will work the same way (or only + sligthly different) compared to the following description. + </para> + </note> + </para> + <section id="ChStatSRTDceRpc"> + <title>The "Service Response Time DCE-RPC" window</title> + <para> + The service response time of DCE-RPC is the time between the request and + the corresponding response. + </para> + <para> + First of all, you have to select the DCE-RPC interface: + </para> + <figure><title>The "Compute DCE-RPC statistics" window</title> + <graphic entityref="EtherealStatsSrtDcerpcFilter" format="PNG"/> + </figure> + <para> + You can optionally set a display filter, to reduce the amount of packets. + </para> + <figure><title>The "DCE-RPC Statistic for ..." window</title> + <graphic entityref="EtherealStatsSrtDcerpc" format="PNG"/> + </figure> + <para> + Each row corresponds to a method of the interface selected (so the EPM + interface in version 3 has 7 methods). For each + method the number of calls, and the statistics of the SRT time is + calculated. + </para> + </section> + </section> + + <section id="ChStatXXX"> + <title>The protocol specific statistics windows</title> + <para> + The protocol specific statistics windows display detailed information + of specific protocols and might be described in a later + version of this document. + </para> + </section> + +</chapter> +<!-- End of EUG Chapter Statistics --> + diff --git a/docbook/eug_src/EUG_chapter_troubleshoot.xml b/docbook/eug_src/EUG_chapter_troubleshoot.xml new file mode 100644 index 0000000000..b0afb9b251 --- /dev/null +++ b/docbook/eug_src/EUG_chapter_troubleshoot.xml @@ -0,0 +1,129 @@ +<!-- EUG Chapter Four --> +<!-- $Id$ --> + +<chapter id="Chap04"> + <title>Troubleshooting with <application>Ethereal</application></title> + <section> + <title>An approach to troubleshooting with Ethereal</title> + <para> + Ethereal is a very useful tool for network troubleshooting, since it + contains a number of features that allow you to quickly focus on + problems in your networkfor several reasons: + <itemizedlist> + <listitem> + <para> + It allows you to focus in on specific packets and protocols, + as you can see a large amount of detail associated with + various protocols. + </para> + </listitem> + <listitem> + <para> + It supports a large number of protocols, and the list of + protocols supported is growing as more people contribute + dissectors + </para> + </listitem> + <listitem> + <para> + By giving you a visual view of traffic in parts of your + network, and providing tools to filter and colorize that + information, you can get a better feel for your network + traffic, and can understand your network better. + </para> + </listitem> + </itemizedlist> + </para> + <para> + The following general approach is suggested: + <itemizedlist> + <listitem> + <para> + Determine that the problem looks like a networking problem. + There is no point in capturing packets if the problem is not + networking related. + </para> + </listitem> + <listitem> + <para> + Figure out where to capture packets. You will have to + capture packets from a part of the network where you can + actually get network traffic related to the problem. This is + especially important in the presence of switches and routers. + See <xref linkend="Ch04ROUSWI"/> for more details. + </para> + <para> + Because Ethereal can read many capture file formats, you can + capture using any conventient tool. One useful approach is + to use <command>tcpdump</command> to capture on remote + systems and then copy the capture file to your system for + later analysis. For more details on capturing with + <command>tcpdump</command>, see <xref linkend="Ch05tcpdump"/>. + </para> + </listitem> + <listitem> + <para> + Once you have captured packets that you think relate to + the problem, load them into Ethereal and look for your + problem. Using Ethereal's filtering and colorization + capabilities, you can quickly narrow down the capture to the + area of interest. + </para> + </listitem> + <listitem> + <para> + Examine the appropriate fields within the packets where + the problem appears to be. These can often help to reveal + the problem. + </para> + </listitem> + </itemizedlist> + </para> + </section> + <section id="Ch04ROUSWI"> + <title>Capturing in the presence of switches and routers</title> + <para> + In the old days of Ethernet, all network traffic was spreaded over one + "yellow" cable through the whole network. Capturing data was easy, + as all packets from the network could be captured using the + "promiscuous mode" at any place in the network. The only devices blocking + network traffic, were routers. But as routers were extremely expensive, + they were not widely used. + </para> + <para> + Then Ethernet wiring using hubs become the state of the art. As the hubs + still spreaded the packets all over the network, things regarding + capturing didn't changed. + </para> + <para> + At the next stage, Ethernet switches became widely available. This + complicated things a lot. When capturing traffic on a computer connected + to a switch, usually the switch will only forward packets to the computer, + which are directed to it, or to all computers (broadcast's). It's much the + same like deactivating the promiscuous mode of the capturing network card. + </para> + <para> + There are some ways to circumvent this. + </para> + <para> + Many vendor's switches support a feature known as "port spanning" + or "port mirroring" in which all of the traffic to and from port A + are also sent out port B. An excellent reference on the + "port spanning" feature of Cisco switches can be found at + <ulink url="http://www.cisco.com/warp/public/473/41.html"> + Configuring the Catalyst Switched Port Analyzer (SPAN) Feature + </ulink> + </para> + </section> + <section> + <title>Examples of troubleshooting</title> + <para> + Troubleshooting often requires a reasonable knowledge of the + protocols in question. However, as Ethereal will often give you some + good hints, you might get an idea of what is going wrong simply by + looking in the packets being exchanged. + </para> + </section> +</chapter> +<!-- End of EUG Chapter 4 --> + diff --git a/docbook/eug_src/EUG_chapter_use.xml b/docbook/eug_src/EUG_chapter_use.xml new file mode 100644 index 0000000000..12838b23b5 --- /dev/null +++ b/docbook/eug_src/EUG_chapter_use.xml @@ -0,0 +1,1860 @@ +<!-- EUG Chapter Three --> +<!-- $Id$ --> + +<chapter id="ChapterUsing"> + <title>User Interface</title> + <section id="ChUseIntroductionSection"><title>Introduction</title> + <para> + By now you have installed <application>Ethereal</application> and + are most likely keen to get started capturing your first packets. In + the next chapters we will explore: + <itemizedlist> + <listitem> + <para> + How the Ethereal user interface works + </para> + </listitem> + <listitem> + <para> + How to capture packets in <application>Ethereal</application> + </para> + </listitem> + <listitem> + <para> + How to view packets in <application>Ethereal</application> + </para> + </listitem> + <listitem> + <para> + How to filter packets in <application>Ethereal</application> + </para> + </listitem> + <listitem> + <para> + ... and many other things! + </para> + </listitem> + </itemizedlist> + </para> + </section> + + <section id="ChUseStartSection"><title>Start Ethereal</title> + <para> + You can start Ethereal from your shell or window manager. + <tip><title>Tip!</title> + <para> + When starting Ethereal it's possible to specify optional settings using + the command line. See <xref linkend="ChCustCommandLine"/> for details. + </para> + </tip> + <note><title>Note!</title> + <para> + In the following chapters, a lot of screenshots from Ethereal will be shown. + As Ethereal runs on many different platforms and there are different + versions of the underlying GUI toolkit (GTK 1.x / 2.x) used, your + screen might look different from the provided screenshots. But as there + are no real differences in functionality, these screenshots should still + be understandable. + </para> + </note> + </para> + </section> + + <section id="ChUseMainWindowSection"><title>The Main window</title> + <para> + Lets look at Ethereal's user interface. <xref linkend="ChUseFig01"/> shows + Ethereal as you would usually see it after some packets captured or loaded + (how to do this will be described later). + <figure id="ChUseFig01"> + <title>The Main window</title> + <graphic scale="100" entityref="EtherealThreePane1" format="PNG"/> + </figure> + </para> + <para> + Ethereal's main window consist of parts that are commonly known from many + other GUI programs. + <orderedlist> + <listitem> + <para> + The <emphasis>menu</emphasis> (see <xref linkend="ChUseMenuSection"/>) + is used to start actions. + </para> + </listitem> + <listitem> + <para> + The <emphasis>main toolbar</emphasis> (see <xref linkend="ChUseMainToolbarSection"/>) + provides quick access to frequently used items from the menu. + </para> + </listitem> + <listitem> + <para> + The <emphasis>filter toolbar</emphasis> (see <xref linkend="ChUseFilterToolbarSection"/>) + provides a way to directly manipulate the currently used display filter + (see <xref linkend="ChWorkDisplayFilterSection"/>). + </para> + </listitem> + <listitem> + <para> + The <emphasis>packet list pane</emphasis> (see <xref linkend="ChUsePacketListPaneSection"/>) + displays a summary of each packet captured. By clicking on packets + in this pane you control what is displayed in the other two panes. + </para> + </listitem> + <listitem> + <para> + The <emphasis>packet details pane</emphasis> (see <xref linkend="ChUsePacketDetailsPaneSection"/>) + displays the packet selected in the packet list pane in more detail. + </para> + </listitem> + <listitem> + <para> + The <emphasis>packet bytes pane</emphasis> (see <xref linkend="ChUsePacketBytesPaneSection"/>) + displays the data from the packet selected in the packet list pane, and + highlights the field selected in the packet details pane. + </para> + </listitem> + <listitem> + <para> + The <emphasis>statusbar</emphasis> (see <xref linkend="ChUseStatusbarSection"/>) + shows some detailed information about the current program state and + the captured data. + </para> + </listitem> + </orderedlist> + <tip><title>Tip!</title> + <para> + The layout of the main window can be customized by changing preference settings. + See <xref linkend="ChCustGUILayoutPrefPage"/> for details! + </para> + </tip> + </para> + </section> + + <section id="ChUseMenuSection"><title>The Menu</title> + <para> + The Ethereal menu sits on top of the Ethereal window. + An example is shown in <xref linkend="ChUseEtherealMenu"/>. + </para> + <note><title>Note!</title> + <para> + Menu items will be greyed out if the corresponding feature isn't + available. For example, you cannot save a capture file if you didn't + capture or load any data before. + </para> + </note> + <para> + <figure id="ChUseEtherealMenu"><title>The Menu</title> + <graphic entityref="EtherealMenuOnly" format="PNG"/> + </figure> + </para> + <para> + It contains the following items: + <variablelist> + <varlistentry><term><command>File</command></term> + <listitem> + <para> + This menu contains tems to open and merge capture files, + save / print / export capture files in whole or in part, + and to quit from Ethereal. See <xref linkend="ChUseFileMenuSection"/>. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Edit</command></term> + <listitem> + <para> + This menu contains items to find a packet, time reference or mark one + or more packets, set your preferences, + (cut, copy, and paste are not presently implemented). + See <xref linkend="ChUseEditMenuSection"/>. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>View</command></term> + <listitem> + <para>This menu controls the display of the captured data, + including the colorization of packets, zooming the font, + show a packet in a separate window, expand and collapse trees in packet details, .... + See <xref linkend="ChUseViewMenuSection"/>. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Go</command></term> + <listitem> + <para>This menu contains items to go to a specific packet. + See <xref linkend="ChUseGoMenuSection"/>. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Capture</command></term> + <listitem> + <para>This menu allows you to start and stop captures and to edit capture filters. + See <xref linkend="ChUseCaptureMenuSection"/>. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Analyze</command></term> + <listitem> + <para> + This menu contains items to manipulate display filters, enable or + disable the dissection of protocols, configure user specified decodes + and follow a TCP stream. + See <xref linkend="ChUseAnalyzeMenuSection"/>. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Statistics</command></term> + <listitem> + <para> + This menu contains menu-items to display various statistic windows, + including a summary of the packets that have been captured, + display protocol hierarchy statistics and much more. + See <xref linkend="ChUseStatisticsMenuSection"/>. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Help</command></term> + <listitem> + <para> + This menu contains items to help the user, like access to some basic + help, a list of the supported protocols, manual pages, online access + to some of the webpages, and the usual about dialog. + See <xref linkend="ChUseHelpMenuSection"/>. + </para> + </listitem> + </varlistentry> + </variablelist> + Each of these menu items is described in more detail in the sections + that follow. + </para> + <tip><title>Tip!</title> + <para> + You can access menu items directly or by pressing the corresponding + accelerator keys, which are shown at the right side of the + menu. For example, you can press the Control (or Strg in german) and the K + keys together to open the capture dialog. + </para> + </tip> + </section> + + <section id="ChUseFileMenuSection"><title>The "File" menu</title> + <para> + The Ethereal file menu contains the fields shown in + <xref linkend="ChUseTabFile"/>. + </para> + <figure id="ChUseEtherealFileMenu"> + <title>The "File" Menu</title> + <graphic entityref="EtherealFileMenu" format="PNG"/> + </figure> + <table id="ChUseTabFile" frame="none"><title>File menu items</title> + <tgroup cols="3"> + <colspec colnum="1" colwidth="72pt"/> + <colspec colnum="2" colwidth="80pt"/> + <thead> + <row> + <entry>Menu Item</entry> + <entry>Accelerator</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><command>Open...</command></entry> + <entry>Ctrl+O</entry> + <entry><para> + This menu item brings up the file open dialog box that + allows you to load a capture file for viewing. It is + discussed in more detail in <xref linkend="ChIOOpen"/>. + </para></entry> + </row> + <row> + <entry><command>Open Recent</command></entry> + <entry></entry> + <entry><para> + This menu item shows a submenu containing the recently opened + capture files. Clicking on one of the submenu items will open the + corresponding capture file directly. + </para></entry> + </row> + <row> + <entry><command>Merge...</command></entry> + <entry></entry> + <entry><para> + This menu item brings up the merge file dialog box that + allows you to merge a capture file into the currently loaded one. + It is discussed in more detail in <xref linkend="ChIOMergeSection"/>. + </para></entry> + </row> + <row> + <entry><command>Close</command></entry> + <entry>Ctrl+W</entry> + <entry><para> + This menu item closes the current capture. If you + haven't saved the capture, you will be asked to do so first + (this can be disabled by a preference setting). + </para></entry> + </row> + <row> + <entry><command>------</command></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry><command>Save</command></entry> + <entry>Ctrl+S</entry> + <entry><para> + This menu item saves the current capture. If you + have not set a default capture file name (perhaps with + the -w <capfile> option), Ethereal pops up the + Save Capture File As dialog box (which is discussed + further in <xref linkend="ChIOSaveAs"/>). + </para><note> + <title>Note!</title> + <para> + If you have already saved the current capture, this + menu item will be greyed out. + </para> + </note><note> + <title>Note!</title> + <para> + You cannot save a live capture while it is in + progress. You must stop the capture in order to + save. + </para> + </note></entry> + </row> + <row> + <entry><command>Save As...</command></entry> + <entry>Shift+Ctrl+S</entry> + <entry><para> + This menu item allows you to save the current capture + file to whatever file you would like. It pops up the + Save Capture File As dialog box (which is discussed + further in <xref linkend="ChIOSaveAs"/>). + </para></entry> + </row> + <row> + <entry><command>------</command></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry><command>Export > as "Plain Text" file...</command></entry> + <entry></entry> + <entry><para> + This menu item allows you to export all, or some, of the packets in + the capture file to a plain ASCII text file. + It pops up the Ethereal Export dialog box (which is discussed further in + <xref linkend="ChIOExportPlainDialog"/>). + </para></entry> + </row> + <row> + <entry><command>Export > as "PostScript" file...</command></entry> + <entry></entry> + <entry><para> + This menu item allows you to export the (or some) of the packets in + the capture file to a PostScript file. + It pops up the Ethereal Export dialog box (which is discussed further in + <xref linkend="ChIOExportPSDialog"/>). + </para></entry> + </row> + <row> + <entry><command>Export > as "PSML" file...</command></entry> + <entry></entry> + <entry><para> + This menu item allows you to export the (or some) of the packets in + the capture file to a PSML (packet summary markup language) XML file. + It pops up the Ethereal Export dialog box (which is discussed further in + <xref linkend="ChIOExportPSMLDialog"/>). + </para></entry> + </row> + <row> + <entry><command>Export > as "PDML" file...</command></entry> + <entry></entry> + <entry><para> + This menu item allows you to export the (or some) of the packets in + the capture file to a PDML (packet details markup language) XML file. + It pops up the Ethereal Export dialog box (which is discussed further in + <xref linkend="ChIOExportPDMLDialog"/>). + </para></entry> + </row> + <row> + <entry><command>Export > Selected Packet Bytes...</command></entry> + <entry>Ctrl+H</entry> + <entry><para> + This menu item allows you to export the currently selected bytes + in the packet bytes pane to a binary file. It pops up the + Ethereal Export dialog box (which is discussed further in + <xref linkend="ChIOExportSelectedDialog"/>) + </para></entry> + </row> + <row> + <entry><command>------</command></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry><command>Print...</command></entry> + <entry>Ctrl+P</entry> + <entry><para> + This menu item allows you to print all (or some of) the packets in + the capture file. It pops up the Ethereal Print dialog + box (which is discussed further in + <xref linkend="ChIOPrintSection"/>). + </para></entry> + </row> + <row> + <entry><command>------</command></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry><command>Quit</command></entry> + <entry>Ctrl+Q</entry> + <entry><para> + This menu item allows you to quit from Ethereal. + Ethereal will ask to save your capture file if you haven't saved + it before (this can be disabled by a preference setting). + </para></entry> + </row> + </tbody> + </tgroup> + </table> + </section> + + <section id="ChUseEditMenuSection"><title>The "Edit" menu</title> + <para> + The Ethereal Edit menu contains the fields shown in + <xref linkend="ChUseTabEdit"/>. + </para> + <figure id="ChUseEtherealEditMenu"> + <title>The "Edit" Menu</title> + <graphic entityref="EtherealEditMenu" format="PNG"/> + </figure> + <table id="ChUseTabEdit" frame="none"> + <title>Edit menu items</title> + <tgroup cols="3"> + <colspec colnum="1" colwidth="72pt"/> + <colspec colnum="2" colwidth="80pt"/> + <thead> + <row> + <entry>Menu Item</entry> + <entry>Accelerator</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><command>Find Packet...</command></entry> + <entry>Ctrl+F</entry> + <entry><para> + This menu item brings up a dialog box that allows you + to find a packet by many criteria. + There is further information on finding packets in + <xref linkend="ChWorkFindPacketSection"/>. + </para></entry> + </row> + <row> + <entry><command>Find Next</command></entry> + <entry>Ctrl+N</entry> + <entry><para> + This menu item tries to find the next packet matching the + settings from "Find Packet...". + </para></entry> + </row> + <row> + <entry><command>Find Previous</command></entry> + <entry>Ctrl+B</entry> + <entry><para> + This menu item tries to find the previous packet matching the + settings from "Find Packet...". + </para></entry> + </row> + <row> + <entry><command>------</command></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry><command>Time Reference > Set Time Reference</command></entry> + <entry>Ctrl+T</entry> + <entry><para> + This menu item set a time reference on the currently selected + packet. See <xref linkend="ChWorkTimeReferencePacketSection"/> for more information + about the time referenced packets. + </para></entry> + </row> + <row> + <entry><command>Time Reference > Find Next</command></entry> + <entry></entry> + <entry><para> + This menu item tries to find the next time referenced packet. + </para></entry> + </row> + <row> + <entry><command>Time Reference > Find Previous</command></entry> + <entry></entry> + <entry><para> + This menu item tries to find the previous time referenced packet. + </para></entry> + </row> + <row> + <entry><command>Mark Packet</command></entry> + <entry>Ctrl+M</entry> + <entry><para> + This menu item "marks" the currently selected packet. See + <xref linkend="ChWorkMarkPacketSection"/> for details. + </para></entry> + </row> + <row> + <entry><command>Mark All Packets</command></entry> + <entry></entry> + <entry><para> + This menu item "marks" all packets. + </para></entry> + </row> + <row> + <entry><command>Unmark All Packets</command></entry> + <entry></entry> + <entry><para>This menu item "unmarks" all marked packets. + </para></entry> + </row> + <row> + <entry><command>------</command></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry><command>Preferences...</command></entry> + <entry>Shift+Ctrl+P</entry> + <entry><para> + This menu item brings up a dialog box that allows + you to set preferences for many parameters that control + Ethereal. You can also save your preferences so Ethereal + will use them the next time you start it. More detail + is provided in <xref linkend="ChCustPreferencesSection"/>. + </para></entry> + </row> + </tbody> + </tgroup> + </table> + </section> + + <section id="ChUseViewMenuSection"><title>The "View" menu</title> + <para> + The Ethereal View menu contains the fields shown in + <xref linkend="ChUseTabView"/>. + </para> + <figure id="ChUseEtherealViewMenu"> + <title>The "View" Menu</title> + <graphic entityref="EtherealViewMenu" format="PNG"/> + </figure> + <table id="ChUseTabView" frame="none"> + <title>View menu items</title> + <tgroup cols="3"> + <colspec colnum="1" colwidth="72pt"/> + <colspec colnum="2" colwidth="80pt"/> + <thead> + <row> + <entry>Menu Item</entry> + <entry>Accelerator</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><command>Main Toolbar</command></entry> + <entry></entry> + <entry><para> + This menu item hides or shows the main toolbar, see + <xref linkend="ChUseMainToolbarSection"/>. + </para></entry> + </row> + <row> + <entry><command>Filter Toolbar</command></entry> + <entry></entry> + <entry><para> + This menu item hides or shows the filter toolbar, see + <xref linkend="ChUseFilterToolbarSection"/>. + </para></entry> + </row> + <row> + <entry><command>Statusbar</command></entry> + <entry></entry> + <entry><para> + This menu item hides or shows the statusbar, see + <xref linkend="ChUseStatusbarSection"/>. + </para></entry> + </row> + <row> + <entry><command>------</command></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry><command>Packet List</command></entry> + <entry></entry> + <entry><para> + This menu item hides or shows the packet list pane, see + <xref linkend="ChUsePacketListPaneSection"/>. + </para></entry> + </row> + <row> + <entry><command>Packet Details</command></entry> + <entry></entry> + <entry><para> + This menu item hides or shows the packet details pane, see + <xref linkend="ChUsePacketDetailsPaneSection"/>. + </para></entry> + </row> + <row> + <entry><command>Packet Bytes</command></entry> + <entry></entry> + <entry><para> + This menu item hides or shows the packet bytes pane, see + <xref linkend="ChUsePacketBytesPaneSection"/>. + </para></entry> + </row> + <row> + <entry><command>------</command></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry><command>Time Display Format > Time of Day</command></entry> + <entry></entry> + <entry><para> + Selecting this tells Ethereal to display time + stamps in time of day format, see + <xref linkend="ChWorkTimeFormatsSection"/>. + <note><title>Note!</title> + <para> + The fields "Time of Day", "Date and Time of + Day", "Seconds Since Beginning of Capture" and "Seconds Since + Previous Packet" are mutually exclusive. + </para> + </note> + </para></entry> + </row> + <row> + <entry><command>Time Display Format > Date and Time of Day</command></entry> + <entry></entry> + <entry><para> + Selecting this tells Ethereal to display the + time stamps in date and time of day format, see + <xref linkend="ChWorkTimeFormatsSection"/>. + </para></entry> + </row> + <row> + <entry><command>Time Display Format > Seconds Since Beginning of Capture</command></entry> + <entry></entry> + <entry><para> + Selecting this tells Ethereal to display time + stamps in seconds since beginning of capture format, see + <xref linkend="ChWorkTimeFormatsSection"/>. + </para></entry> + </row> + <row> + <entry><command>Time Display Format > Seconds Since Previous Packet</command></entry> + <entry></entry> + <entry><para> + Selecting this tells Ethereal to display time stamps in + seconds since previous packet format, see + <xref linkend="ChWorkTimeFormatsSection"/>. + </para></entry> + </row> + <row> + <entry><command>Name Resolution > Resolve Name</command></entry> + <entry></entry> + <entry><para> + This item allows you to trigger a name resolve of the current packet + only, see <xref linkend="ChAdvNameResolutionSection"/>. + </para></entry> + </row> + <row> + <entry><command>Name Resolution > Enable for MAC Layer</command></entry> + <entry></entry> + <entry><para> + This item allows you to control whether or not + Ethereal translates MAC addresses into names, see + <xref linkend="ChAdvNameResolutionSection"/>. + </para></entry> + </row> + <row> + <entry><command>Name Resolution > Enable for Network Layer</command></entry> + <entry></entry> + <entry><para> + This item allows you to control whether or not + Ethereal translates network addresses into names, see + <xref linkend="ChAdvNameResolutionSection"/>. + </para></entry> + </row> + <row> + <entry><command>Name Resolution > Enable for Transport Layer</command></entry> + <entry></entry> + <entry><para> + This item allows you to control whether or not + Ethereal translates transport addresses into names, see + <xref linkend="ChAdvNameResolutionSection"/>. + </para></entry> + </row> + <row> + <entry><command>Auto Scroll in Live Capture</command></entry> + <entry></entry> + <entry><para> + This item allows you to specify that Ethereal + should scroll the packet list pane as new packets come + in, so you are always looking at the last packet. If you + do not specify this, Ethereal simply adds new packets onto + the end of the list, but does not scroll the packet list + pane. + </para></entry> + </row> + <row> + <entry><command>------</command></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry><command>Zoom In</command></entry> + <entry>Ctrl++</entry> + <entry><para> + Zoom into the packet data (increase the font size). + </para></entry> + </row> + <row> + <entry><command>Zoom Out</command></entry> + <entry>Ctrl+-</entry> + <entry><para> + Zoom out of the packet data (decrease the font size). + </para></entry> + </row> + <row> + <entry><command>Normal Size</command></entry> + <entry>Ctrl+=</entry> + <entry><para> + Set zoom level back to 100% (set font size back to normal). + </para></entry> + </row> + <row> + <entry><command>------</command></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry><command>Collapse All</command></entry> + <entry></entry> + <entry><para> + Ethereal keeps a list of all the protocol subtrees + that are expanded, and uses it to ensure that the + correct subtrees are expanded when you display a packet. + This menu item collapses the tree view of all packets + in the capture list. + </para></entry> + </row> + <row> + <entry><command>Expand All</command></entry> + <entry></entry> + <entry><para> + This menu item expands all subtrees in all packets in + the capture. + </para></entry> + </row> + <row> + <entry><command>Expand Tree</command></entry> + <entry></entry> + <entry><para> + This menu item expands the currently selected subtree in the + packet details tree. + </para></entry> + </row> + <row> + <entry><command>------</command></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry><command>Coloring Rules...</command></entry> + <entry></entry> + <entry><para> + This menu item brings up a dialog box that allows you + to color packets in the packet list pane according to + filter expressions you choose. It can be very useful + for spotting certain types of packets, see + <xref linkend="ChCustColorizationSection"/>. + </para></entry> + </row> + <row> + <entry><command>------</command></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry><command>Show Packet in New Window</command></entry> + <entry></entry> + <entry><para> + This menu item brings up the selected packet in a + separate window. The separate window shows only the + tree view and byte view panes. + </para></entry> + </row> + <row> + <entry><command>Reload</command></entry> + <entry>Ctrl-R</entry> + <entry><para> + This menu item allows you to reload the current + capture file. + </para></entry> + </row> + </tbody> + </tgroup> + </table> + </section> + + <section id="ChUseGoMenuSection"><title>The "Go" menu</title> + <para> + The Ethereal Go menu contains the fields shown in + <xref linkend="ChUseTabGo"/>. + </para> + <figure id="ChUseEtherealGoMenu"> + <title>The "Go" Menu</title> + <graphic entityref="EtherealGoMenu" format="PNG"/> + </figure> + <table id="ChUseTabGo" frame="none"> + <title>Go menu items</title> + <tgroup cols="3"> + <colspec colnum="1" colwidth="72pt"/> + <colspec colnum="2" colwidth="80pt"/> + <thead> + <row> + <entry>Menu Item</entry> + <entry>Accelerator</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><command>Go to Packet...</command></entry> + <entry>Ctrl-G</entry> + <entry><para> + This menu item brings up a dialog box that allows you + to specify a packet number, and then goes to that packet. See + <xref linkend="ChWorkGoToPacketSection"/> for details. + </para></entry> + </row> + <row> + <entry><command>Go to Corresponding Packet</command></entry> + <entry></entry> + <entry><para> + This menu item goes to the corresponding packet of the currently + selected protocol field. If the selected field doesn't correspond + to a packet, this item is greyed out. + </para></entry> + </row> + <row> + <entry><command>------</command></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry><command>First Packet</command></entry> + <entry></entry> + <entry><para> + This menu item jumps to the first packet of the capture file. + </para></entry> + </row> + <row> + <entry><command>Last Packet</command></entry> + <entry></entry> + <entry><para> + This menu item jumps to the last packet of the capture file. + </para></entry> + </row> + </tbody> + </tgroup> + </table> + </section> + + <section id="ChUseCaptureMenuSection"><title>The "Capture" menu</title> + <para> + The Ethereal Capture menu contains the fields shown in + <xref linkend="ChUseTabCap"/>. + </para> + <figure id="ChUseEtherealCaptureMenu"> + <title>The "Capture" Menu</title> + <graphic entityref="EtherealCaptureMenu" format="PNG"/> + </figure> + <table id="ChUseTabCap" frame="none"> + <title>Capture menu items</title> + <tgroup cols="3"> + <colspec colnum="1" colwidth="72pt"/> + <colspec colnum="2" colwidth="80pt"/> + <thead> + <row> + <entry>Menu Item</entry> + <entry>Accelerator</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><command>Start...</command></entry> + <entry>Ctrl+K</entry> + <entry><para> + This menu item brings up the Capture Options + dialog box (discussed further in + <xref linkend="ChCapCaptureOptions"/>) and allows you to + start capturing packets. + </para></entry> + </row> + <row> + <entry><command>Stop</command></entry> + <entry>Ctrl+E</entry> + <entry><para> + This menu item stops the currently running capture, see + <xref linkend="ChCapStopSection"/>) . + </para></entry> + </row> + <row> + <entry><command>Interfaces ...</command></entry> + <entry></entry> + <entry><para> + This menu item brings up a dialog box that shows what's going on + at the network interfaces Ethereal knows of, see + <xref linkend="ChCapInterfaceSection"/>) . + </para></entry> + </row> + <row> + <entry><command>Capture Filters...</command></entry> + <entry></entry> + <entry><para> + This menu item brings up a dialog box that allows you to + create and edit capture filters. You can name filters, + and you can save them for future use. More detail on + this subject is provided in + <xref linkend="ChWorkDefineFilterSection"/> + </para></entry> + </row> + </tbody> + </tgroup> + </table> + </section> + + <section id="ChUseAnalyzeMenuSection"><title>The "Analyze" menu</title> + <para> + The Ethereal Analyze menu contains the fields shown in + <xref linkend="ChUseAnalyze"/>. + </para> + <figure id="ChUseEtherealAnalyzeMenu"> + <title>The "Analyze" Menu</title> + <graphic entityref="EtherealAnalyzeMenu" format="PNG"/> + </figure> + <table id="ChUseAnalyze" frame="none"><title>Analyze menu items</title> + <tgroup cols="3"> + <colspec colnum="1" colwidth="72pt"/> + <colspec colnum="2" colwidth="80pt"/> + <thead> + <row> + <entry>Menu Item</entry> + <entry>Accelerator</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><command>Display Filters...</command></entry> + <entry></entry> + <entry><para> + This menu item brings up a dialog box that allows you + to create and edit display filters. You can name + filters, and you can save them for future use. More + detail on this subject is provided in + <xref linkend="ChWorkDefineFilterSection"/> + </para></entry> + </row> + <row> + <entry><command>Apply as Filter > ...</command></entry> + <entry></entry> + <entry><para> + These menu items will change the current display filter and apply + the changed filter immediately. Depending on the chosen menu item, + the current display filter string will be replaced or appended to + by the selected protocol field in the packet details pane. + </para></entry> + </row> + <row> + <entry><command>Prepare a Filter > ...</command></entry> + <entry></entry> + <entry><para> + These menu items will change the current display filter but won't + apply the changed filter. Depending on the chosen menu item, + the current display filter string will be replaced or appended to + by the selected protocol field in the packet details pane. + </para></entry> + </row> + <row> + <entry><command>------</command></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry><command>Enabled Protocols...</command></entry> + <entry>Shift+Ctrl+R</entry> + <entry><para> + This menu item allows the user to enable/disable protocol + dissectors, see <xref linkend="ChAdvEnabledProtocols"/> + </para></entry> + </row> + <row> + <entry><command>Decode As...</command></entry> + <entry></entry> + <entry><para> + This menu item allows the user to force Ethereal to + decode certain packets as a particular protocol, see + <xref linkend="ChAdvDecodeAs"/> + </para></entry> + </row> + <row> + <entry><command>User Specified Decodes...</command></entry> + <entry></entry> + <entry><para> + This menu item allows the user to force Ethereal to + decode certain packets as a particular protocol, see + <xref linkend="ChAdvDecodeAsShow"/> + </para></entry> + </row> + <row> + <entry><command>------</command></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry><command>Follow TCP Stream</command></entry> + <entry></entry> + <entry><para> + This menu item brings up a separate window and displays + all the TCP segments captured that are on the same TCP + connection as a selected packet, see + <xref linkend="ChAdvFollowTCPSection"/> + </para></entry> + </row> + </tbody> + </tgroup> + </table> + </section> + + <section id="ChUseStatisticsMenuSection"><title>The "Statistics" menu</title> + <para> + The Ethereal Statistics menu contains the fields shown in + <xref linkend="ChUseStatistics"/>. + </para> + <figure id="ChUseEtherealStatisticsMenu"> + <title>The "Statistics" Menu</title> + <graphic entityref="EtherealStatisticsMenu" format="PNG"/> + </figure> + <para> + All menu items will bring up a new window showing specific statistical + information. + </para> + <table id="ChUseStatistics" frame="none"> + <title>Statistics menu items</title> + <tgroup cols="3"> + <colspec colnum="1" colwidth="72pt"/> + <colspec colnum="2" colwidth="80pt"/> + <thead> + <row> + <entry>Menu Item</entry> + <entry>Accelerator</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><command>Summary</command></entry> + <entry></entry> + <entry><para> + Show information about the data captured, see <xref + linkend="ChStatSummary"/>. + </para></entry> + </row> + <row> + <entry><command>Protocol Hierarchy</command></entry> + <entry></entry> + <entry><para> + Display a hierarchical tree of protocol statistics, see <xref + linkend="ChStatHierarchy"/>. + </para></entry> + </row> + <row> + <entry><command>Conversations</command></entry> + <entry></entry> + <entry><para> + Display a list of conversations (traffic between two endpoints), + see <xref linkend="ChStatConversationsWindow"/>. + </para></entry> + </row> + <row> + <entry><command>Endpoints</command></entry> + <entry></entry> + <entry><para> + Display a list of endpoints (traffic to/from an address), see + <xref linkend="ChStatEndpointsWindow"/>. + </para></entry> + </row> + <row> + <entry><command>IO Graphs</command></entry> + <entry></entry> + <entry><para> + Display user specified graphs (e.g. the number of packets in the + course of time), see <xref linkend="ChStatIOGraphs"/>. + </para></entry> + </row> + <row> + <entry><command>------</command></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry><command>Conversation List</command></entry> + <entry></entry> + <entry><para> + Display a list of conversations, obsoleted by the combined window + of Conversations above, see + <xref linkend="ChStatConversationListWindow"/>. + </para></entry> + </row> + <row> + <entry><command>Endpoint List</command></entry> + <entry></entry> + <entry><para> + Display a list of endpoints, obsoleted by the combined window + of Endpoints above, see + <xref linkend="ChStatEndpointListWindow"/>. + </para></entry> + </row> + <row> + <entry><command>Service Response Time</command></entry> + <entry></entry> + <entry><para> + Display the time between a request and the corresponding response, see + <xref linkend="ChStatSRT"/>. + </para></entry> + </row> + <row> + <entry><command>------</command></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry><command>ANSI</command></entry> + <entry></entry> + <entry><para>See <xref linkend="ChStatXXX"/></para></entry> + </row> + <row> + <entry><command>BOOTP-DHCP</command></entry> + <entry></entry> + <entry><para>See <xref linkend="ChStatXXX"/></para></entry> + </row> + <row> + <entry><command>GSM</command></entry> + <entry></entry> + <entry><para>See <xref linkend="ChStatXXX"/></para></entry> + </row> + <row> + <entry><command>HTTP</command></entry> + <entry></entry> + <entry><para>HTTP request/response statistics, see <xref linkend="ChStatXXX"/></para></entry> + </row> + <row> + <entry><command>ISUP Message Types</command></entry> + <entry></entry> + <entry><para>See <xref linkend="ChStatXXX"/></para></entry> + </row> + <row> + <entry><command>ITU-T H.225</command></entry> + <entry></entry> + <entry><para>See <xref linkend="ChStatXXX"/></para></entry> + </row> + <row> + <entry><command>MTP3</command></entry> + <entry></entry> + <entry><para>See <xref linkend="ChStatXXX"/></para></entry> + </row> + <row> + <entry><command>ONC-RPC Programs</command></entry> + <entry></entry> + <entry><para>See <xref linkend="ChStatXXX"/></para></entry> + </row> + <row> + <entry><command>RTP</command></entry> + <entry></entry> + <entry><para>See <xref linkend="ChStatXXX"/></para></entry> + </row> + <row> + <entry><command>SIP</command></entry> + <entry></entry> + <entry><para>See <xref linkend="ChStatXXX"/></para></entry> + </row> + <row> + <entry><command>TCP Stream Graph</command></entry> + <entry></entry> + <entry><para>See <xref linkend="ChStatXXX"/></para></entry> + </row> + <row> + <entry><command>WAP-WSP</command></entry> + <entry></entry> + <entry><para>See <xref linkend="ChStatXXX"/></para></entry> + </row> + </tbody> + </tgroup> + </table> + </section> + + <section id="ChUseHelpMenuSection"><title>The "Help" menu</title> + <para> + The Ethereal Help menu contains the fields shown in + <xref linkend="ChUseHelp"/>. + </para> + <figure id="ChUseEtherealHelpMenu"> + <title>The "Help" Menu</title> + <graphic entityref="EtherealHelpMenu" format="PNG"/> + </figure> + <table id="ChUseHelp" frame="none"> + <title>Help menu items</title> + <tgroup cols="3"> + <colspec colnum="1" colwidth="72pt"/> + <colspec colnum="2" colwidth="80pt"/> + <thead> + <row> + <entry>Menu Item</entry> + <entry>Accelerator</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><command>Contents</command></entry> + <entry>F1</entry> + <entry><para> + This menu item brings up a basic help system. + </para></entry> + </row> + <row> + <entry><command>Supported Protocols</command></entry> + <entry></entry> + <entry><para> + This menu item brings up a dialog box showing the supported + protocols and protocol fields. + </para></entry> + </row> + <row> + <entry><command>Manual Pages > ...</command></entry> + <entry></entry> + <entry><para> + This menu item starts a Web browser showing one of the locally + installed html manual pages. + </para></entry> + </row> + <row> + <entry><command>Ethereal Online > ...</command></entry> + <entry></entry> + <entry><para> + This menu item starts a Web browser showing the chosen + webpage from: + <ulink url="&EtherealWebSite;">&EtherealWebSite;</ulink>. + </para></entry> + </row> + <row> + <entry><command>------</command></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry><command>About Ethereal</command></entry> + <entry></entry> + <entry><para> + This menu item brings up an information window that + provides some information on Ethereal, such as the plugins, the + used folders, ... + </para></entry> + </row> + </tbody> + </tgroup> + </table> + <note><title>Note!</title> + <para> + Calling a Web browser might be unsupported in your version of Ethereal. + If this is the case, the corresponding menu items will be hidden. + </para> + </note> + <note><title>Note!</title> + <para> + If calling a Web browser fails on your machine, maybe because just nothing + happens or the browser is started but no page is shown, have a look at the + webbrowser setting in the preferences dialog. + </para> + </note> + </section> + + <section id="ChUseMainToolbarSection"><title>The "Main" toolbar</title> + <para> + The main toolbar provides quick access to frequently used items from the + menu. This toolbar cannot be customized by the user, but it can be hidden + using the View menu, if the space on the screen is needed to show even + more packet data. + </para> + <para> + As in the menu, only the items useful in the current program state will + be available. The others will be greyed out (e.g. you cannot save a capture + file if you haven't loaded one). + <figure id="ChUseEtherealMainToolbar"> + <title>The "Main" toolbar</title> + <graphic entityref="EtherealMainToolbar" format="PNG"/> + </figure> + </para> + <table id="ChUseMainToolbar" frame="none"> + <title>Main toolbar items</title> + <tgroup cols="4"> + <colspec colnum="1" colwidth="40pt"/> + <colspec colnum="2" colwidth="80pt"/> + <colspec colnum="3" colwidth="80pt"/> + <thead> + <row> + <entry>Toolbar Icon</entry> + <entry>Toolbar Item</entry> + <entry>Corresponding Menu Item</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><graphic entityref="EtherealToolbarCapture" format="PNG"/></entry> + <entry><command>Start Capture...</command></entry> + <entry>Capture/Start...</entry> + <entry><para> + This item brings up the Capture Options + dialog box (discussed further in + <xref linkend="ChCapCapturingSection"/>) and allows you to + start capturing packets. + </para> + <note><title>Note!</title> + <para> + If a live capture is in progress, and you are using "Update List + of Packets in Realtime", this icon will be replaced by the Stop + Capture icon + <inlinegraphic entityref="EtherealToolbarStop" format="PNG"/>. + </para></note> + </entry> + </row> + <row> + <entry><graphic entityref="EtherealToolbarStop" format="PNG"/></entry> + <entry><command>Stop Capture</command></entry> + <entry>Capture/Stop</entry> + <entry><para> + This item stops the currently running live capture process + <xref linkend="ChCapCapturingSection"/>). + </para> + <note><title>Note!</title> + <para> + This icon is shown if a live capture is in progress, and you are + using "Update List of Packets in Realtime", otherwise the Start + Capture icon + <inlinegraphic entityref="EtherealToolbarCapture" format="PNG"/> + is shown. + </para></note> + </entry> + </row> + <row> + <entry><command>------</command></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry><graphic entityref="EtherealToolbarOpen" format="PNG"/></entry> + <entry><command>Open...</command></entry> + <entry>File/Open...</entry> + <entry><para> + This item brings up the file open dialog box that + allows you to load a capture file for viewing. It is + discussed in more detail in <xref linkend="ChIOOpen"/>. + </para></entry> + </row> + <row> + <entry><graphic entityref="EtherealToolbarSaveAs" format="PNG"/></entry> + <entry><command>Save As...</command></entry> + <entry>File/Save As...</entry> + <entry><para> + This item allows you to save the current capture file to whatever + file you would like. It pops up the Save Capture File As dialog + box (which is discussed further in <xref linkend="ChIOSaveAs"/>). + </para> + <note><title>Note!</title> + <para> + If you currently have a temporary capture file, the Save icon + <inlinegraphic entityref="EtherealToolbarSave" format="PNG"/> will be + shown instead. + </para></note> + </entry> + </row> + <row> + <entry><graphic entityref="EtherealToolbarClose" format="PNG"/></entry> + <entry><command>Close</command></entry> + <entry>File/Close</entry> + <entry><para> + This item closes the current capture. If you + have not saved the capture, you will be asked to save it first. + </para></entry> + </row> + <row> + <entry><graphic entityref="EtherealToolbarReload" format="PNG"/></entry> + <entry><command>Reload</command></entry> + <entry>View/Reload</entry> + <entry><para> + This item allows you to reload the current capture file. + </para></entry> + </row> + <row> + <entry><graphic entityref="EtherealToolbarPrint" format="PNG"/></entry> + <entry><command>Print...</command></entry> + <entry>File/Print...</entry> + <entry><para> + This item allows you to print all (or some of) the packets in + the capture file. It pops up the Ethereal Print dialog + box (which is discussed further in + <xref linkend="ChIOPrintSection"/>). + </para></entry> + </row> + <row> + <entry><command>------</command></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry><graphic entityref="EtherealToolbarFind" format="PNG"/></entry> + <entry><command>Find Packet...</command></entry> + <entry>Edit/Find Packet...</entry> + <entry><para> + This item brings up a dialog box that allows you + to find a packet. There is further information on finding packets + in <xref linkend="ChWorkFindPacketSection"/>. + </para></entry> + </row> + <row> + <entry><graphic entityref="EtherealToolbarFindPrevious" format="PNG"/></entry> + <entry><command>Find Previous</command></entry> + <entry>Edit/Find Previous</entry> + <entry><para> + This item tries to find the previous packet, matching the + settings from "Find Packet...". + </para></entry> + </row> + <row> + <entry><graphic entityref="EtherealToolbarFindNext" format="PNG"/></entry> + <entry><command>Find Next</command></entry> + <entry>Edit/Find Next</entry> + <entry><para> + This item tries to find the next packet, matching the + settings from "Find Packet...". + </para></entry> + </row> + <row> + <entry><command>------</command></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry><graphic entityref="EtherealToolbarGoTo" format="PNG"/></entry> + <entry><command>Go to Packet...</command></entry> + <entry>Go/Go to Packet...</entry> + <entry><para> + This item brings up a dialog box that allows you + to specify a packet number to go to that packet. + </para></entry> + </row> + <row> + <entry><graphic entityref="EtherealToolbarGoFirst" format="PNG"/></entry> + <entry><command>Go To First Packet</command></entry> + <entry>Go/First Packet</entry> + <entry><para> + This item jumps to the first packet of the capture file. + </para></entry> + </row> + <row> + <entry><graphic entityref="EtherealToolbarGoLast" format="PNG"/></entry> + <entry><command>Go To Last Packet</command></entry> + <entry>Go/Last Packet</entry> + <entry><para> + This item jumps to the last packet of the capture file. + </para></entry> + </row> + <row> + <entry><command>------</command></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry><graphic entityref="EtherealToolbarZoomIn" format="PNG"/></entry> + <entry><command>Zoom In</command></entry> + <entry>View/Zoom In</entry> + <entry><para> + Zoom into the packet data (increase the font size). + </para></entry> + </row> + <row> + <entry><graphic entityref="EtherealToolbarZoomOut" format="PNG"/></entry> + <entry><command>Zoom Out</command></entry> + <entry>View/Zoom Out</entry> + <entry><para> + Zoom out of the packet data (decrease the font size). + </para></entry> + </row> + <row> + <entry><graphic entityref="EtherealToolbarZoom100" format="PNG"/></entry> + <entry><command>Normal Size</command></entry> + <entry>View/Normal Size</entry> + <entry><para> + Set zoom level back to 100%. + </para></entry> + </row> + <row> + <entry><command>------</command></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry><graphic entityref="EtherealToolbarCaptureFilters" format="PNG"/></entry> + <entry><command>Capture Filters...</command></entry> + <entry>Capture/Capture Filters...</entry> + <entry><para> + This item brings up a dialog box that allows you to + create and edit capture filters. You can name filters, + and you can save them for future use. More detail on + this subject is provided in + <xref linkend="ChWorkDefineFilterSection"/>. + </para></entry> + </row> + <row> + <entry><graphic entityref="EtherealToolbarDisplayFilters" format="PNG"/></entry> + <entry><command>Display Filters...</command></entry> + <entry>Analyze/Display Filters...</entry> + <entry><para> + This item brings up a dialog box that allows you + to create and edit display filters. You can name + filters, and you can save them for future use. More + detail on this subject is provided in + <xref linkend="ChWorkDefineFilterSection"/>. + </para></entry> + </row> + <row> + <entry><graphic entityref="EtherealToolbarColoringRules" format="PNG"/></entry> + <entry><command>Coloring Rules...</command></entry> + <entry>View/Coloring Rules...</entry> + <entry><para> + This item brings up a dialog box that allows you + color packets in the packet list pane according to + filter expressions you choose. It can be very useful + for spotting certain types of packets. More + detail on this subject is provided in + <xref linkend="ChCustColorizationSection"/>. + </para></entry> + </row> + <row> + <entry><graphic entityref="EtherealToolbarPreferences" format="PNG"/></entry> + <entry><command>Preferences...</command></entry> + <entry>Edit/Preferences</entry> + <entry><para> + This item brings up a dialog box that allows + you to set preferences for many parameters that control + Ethereal. You can also save your preferences so Ethereal + will use them the next time you start it. More detail + is provided in <xref linkend="ChCustPreferencesSection"/> + </para></entry> + </row> + </tbody> + </tgroup> + </table> + </section> + + <section id="ChUseFilterToolbarSection"><title>The "Filter" toolbar</title> + <para> + The filter toolbar lets you quickly edit and apply display filters. More information on + display filters is available in <xref linkend="ChWorkDisplayFilterSection"/>. + <figure id="ChUseEtherealFilterToolbar"> + <title>The "Filter" toolbar</title> + <graphic entityref="EtherealFilterToolbar" format="PNG"/> + </figure> + <itemizedlist> + <listitem> + <para> + The leftmost button labeled "Filter:" can be clicked to + bring up the filter construction dialog, described in <xref linkend="FiltersDialog"/>. + </para> + </listitem> + <listitem> + <para> + The left middle text box provides an area to enter or edit display + filter strings, see <xref linkend="ChWorkBuildDisplayFilterSection"/> + . A syntax check of your filter string is done while you are typing. + The background will turn red if you enter an incomplete or invalid + string, and will become green when you enter a valid string. You can + click on the pull down arrow to select a previously-entered filter + string from a list. The entries in the pull down list will remain + available even after a program restart. + </para> + <note><title>Note!</title> + <para> + After you've changed something in this field, don't forget to press + the Apply button (or the Enter/Return key), to apply this filter + string to the display. + </para> + </note> + <note><title>Note!</title> + <para> + This field is also where the current filter in effect is displayed. + </para> + </note> + </listitem> + <listitem> + <para> + The middle button labeled "Add Expression..." opens a dialog box that lets + you edit a display filter from a list of protocol fields, described in + <xref linkend="ChWorkFilterAddExpressionSection"/> + </para> + </listitem> + <listitem> + <para> + The right middle button labeled "Clear" resets the current + display filter and clears the edit area. + </para> + </listitem> + <listitem> + <para> + The rightmost button labeled "Apply" applies the current + value in the edit area as the new display filter. + </para> + </listitem> + </itemizedlist> + </para> + <note><title>Note!</title> + <para> + Applying a display filter on large capture files might take quite a long time! + </para> + </note> + </section> + + <section id="ChUsePacketListPaneSection"><title>The "Packet List" pane</title> + <para> + The packet list pane displays all the packets in the current capture + file. + <figure id="ChUseEtherealListPane"> + <title>The "Packet List" pane</title> + <graphic entityref="EtherealListPane" format="PNG"/> + </figure> + Each line in the packet list corrresponds to one packet in the capture + file. If you select a line in this pane, more details will be displayed in + the "Packet Details" and "Packet Bytes" panes. + </para> + <para> + While dissecting a packet, Ethereal will place information from the + protocol dissectors into the columns. As higher level protocols might + overwrite information from lower levels, you will typically see the + information from the highest possible level only. + </para> + <para> + For example, let's look at a packet containing TCP inside IP inside + an Ethernet packet. The Ethernet dissector will write its data (such as + the Ethernet addresses), the IP dissector will overwrite this by its own + (such as the IP addresses), the TCP dissector will overwrite the IP + information, and so on. + </para> + <para> + There are a lot of different columns available. Which columns are + displayed can be selected by preference settings, see + <xref linkend="ChCustGUIColumnsPrefPage"/>. + </para> + <para> + The default columns will show: + <itemizedlist> + <listitem> + <para><command>No.</command> + The number of the packet in the capture file. This number won't change, + even if a display filter is used. + </para> + </listitem> + <listitem> + <para><command>Time</command> + The timestamp of the packet. The presentation format of this timestamp + can be changed, see <xref linkend="ChWorkTimeFormatsSection"/>. + </para> + </listitem> + <listitem> + <para><command>Source</command> + The address where this packet is coming from. + </para> + </listitem> + <listitem> + <para><command>Destination</command> + The address where this packet is going to. + </para> + </listitem> + <listitem> + <para><command>Protocol</command> + The protocol name in a short (perhaps abbreviated) version. + </para> + </listitem> + <listitem> + <para><command>Info</command> + Additional information about the packet content. + </para> + </listitem> + </itemizedlist> + </para> + <para> + There is a context menu (right mouse click) available, see details in + <xref linkend="ChWorkPacketListPanePopUpMenu"/>. + </para> + </section> + + <section id="ChUsePacketDetailsPaneSection"><title>The "Packet Details" pane</title> + <para> + The packet details pane shows the current packet (selected in the "Packet List" + pane) in a more detailed form. + <figure id="ChUseEtherealDetailsPane"> + <title>The "Packet Details" pane</title> + <graphic entityref="EtherealDetailsPane" format="PNG"/> + </figure> + </para> + <para> + This pane shows the protocols and protocol fields of the packet selected + in the "Packet List" pane. The protocols and fields of the packet are + displayed using a tree, which can be expanded and collapsed. + </para> + <para> + There is a context menu (right mouse click) available, see details in + <xref linkend="ChWorkPacketDetailsPanePopUpMenu"/>. + </para> + <para> + Some protocol fields are specially displayed. + </para> + <itemizedlist> + <listitem> + <para> + <command>Generated fields</command> + Ethereal itself will generate additional protocol fields which are + surrounded by brackets. The information in these fields is derived from the + known context to other packets in the capture file. For example, Ethereal + is doing a sequence/acknowledge analysis of each TCP stream, + which is displayed in the [SEQ/ACK analysis] fields of the TCP protocol. + </para> + </listitem> + <listitem> + <para> + <command>Links</command> + If Ethereal detected a relationship to another packet in the capture file, + it will generate a link to that packet. Links are underlined and displayed + in blue. If double-clicked, Ethereal jumps to the corresponding packet. + </para> + </listitem> + </itemizedlist> + </section> + + <section id="ChUsePacketBytesPaneSection"><title>The "Packet Bytes" pane</title> + <para> + The packet bytes pane shows the data of the current packet (selected in the "Packet List" + pane) in a hexdump style. + <figure id="ChUseEtherealBytesPane"> + <title>The "Packet Bytes" pane</title> + <graphic entityref="EtherealBytesPane" format="PNG"/> + </figure> + </para> + <para> + As usual for a hexdump, the left side shows the offset in the packet data, + in the middle the packet data is shown in a hexadecimal representation and + on the right the corresponding ASCII characters (or . if not appropriate) + are displayed. + </para> + <para> + There is a context menu (right mouse click) available, see details in + <xref linkend="ChWorkPacketBytesPanePopUpMenu"/>. + </para> + <para> + Depending on the packet data, sometimes more than one page is available, + e.g. when Ethereal has reassembled some packets into a single chunk of + data, see <xref linkend="ChAdvReassemblySection"/>. In this case there are + some additional tabs shown at the bottom of the pane to let you select + the page you want to see. + <figure id="ChUseEtherealBytesPaneTabs"> + <title>The "Packet Bytes" pane with tabs</title> + <graphic entityref="EtherealBytesPaneTabs" format="PNG"/> + </figure> + </para> + <note><title>Note!</title> + <para> + The additional pages might contain data picked from multiple packets. + </para> + </note> + <para> + The context menu (right mouse click) of the tab labels will show a list of + all available pages. This can be helpful if the size in the pane is too + small for all the tab labels. + </para> + </section> + + <section id="ChUseStatusbarSection"><title>The Statusbar</title> + <para> + The statusbar displays informational messages. + </para> + <para> + In general, the left side will show context related information, while the + right side will show the current number of packets. + </para> + <para> + <figure id="ChUseEtherealStatusbarEmpty"> + <title>The initial Statusbar</title> + <graphic entityref="EtherealStatusbarEmpty" format="PNG"/> + </figure> + This statusbar is shown while no capture file is loaded, e.g. when + Ethereal is started. + </para> + <para> + <figure id="ChUseEtherealStatusbarLoaded"> + <title>The Statusbar with a loaded capture file</title> + <graphic entityref="EtherealStatusbarLoaded" format="PNG"/> + </figure> + The left side shows information about the capture file, its + name, its size and the elapsed time while it was being captured. + </para> + <para> + The right side shows the current number of packets in the + capture file. The following values are displayed: + <itemizedlist mark="bullet"> + <listitem> + <para><emphasis>P:</emphasis> the number of captured packets</para> + </listitem> + <listitem> + <para><emphasis>D:</emphasis> the number of packets currently being + displayed</para> + </listitem> + <listitem> + <para><emphasis>M:</emphasis> the number of marked packets</para> + </listitem> + </itemizedlist> + </para> + <para> + <figure id="ChUseEtherealStatusbarSelected"> + <title>The Statusbar with a selected protocol field</title> + <graphic entityref="EtherealStatusbarSelected" format="PNG"/> + </figure> + This is displayed if you have selected a protocol field from the + "Packet Details" pane. + </para> + <tip><title>Tip!</title> + <para> + The value between the brackets (in this example + <command>arp.opcode</command>) can be used as a display filter string, + representing the selected protocol field. + </para> + </tip> + </section> + +</chapter> +<!-- End of EUG Chapter 3 --> diff --git a/docbook/eug_src/EUG_chapter_work.xml b/docbook/eug_src/EUG_chapter_work.xml new file mode 100644 index 0000000000..a34148dab2 --- /dev/null +++ b/docbook/eug_src/EUG_chapter_work.xml @@ -0,0 +1,1383 @@ +<!-- EUG Chapter Work --> +<!-- $Id$ --> + +<chapter id="ChapterWork"> + <title>Working with captured packets</title> + + <section id="ChWorkViewPacketsSection"><title>Viewing packets you have captured</title> + <para> + Once you have captured some packets, or you have opened a previously + saved capture file, you can view the packets that are displayed in + the packet list pane by simply clicking on that packet in the + packet list pane, which will bring up the selected packet in the + tree view and byte view panes. + </para> + <para> + You can then expand any part of the tree view by clicking on the + <command>plus</command> sign (the symbol itself may vary) to the left of + that part of the payload, + and you can select individual fields by clicking on them in the tree + view pane. An example with a TCP packet selected is shown in + <xref linkend="ChWorkSelPack1"/>. It also has the Acknowledgment number + in the TCP header selected, which shows up in the byte view as the + selected bytes. + <figure id="ChWorkSelPack1"> + <title>Ethereal with a TCP packet selected for viewing</title> + <graphic entityref="EtherealPacketSelected1" format="PNG"/> + </figure> + </para> + <para> + You can also select and view packets the same way, while Ethereal is + capturing, if you selected "Update list of packets in real time" in the + Ethereal Capture Preferences dialog box. + </para> + <para> + In addition, you can view individual packets in a separate window as + shown in <xref linkend="ChWorkPacketSepView"/>. Do this by selecting the + packet you are interested in in the packet list pane, and then + select "Show Packet in New Windows" from the Display menu. This + allows you to easily compare two or more packets. + <figure id="ChWorkPacketSepView"> + <title>Viewing a packet in a separate window</title> + <graphic entityref="EtherealPacketSepView" format="PNG"/> + </figure> + </para> + <para> + Finally, you can bring up a pop-up menu over either the "Packet List", + "Packet Details" or "Packet Bytes" pane by clicking your right mouse button. + </para> + <para> + The following table gives an overview of which functions are available + in the panes, where to find the corresponding function in the menu, and + a short description of each item. + </para> + <table id="PopupMenuTable"> + <title>Function overview of the pop-up menus</title> + <tgroup cols="6"> + <colspec colnum="1" colwidth="80pt"/> + <colspec colnum="2" colwidth="20pt"/> + <colspec colnum="3" colwidth="20pt"/> + <colspec colnum="4" colwidth="20pt"/> + <colspec colnum="5" colwidth="80pt"/> + <thead> + <row> + <entry>Item</entry> + <entry>List</entry> + <entry>Details</entry> + <entry>Bytes</entry> + <entry>Menu</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><command>Follow TCP stream</command></entry> + <entry>X</entry> + <entry>X</entry> + <entry>X</entry> + <entry>Analyze</entry> + <entry> + <para>View all the data on a TCP stream between a pair of nodes.</para> + </entry> + </row> + <row> + <entry><command>Decode As...</command></entry> + <entry>X</entry> + <entry>X</entry> + <entry>X</entry> + <entry>Analyze</entry> + <entry> + <para>.</para> + </entry> + </row> + <row> + <entry><command>Display Filters...</command></entry> + <entry>X</entry> + <entry>X</entry> + <entry>X</entry> + <entry>Analyze</entry> + <entry> + <para>Specify and manage filters.</para> + </entry> + </row> + <row> + <entry><command>Mark Packet</command></entry> + <entry>X</entry> + <entry>-</entry> + <entry>-</entry> + <entry>Edit</entry> + <entry> + <para>Mark a packet.</para> + </entry> + </row> + <row> + <entry><command>Time Reference</command></entry> + <entry>X</entry> + <entry>-</entry> + <entry>-</entry> + <entry>Edit</entry> + <entry> + <para>Set/reset and find time references.</para> + </entry> + </row> + <row> + <entry><command>Apply as Filter</command></entry> + <entry>X</entry> + <entry>X</entry> + <entry>-</entry> + <entry>Analyze</entry> + <entry> + <para>.</para> + </entry> + </row> + <row> + <entry><command>Prepare a Filter</command></entry> + <entry>X</entry> + <entry>X</entry> + <entry>-</entry> + <entry>Analyze</entry> + <entry> + <para>.</para> + </entry> + </row> + <row> + <entry><command>Coloring Rules...</command></entry> + <entry>X</entry> + <entry>-</entry> + <entry>-</entry> + <entry>View</entry> + <entry> + <para>Colorize packets in the "Packet List" pane.</para> + </entry> + </row> + <row> + <entry><command>Print...</command></entry> + <entry>X</entry> + <entry>-</entry> + <entry>-</entry> + <entry>File</entry> + <entry> + <para>Print packets.</para> + </entry> + </row> + <row> + <entry><command>Show Packet in New Window</command></entry> + <entry>X</entry> + <entry>-</entry> + <entry>-</entry> + <entry>View</entry> + <entry> + <para>Display the selected packet in another window.</para> + </entry> + </row> + <row> + <entry><command>Resolve name</command></entry> + <entry>-</entry> + <entry>X</entry> + <entry>-</entry> + <entry>-</entry> + <entry> + <para>Cause a name resolution to be performed for the selected packet, + but NOT for every packet in the capture.</para> + </entry> + </row> + <row> + <entry><command>Go to Corresponding Packet</command></entry> + <entry>-</entry> + <entry>X</entry> + <entry>-</entry> + <entry>Go</entry> + <entry> + <para>If the selected field has a packet number in it, go to it. The + corresponding packet will often be a response which is requested by + this packet, or the request for which this packet is a response. + </para> + </entry> + </row> + <row> + <entry><command>Export Selected Packet Bytes...</command></entry> + <entry>-</entry> + <entry>X</entry> + <entry>X</entry> + <entry>File->Export</entry> + <entry> + <para>Export raw packet bytes to a binary file.</para> + </entry> + </row> + <row> + <entry><command>Protocol Preferences...</command></entry> + <entry>-</entry> + <entry>X</entry> + <entry>-</entry> + <entry>Edit</entry> + <entry> + <para>The menu item takes you to the preferences dialog and selects + the page corresponding to the protocol if there are settings + associated with the highlighted field. More information on preferences + can be found in <xref linkend="ChCustProtocolsPrefPages"/>. + </para> + </entry> + </row> + <row> + <entry><command>Collapse All</command></entry> + <entry>-</entry> + <entry>X</entry> + <entry>-</entry> + <entry>View</entry> + <entry> + <para> + Ethereal keeps a list of all the protocol subtrees that are + expanded, and uses it to ensure that the correct subtrees + are expanded when you display a packet. This menu item + collapses the tree view of all packets in the capture list. + </para> + </entry> + </row> + <row> + <entry><command>Expand All</command></entry> + <entry>-</entry> + <entry>X</entry> + <entry>-</entry> + <entry>View</entry> + <entry> + <para>Expand all subtrees in all packets in the capture. + </para> + </entry> + </row> + <row> + <entry><command>Expand Tree</command></entry> + <entry>-</entry> + <entry>X</entry> + <entry>-</entry> + <entry>View</entry> + <entry> + <para>Expand the currently selected subtree. + </para> + </entry> + </row> + </tbody> + </tgroup> + </table> + <para> + <figure id="ChWorkPacketListPanePopUpMenu"> + <title>Pop-up menu of "Packet List" pane</title> + <graphic entityref="EtherealPacketPanePopupMenu" format="PNG"/> + </figure> + <variablelist> + <varlistentry><term><command>Follow TCP Stream</command></term> + <listitem> + <para> + This menu item is the same as the Analyze menu item of + the same name. It allows you to view all the data on a TCP + stream between a pair of nodes. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Decode As...</command></term> + <listitem> + <para> + This menu item is the same as the Analyze menu item of the + same name. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Display Filters...</command></term> + <listitem> + <para> + This menu item is the same as the Analyze menu item of the same + name. It allows you to specify and manage display filters. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Mark Packet</command></term> + <listitem> + <para> + This menu item is the same as the Edit menu item of the same + name. It allows you to mark a packet. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Time Reference</command></term> + <listitem> + <para> + This menu item is the same as the Edit menu items of the same + name. It allows you to set and work with time references. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Apply as Filter</command></term> + <listitem> + <para> + This menu item is the same as the Analyze menu items of the same + name. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Prepare a Filter</command></term> + <listitem> + <para> + This menu item is the same as the Analyze menu items of the same + name. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><command>Coloring Rules...</command></term> + <listitem> + <para> + This menu item is the same as the View menu item of the + same name. It allows you to colorize packets in the packet + list pane. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Print...</command></term> + <listitem> + <para> + This menu item is the same as the File menu item of the same + name. It allows you to print packets. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><command>Show Packet in New Window</command></term> + <listitem> + <para> + This menu item is the same as the View menu item of the + same name. It allows you to display the selected packet in + another window. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + <para> + <figure id="ChWorkPacketDetailsPanePopUpMenu"> + <title>Pop-up menu of "Packet Details" pane</title> + <graphic entityref="EtherealDetailsPanePopupMenu" format="PNG"/> + </figure> + <variablelist> + <varlistentry><term><command>Follow TCP Stream</command></term> + <listitem> + <para> + This menu item is the same as the Analyze menu item of the + same name. It allows you to view all the data on a TCP stream + between a pair of nodes. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Decode As...</command></term> + <listitem> + <para> + This menu item is the same as the Analyze menu item of the + same name. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Display Filters...</command></term> + <listitem> + <para> + This menu item is the same as the Analyze menu item of the same + name. It allows you to specify and manage filters. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Resolve Name</command></term> + <listitem> + <para> + This menu item causes name resolution to be performed for + the selected packet, but NOT every packet in the capture. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Go to Corresponding Packet</command></term> + <listitem> + <para> + If the selected field has a corresponding packet, go to it. + Corresponding packets will usually be a request/response packet pair + or such. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Export Selected Packet Bytes...</command></term> + <listitem> + <para> + This menu item is the same as the File menu item of the same + name. It allows you to export raw packet bytes to a binary file. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Protocol Properties...</command></term> + <listitem> + <para> + The menu item takes you to the properties dialog and selects the + page corresponding to the protocol if there are properties + associated with the highlighted field. + More information on preferences can be found in + <xref linkend="ChCustGUIPrefPage"/>. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Apply as Filter</command></term> + <listitem> + <para> + This menu item is the same as the Analyze menu items of the same + name. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Prepare a Filter</command></term> + <listitem> + <para> + This menu item is the same as the Analyze menu items of the same + name. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Collapse All</command></term> + <listitem> + <para> + Ethereal keeps a list of all the protocol subtrees that are + expanded, and uses it to ensure that the correct subtrees + are expanded when you display a packet. This menu item + collapses the tree view of all packets in the capture list. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Expand All</command></term> + <listitem> + <para> + This menu item expands all subtrees in all packets in the + capture. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Expand Tree</command></term> + <listitem> + <para> + This menu item expands the currently selected subtree. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + <para> + <figure id="ChWorkPacketBytesPanePopUpMenu"> + <title>Pop-up menu of "Packet Bytes" pane</title> + <graphic entityref="EtherealBytesPanePopupMenu" format="PNG"/> + </figure> + <variablelist> + <varlistentry><term><command>Follow TCP Stream</command></term> + <listitem> + <para> + This menu item is the same as the Analyze menu item of the + same name. It allows you to view all the data on a TCP stream + between a pair of nodes. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Decode As...</command></term> + <listitem> + <para> + This menu item is the same as the Analyze menu item of the + same name. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Display Filters...</command></term> + <listitem> + <para> + This menu item is the same as the Analyze menu item of the same + name. It allows you to specify and manage filters. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Export Selected Packet Bytes...</command></term> + <listitem> + <para> + This menu item is the same as the File menu item of the same + name. It allows you to export raw packet bytes to a binary file. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </section> + + <section id="ChWorkDisplayFilterSection"><title>Filtering packets while viewing</title> + <para> + Ethereal has two filtering languages: One used when capturing + packets, and one used when displaying packets. In this section we + explore that second type of filter: Display filters. The first one + has already been dealt with in <xref linkend="ChCapCaptureFilterSection"/>. + </para> + <para> + Display filters allow you to concentrate on the packets you are + interested in. They allow you to select packets by: + <itemizedlist> + <listitem><para>Protocol</para></listitem> + <listitem><para>The presence of a field</para></listitem> + <listitem><para>The values of fields</para></listitem> + <listitem><para>A comparison between fields</para></listitem> + <listitem><para>... and a lot more!</para></listitem> + </itemizedlist> + </para> + <para> + To select packets based on protocol type, simply type the protocol you + are interested in in the <command>Filter:</command> field in the filter + toolbar of the Ethereal window and press enter to initiate + the filter. <xref linkend="ChWorkTCPFilter"/> shows an example of what + happens when you type <command>tcp</command> in the filter field. + </para> + <note> + <title>Note!</title> + <para> + All protocol and field names are entered in lowercase. Also, don't + forget to press enter after entering the filter expression. + </para> + </note> + <figure id="ChWorkTCPFilter"><title>Filtering on the TCP protocol</title> + <graphic entityref="EtherealFilterTCP" format="JPG"/> + </figure> + <para> + As you might have noticed, only packets of the TCP protocol are displayed + now (e.g. packets 1-10 are hidden). The packet numbering will remain as + before, so the first packet shown is now packet number 11. + </para> + <note> + <title>Note!</title> + <para> + When using a display filter, all packets remain in the capture file. + The display filter only changes the display of the capture file and + not its content! + </para> + </note> + <para> + You can filter on any protocol that Ethereal understands. + You can also filter on any field that a dissector adds to the tree + view, but only if the dissector has added an abbreviation for the + field. A list of such fields is available in the Ethereal in the + <command>Add Expression...</command> dialog box. You can find more + information on the <command>Add Expression...</command> dialog box + in <xref linkend="ChWorkFilterAddExpressionSection"/>. + </para> + <para> + For example, to narrow the packet list pane down to only those + packets to or from the IP address 192.168.0.1, use + <command>ip.addr==192.168.0.1</command>. + </para> + <note> + <title>Note!</title> + <para> + To remove the filter, click on the <command>Clear</command> button + to the right of the filter field. + </para> + </note> + </section> + + <section id="ChWorkBuildDisplayFilterSection"> + <title>Building display filter expressions</title> + <para> + Ethereal provides a simple but powerful display filter language that you + can build quite complex filter expressions with. You can compare + values in packets as well as combine expressions into more + specific expressions. The following sections provide more + information on doing this. + </para> + <section> + <title>Display filter fields</title> + <para> + Every field in the packet details pane can be used as a filter + string, this will result in showing only the packets where this field + exists. For example: the + filter string: <command>tcp</command> will show all packets containing the + tcp protocol. + </para> + <para> + There is a complete list of all filter fields available + through the menu item "Help/Supported Protocols" in the page "Display Filter + Fields" of the upcoming dialog. + </para> + <para> + XXX - add some more info here and a link to the statusbar info. + </para> + </section> + <section> + <title>Comparing values</title> + <para> + You can build display filters that compare values using a number + of different comparison operators. They are shown in + <xref linkend="DispCompOps"/>. + </para> + <tip><title></title> + <para> + You can use English and C-like terms in the same way, they can even be + mixed in a filter string! + </para> + </tip> + <table id="DispCompOps"> + <title>Display Filter comparison operators</title> + <tgroup cols="3"> + <colspec colnum="1" colwidth="50pt"/> + <colspec colnum="2" colwidth="50pt"/> + <thead> + <row> + <entry>English</entry> + <entry>C-like</entry> + <entry>Description and example</entry> + </row> + </thead> + <tbody> + <row> + <entry>eq</entry> + <entry><programlisting>==</programlisting></entry> + <entry><para> + <command>Equal</command></para><para> + <programlisting>ip.addr==10.0.0.5</programlisting> + </para></entry> + </row> + <row> + <entry>ne</entry> + <entry><programlisting>!=</programlisting></entry> + <entry><para> + <command>Not equal</command></para><para> + <programlisting>ip.addr!=10.0.0.5</programlisting> + </para></entry> + </row> + <row> + <entry>gt</entry> + <entry><programlisting>></programlisting></entry> + <entry><para> + <command>Greater than</command></para><para> + <programlisting>frame.pkt_len > 10</programlisting> + </para></entry> + </row> + <row> + <entry>lt</entry> + <entry><programlisting><</programlisting></entry> + <entry><para><command>Less than</command></para><para> + <programlisting>frame.pkt_len < 128</programlisting> + </para></entry> + </row> + <row> + <entry>ge</entry> + <entry><programlisting>>=</programlisting></entry> + <entry><para> + <command>Greater than or equal to</command></para><para> + <programlisting>frame.pkt_len ge 0x100</programlisting> + </para></entry> + </row> + <row> + <entry>le</entry> + <entry><programlisting><=</programlisting></entry> + <entry><para> + <command>Less than or equal to</command></para><para> + <programlisting>frame.pkt_len <= 0x20</programlisting> + </para></entry> + </row> + </tbody> + </tgroup> + </table> + <para> + In addition, all protocol fields are typed. + <xref linkend="ChWorkFieldTypes"/> provides a list of the types and + example of how to express them. + <table id="ChWorkFieldTypes"> + <title>Display Filter Field Types</title> + <tgroup cols="2"> + <thead> + <row> + <entry>Type</entry> + <entry>Example</entry> + </row> + </thead> + <tbody> + <row> + <entry> + Unsigned integer (8-bit, 16-bit, 24-bit, 32-bit) + </entry> + <entry><para> + You can express integers in decimal, octal, or + hexadecimal. The following display filters are + equivalent: + <programlisting> +ip.len le 1500 +ip.len le 02734 +ip.len le 0x436 + </programlisting> + </para></entry> + </row> + <row> + <entry> + Signed integer (8-bit, 16-bit, 24-bit, 32-bit) + </entry> + <entry></entry> + </row> + <row> + <entry>Boolean</entry> + <entry><para> + A boolean field is present in the protocol decode + only if its value is true. For example, + <command>tcp.flags.syn</command> is present, and + thus true, only if the SYN flag is present in a + TCP segment header.</para><para> + Thus the filter expression + <command>tcp.flags.syn</command> will select only + those packets for which this flag exists, that is, + TCP segments where the segment header contains the + SYN flag. Similarly, to find source-routed token + ring packets, use a filter expression of + <command>tr.sr</command>. + </para></entry> + </row> + <row> + <entry>Ethernet address (6 bytes)</entry> + <entry>eth.addr == ff:ff:ff:ff:ff:ff</entry> + </row> + <row> + <entry>IPv4 address</entry> + <entry>ip.addr == 192.168.0.1</entry> + </row> + <row> + <entry>IPv6 address</entry> + <entry> </entry> + </row> + <row> + <entry>IPX network number</entry> + <entry> </entry> + </row> + <row> + <entry>String (text)</entry> + <entry> </entry> + </row> + <row> + <entry> + Double-precision floating point number + </entry> + <entry> </entry> + </row> + </tbody> + </tgroup> + </table> + </para> + </section> + <section> + <title>Combining expressions</title> + <para> + You can combine filter expressions in Ethereal using the + logical operators shown in <xref linkend="FiltLogOps"/> + </para> + <table id="FiltLogOps"> + <title>Display Filter Logical Operations</title> + <tgroup cols="3"> + <colspec colnum="1" colwidth="50pt"/> + <colspec colnum="2" colwidth="50pt"/> + <thead> + <row> + <entry>English</entry> + <entry>C-like</entry> + <entry>Description and example</entry> + </row> + </thead> + <tbody> + <row> + <entry>and</entry> + <entry>&&</entry> + <entry><para> + <command>Logical AND</command></para><para> + <programlisting>ip.addr==10.0.0.5 and tcp.flags.fin</programlisting> + </para></entry> + </row> + <row> + <entry>or</entry> + <entry>||</entry> + <entry><para> + <command>Logical OR</command></para><para> + <programlisting>ip.addr==10.0.0.5 or ip.addr==192.1.1.1</programlisting> + </para></entry> + </row> + <row> + <entry>xor</entry> + <entry>^^</entry> + <entry><para> + <command>Logical XOR</command></para><para> + <programlisting>tr.dst[0:3] == 0.6.29 xor tr.src[0:3] == 0.6.29</programlisting> + </para></entry> + </row> + <row> + <entry>not</entry> + <entry>!</entry> + <entry><para> + <command>Logical NOT</command></para><para> + <programlisting>not llc</programlisting> + </para></entry> + </row> + <row> + <entry>[...]</entry> + <entry></entry> + <entry><para> + <command>Substring Operator</command></para><para> + Ethereal allows you to select subsequences of a + sequence in rather elaborate ways. After a label you + can place a pair of brackes [] containing a comma + separated list of range specifiers. </para><para> + <programlisting>eth.src[0:3] == 00:00:83</programlisting></para><para> + The example above uses the n:m format to specify a + single range. In this case n is the beginning offset + and m is the length of the range + being specified.</para><para> + <programlisting> +eth.src[1-2] == 00:83 + </programlisting></para><para> + The example above uses the n-m format to specify a + single range. In this case n is the beginning offset + and m is the ending offset. </para><para> + <programlisting>eth.src[:4] == 00:00:83:00</programlisting></para><para> + The example above uses the :m format, which takes + everything from the beginning of a sequence to offset m. + It is equivalent to 0:m</para><para> + <programlisting>eth.src[4:] == 20:20</programlisting></para><para> + The example above uses the n: format, which takes + everything from offset n to the end of the + sequence. </para><para> + <programlisting>eth.src[2] == 83</programlisting></para><para> + The example above uses the n format to specify a + single range. In this case the element in the + sequence at offset n is selected. This is equivalent + to n:1.</para><para> + <programlisting>eth.src[0:3,1-2,:4,4:,2] == +00:00:83:00:83:00:00:83:00:20:20:83</programlisting></para><para> + Ethereal allows you to string together single ranges + in a comma separated list to form compound ranges as + shown above. + </para></entry> + </row> + </tbody> + </tgroup> + </table> + </section> + <section><title>A common mistake</title> + <para> + Often people use a filter string to display something like + <command>ip.addr == 1.2.3.4</command> which will display all packets + containing the IP address 1.2.3.4. + </para> + <para> + Then they use <command>ip.addr != 1.2.3.4</command> to see all packets + not containing the IP address 1.2.3.4 in it. Unfortunately, this does + <command>not</command> do the expected. + </para> + <para> + Instead, that expression will even be true for packets where either + source or destination IP address equals 1.2.3.4. The reason for this, + is that the expression <command>ip.addr != 1.2.3.4</command> must be read as "the + packet contains a field named ip.addr with a value + different from 1.2.3.4". As an IP datagram contains both a source and + a destination address, the expression will evaluate to true whenever + at least one of the two addresses differs from 1.2.3.4. + </para> + <para> + If you want to + filter out all packets containing IP datagrams to or from IP address + 1.2.3.4, then the correct filter is <command>!(ip.addr == 1.2.3.4)</command> as it + reads "show me all the packets for which it is not true + that a field named ip.addr exists with a value of 1.2.3.4", or in + other words, "filter out all packets for which there are + no occurrences of a field named ip.addr with the value 1.2.3.4". + </para> + </section> + </section> + + <section id="ChWorkFilterAddExpressionSection"> + <title>The "Filter Expression" dialog box</title> + <para> + When you are accustomed to Ethereal's filtering system and know what + labels you wish to use in your filters it can be very quick to + simply type a filter string. However if you are new to Ethereal or + are working with a slightly unfamiliar protocol it can be very + confusing to try to figure out what to type. The Filter Expression + dialog box helps with this. + </para> + <tip><title>Tip!</title> + <para> + The "Filter Expression" dialog box is an excellent way to learn how to + write Ethereal display filter strings. + </para> + </tip> + <figure id="ChWorkFilterAddExpression1"> + <title>The "Filter Expression" dialog box</title> + <graphic entityref="EtherealFilterAddExpression" format="PNG"/> + </figure> + <para> + When you first bring up the Filter Expression dialog box you are shown a + tree list of field names, organized by protocol, and a box for + selecting a relation. + </para> + <variablelist> + <varlistentry><term><command>Field Name</command></term> + <listitem> + <para> + Select a protocol field from the protocol field tree. + Every protocol with filterable fields is listed at the + top level. By clicking on the "+" next to a protocol name + you can get a list of the field names available for filtering + for that protocol. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Relation</command></term> + <listitem> + <para> + Select a relation from the list of available relation. + The <command>is present</command> is a unary relation which + is true if the selected field is present in a packet. All + other listed relations are binary relations which require additional + data (e.g. a <command>Value</command> to match) to complete. + </para> + </listitem> + </varlistentry> + </variablelist> + <para> + When you select a field from the field name list and select a + binary relation (such as the equality relation ==) you will be + given the opportunity to enter a value, and possibly some range + information. + </para> + <variablelist> + <varlistentry><term><command>Value</command></term> + <listitem> + <para> + You may enter an appropriate value in the + <command>Value</command> text box. The <command>Value</command> + will also indicate the type of value for the + <command>field name</command> you have selected (like + character string). + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Predefined values</command></term> + <listitem> + <para> + Some of the protocol fields have predefined values available, much like + enum's in C. If the selected protocol field has such values defined, you + can choose it here. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Range</command></term> + <listitem> + <para> + XXX - add an explanation here! + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>OK</command></term> + <listitem> + <para> + When you have built a satisfactory expression click + <command>OK</command> and a filter string will be + built for you. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Cancel</command></term> + <listitem> + <para> + You can leave the <command>Add Expression...</command> dialog + box without any effect by clicking the <command>Cancel</command> + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + + <section id="ChWorkDefineFilterSection"><title>Defining and saving filters</title> + <para> + You can define filters with Ethereal and give them labels for + later use. This can save time in remembering and retyping some of + the more complex filters you use. + </para> + <para> + To define a new filter or edit an existing filter, select the + <command>Capture Filters...</command> menu item from the Capture menu + or the <command>Display Filters...</command> menu item from the Analyze + menu. Ethereal will then pop up the Filters dialog as shown in + <xref linkend="FiltersDialog"/>. + </para> + <note> + <title>Note!</title> + <para> + The mechanisms for defining and saving capture filters and display + filters are almost identical. So both will be described here, + differences between these two will be marked as such. + </para> + </note> + <warning><title>Warning!</title> + <para> + You must use <command>Save</command> to save your filters permanently. + <command>Ok</command> or <command>Apply</command> will not save the filters, + so they will be lost when you close Ethereal. + </para> + </warning> + <figure id="FiltersDialog"> + <title>The "Capture Filters" and "Display Filters" dialog boxes</title> + <graphic entityref="EtherealFilters" format="PNG"/> + </figure> + <para> + <variablelist> + <varlistentry><term><command>New</command></term> + <listitem> + <para> + This button adds a new filter to the list of filters. The currently + entered values from Filter name and Filter string will be used. If + any of these fields are empty, it will be set to "new". + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Delete</command></term> + <listitem> + <para> + This button deletes the selected filter. It will be greyed out, if no + filter is selected. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Filter</command></term> + <listitem> + <para> + You can select a filter from this list (which will fill in the + filter name and filter string in the fields down the bottom of the + dialog box). + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Filter name:</command></term> + <listitem> + <para> + You can change the name of the currently selected filter here. + </para> + <note><title>Note!</title> + <para> + The filter name will only be used in this dialog to identify the + filter for your convenience, it will not be used elsewhere. You can + add multiple filters with the same name, but this is not very useful. + </para> + </note> + </listitem> + </varlistentry> + <varlistentry><term><command>Filter string:</command></term> + <listitem> + <para> + You can change the filter string of the currently selected filter here. + Display Filter only: the string will be syntax checked while you are + typing. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Add Expression...</command></term> + <listitem> + <para> + Display Filter only: This button brings up the Add Expression + dialog box which assists in building filter strings. You can find + more information about the Add Expression dialog in + <xref linkend="ChWorkFilterAddExpressionSection"/> + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>OK</command></term> + <listitem> + <para> + Display Filter only: This button applies the selected filter to the + current display and closes the dialog. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Apply</command></term> + <listitem> + <para> + Display Filter only: This button applies the selected filter to the + current display, and keeps the dialog open. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Save</command></term> + <listitem> + <para> + Save the current settings in this dialog. The file location and + format is explained in <xref linkend="AppFiles"/>. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Close</command></term> + <listitem> + <para> + Close this dialog. This will discard unsaved settings. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </section> + + <section id="ChWorkFindPacketSection"><title>Finding packets</title> + <para> + You can easily find packets once you have captured some packets or + have read in a previously saved capture file. Simply select the + <command>Find Packet...</command> menu item from the + <command>Edit</command> menu. Ethereal will pop up the dialog box + shown in <xref linkend="ChWorkFindPacketDialog"/>. + </para> + <section><title>The "Find Packet" dialog box</title> + <figure id="ChWorkFindPacketDialog"> + <title>The "Find Packet" dialog box</title> + <graphic entityref="EtherealFindPacket" format="PNG"/> + </figure> + <para> + You might first select the kind of thing to search for: + <itemizedlist> + <listitem> + <para> + <command>Display filter</command> + </para> + <para> + Simply enter a display filter string into the + <command>Filter:</command> field, select a direction, and click on OK. + </para> + <para> + For example, to find the three way handshake for a connection from + host 192.168.0.1, use the following filter string: + <programlisting>ip.addr==192.168.0.1 and tcp.flags.syn</programlisting> + For more details on display filters, see <xref linkend="ChWorkDisplayFilterSection"/> + </para> + </listitem> + <listitem> + <para> + <command>Hex Value</command> + </para> + <para> + Search for a specific byte sequence in the packet data. + </para> + <para> + For example, use "00:00" to find the next packet including two + null bytes in the packet data. + </para> + </listitem> + <listitem> + <para> + <command>String</command> + </para> + <para> + Find a string in the packet data, with various options. + </para> + </listitem> + </itemizedlist> + </para> + <para> + The value to be found will by syntax checked while you type it in. If the + syntax check of your value succeeded, the background of the entry field + will turn green, if it fails, it will turn red. + </para> + <para> + You can choose the direction to be searched for: + <itemizedlist> + <listitem> + <para><command>Up</command></para> + <para>Search upwards in the packet list (decreasing packet numbers).</para> + </listitem> + </itemizedlist> + <itemizedlist> + <listitem> + <para><command>Down</command></para> + <para>Search downwards in the packet list (increasing packet numbers).</para> + </listitem> + </itemizedlist> + </para> + </section> + <section><title>The "Find Next" command</title> + <para> + "Find Next" will continue searching with the same options like in the last + "Find Packet" run. + </para> + </section> + <section><title>The "Find Previous" command</title> + <para> + "Find Previous" will do the same thing as "Find Next", but with reverse + search direction. + </para> + </section> + </section> + + <section id="ChWorkGoToPacketSection"><title>Go to a specific packet</title> + <para> + You can easily jump to specific packets with one of the menu items in the + Go menu. + </para> + <section><title>The "Go to Packet" dialog box</title> + <figure id="ChWorkGoToPacketDialog"> + <title>The "Go To Packet" dialog box</title> + <graphic entityref="EtherealGoToPacket" format="PNG"/> + </figure> + <para> + This dialog box will let you enter a packet number. When you press + <command>OK</command>, Ethereal will jump to that packet. + </para> + </section> + <section><title>The "Go to Corresponding Packet" command</title> + <para> + If a protocol field is selected, which points to another packet in the + capture file, this command will jump to that packet. + </para> + <note><title>Note!</title> + <para> + As these protocol fields now work like links (just as in your + Web browser), it's easier simply to double-click on the field to jump + to the corresponding field. + </para> + </note> + </section> + <section><title>The "Go to First Packet" command</title> + <para> + This command will simply jump to the first packet displayed. + </para> + </section> + <section><title>The "Go to Last Packet" command</title> + <para> + This command will simply jump to the last packet displayed. + </para> + </section> + </section> + + <section id="ChWorkMarkPacketSection"><title>Marking packets</title> + <para> + You can mark packets in the "Packet List" pane. A marked packet will + be shown with black background, regardless of the coloring rules set. + Marking a packet can be useful to find it later while analyzing in a large + capture file. + </para> + <warning><title>Warning!</title> + <para> + The packet marks are not stored in the capture file or anywhere else, + so all packet marks will be lost if you close the capture file. + </para> + </warning> + <para> + You can use packet marking to control the output of packets when + saving/exporting/printing. To do so, an option in the packet range is + available, see <xref linkend="ChIOPacketRangeSection"/>. + </para> + <para> + There are three functions to manipulate the marked state of a packet: + <itemizedlist> + <listitem> + <para> + <command>Mark packet</command> toggle the marked state of a single packet. + </para> + </listitem> + <listitem> + <para> + <command>Mark all packets</command> set the mark state of all packets. + </para> + </listitem> + <listitem> + <para> + <command>Unmark all packets</command> reset the mark state of all packets. + </para> + </listitem> + </itemizedlist> + These mark function are available from the "Edit" menu, and the "Mark packet" + function is also available from the pop-up menu of the "Packet List" pane. + </para> + </section> + + <section id="ChWorkTimeFormatsSection"><title>Time display formats and time + references</title> + <para> + While packets are captured, each packet is timestamped. These timestamps + will be saved to the capture file, so they will be available for later + analysis. + </para> + <para> + When the packets are displayed, the presentation of these timestamps can + be chosen by the user. There are four presentation formats available: + <itemizedlist> + <listitem><para><command>Time of Day</command>, e.g. 20:02:48.863096 + The absolute time of the day when the packet was captured.</para> + </listitem> + <listitem><para><command>Date and Time of Day</command>, e.g. 2004-06-22 20:02:48.863096 + The absolute date and time of the day when the packet was captured.</para> + </listitem> + <listitem><para><command>Seconds Since Beginning of Capture</command>, e.g. 123.299139 + The time relative to the start of the capture file or the first + "Time Reference" before this packet (see <xref + linkend="ChWorkTimeReferencePacketSection"/>).</para> + </listitem> + <listitem><para><command>Seconds Since Previous Packet</command>, e.g. 1.162423 + The time relative to the previous packet.</para> + </listitem> + </itemizedlist> + The time format can be selected from the View menu, see + <xref linkend="ChUseEtherealViewMenu"/>. + </para> + <para> + XXX - how is the GMT / localtime thing handled. + </para> + <section id="ChWorkTimeReferencePacketSection"> + <title>Packet time referencing</title> + <para> + The user can set time references to packets. A time reference is the + starting point for all subsequent packet time calculations. It will be + useful, if you want to see the time values relative to a special packet, + e.g. the start of a new request. It's possible to set multiple time + references in the capture file. + </para> + <warning><title>Warning!</title> + <para> + The time references will not be saved permanently and will be lost when + you close the capture file. + </para> + </warning> + <note><title>Note!</title> + <para> + Time referencing will only be useful, if the time display format is set to + "Seconds Since Beginning of Capture". If one of the other time display + formats are used, time referencing will have no effect (and will make no + sense either). + </para> + </note> + <para> + To work with time references, choose one of the "Time Reference" items + in the "Edit" menu , see <xref linkend="ChUseEditMenuSection"/>, or from + the pop-up menu of the "Packet List" pane. + </para> + <itemizedlist> + <listitem><para><command>Set Time Reference (toggle)</command> + Toggles the time reference state of the currently selected + packet to on or off.</para> + </listitem> + <listitem><para><command>Find Next</command> + Find the next time referenced packet in the "Packet List" pane. + </para> + </listitem> + <listitem><para><command>Find Previous</command> + Find the previous time referenced packet in the "Packet List" + pane. + </para> + </listitem> + </itemizedlist> + <para> + <figure id="ChWorkTimeReference"> + <title>Ethereal showing a time referenced packet</title> + <graphic entityref="EtherealTimeReference" format="PNG"/> + </figure> + </para> + <para> + A time referenced packet will be marked with the string *REF* in the Time + column (see packet number 10). All subsequent packets will show the time + since the last time reference. + </para> + </section> + </section> + +</chapter> +<!-- End of EUG Chapter Work --> + diff --git a/docbook/eug_src/EUG_meta_info.xml b/docbook/eug_src/EUG_meta_info.xml new file mode 100644 index 0000000000..62005e27d6 --- /dev/null +++ b/docbook/eug_src/EUG_meta_info.xml @@ -0,0 +1,38 @@ +<!-- $Id$ --> + +<bookinfo> + <title><inlinegraphic entityref="EtherealLogo" valign="middle" format="PNG"/> &DocumentTitle;</title> + <subtitle>&DocumentSubTitle;</subtitle> + <authorgroup> + <author> + <firstname>&AuthorFirstName;</firstname> + <surname>&AuthorSurname;</surname> + <affiliation><orgname>&AuthorOrgName;</orgname></affiliation> + </author> + <author> + <firstname>&AuthorFirstName2;</firstname> + <surname>&AuthorSurname2;</surname> + <affiliation><orgname>&AuthorOrgName2;</orgname></affiliation> + </author> + <author> + <firstname>&AuthorFirstName3;</firstname> + <surname>&AuthorSurname3;</surname> + <affiliation><orgname>&AuthorOrgName3;</orgname></affiliation> + </author> + </authorgroup> + <!-- <edition>&DocumentEdition;</edition> + <pubdate>&DocumentPubDate;</pubdate> --> + <copyright> + <year>&DocumentCopyrightYear;</year> + <holder>&DocumentCopyrightHolder1;</holder> + <holder>&DocumentCopyrightHolder2;</holder> + <holder>&DocumentCopyrightHolder3;</holder> + </copyright> + + <graphic scale="100" entityref="EtherealLogo" format="PNG"/> + + <legalnotice> + &DocumentLegalNotice; + </legalnotice> + +</bookinfo> diff --git a/docbook/eug_src/EUG_preface.xml b/docbook/eug_src/EUG_preface.xml new file mode 100644 index 0000000000..9f09ef4bc0 --- /dev/null +++ b/docbook/eug_src/EUG_preface.xml @@ -0,0 +1,170 @@ +<!-- $Id$ --> + +<preface id="Preface"> + <title>Preface</title> + <section id="PreForeword"> + <title>Foreword</title> + <para> + Ethereal is one of those programs that many network managers would love + to be able to use, but they are often prevented from getting what they + would like from Ethereal because of the lack of documentation. + </para> + <para> + This document is part of an effort by the Ethereal team to improve the + usability of Ethereal. + </para> + <para> + We hope that you find it useful, and look forward to your comments. + </para> + </section> + + <section id="PreAudience"> + <title>Who should read this document?</title> + <para> + The intended audience of this book is anyone using Ethereal. + </para> + <para> + This book will explain all the basics and also some of the advanced features + that Ethereal provides. As Ethereal has become a very complex program since + the early days, not every feature of Ethereal might be explained in this + book. + </para> + <para> + This book is not intended to explain network sniffing in general and it will + not provide details about specific network protocols. However, as this book + evolves in time (like Ethereal itself), this might change in the future. + </para> + <para> + By reading this book, you will learn how to install Ethereal, how to use the + basic elements of the graphical user interface (like the menu) and what's + behind some of the advanced features that are maybe not that obvious at first + sight. It will + hopefully guide you around some common problems that frequently appears for + new (and sometimes even advanced) users of Ethereal. + </para> + </section> + + <section id="PreAck"> + <title>Acknowledgements</title> + <para> + The authors would like to thank the whole Ethereal team for their + assistance. In particular, the authors would like to thank: + <itemizedlist> + <listitem> + <para> + Gerald Combs, for initiating the Ethereal project and funding to + do this documentation. + </para> + </listitem> + <listitem> + <para> + Guy Harris, for many helpful hints and a great deal of patience + in reviewing this document. + </para> + </listitem> + <listitem> + <para> + Gilbert Ramirez, for general encouragement and helpful hints along + the way. + </para> + </listitem> + </itemizedlist> + </para> + <para> + The authors would also like to thank the following people for their + helpful feedback on this document: + <itemizedlist> + <listitem> + <para> + Pat Eyler, for his suggestions on improving the example on + generating a backtrace. + </para> + </listitem> + <listitem> + <para> + Martin Regner, for his various suggestions and corrections. + </para> + </listitem> + <listitem> + <para> + Graeme Hewson, for a lot of grammatical corrections. + </para> + </listitem> + </itemizedlist> + </para> + <para> + The authors would like to acknowledge those man page and README authors + for the ethereal project from who sections of this document borrow heavily: + <itemizedlist> + <listitem> + <para> + Scott Renfro from whose <command>mergecap</command> man page + <xref linkend="AppToolsmergecap"/> is derived. + </para> + </listitem> + <listitem> + <para> + Ashok Narayanan from whose <command>text2pcap</command> man page + <xref linkend="AppToolstext2pcap"/> is derived. + </para> + </listitem> + <listitem> + <para> + Frank Singleton from whose <filename>README.idl2eth</filename> + <xref linkend="AppToolsidl2eth"/> is derived. + </para> + </listitem> + </itemizedlist> + </para> + </section> + + <section id="PreAbout"> + <title>About this document</title> + <para> + This book was originally developed by + <ulink url="mailto:&AuthorEmail;">Richard Sharpe</ulink> with + funds provided from the Ethereal Fund. It was updated by + <ulink url="mailto:&AuthorEmail2;">Ed Warnicke</ulink> and more recently + redesigned and updated by <ulink url="mailto:&AuthorEmail3;">Ulf + Lamping</ulink>. + </para> + <para> + It is written in DocBook/XML. + </para> + <para> + You will find some specially marked parts in this book: + </para> + <warning><title>This is a warning!</title> + <para> + You should pay attention to a warning, as otherwise data loss might occur. + </para> + </warning> + <note><title>This is a note!</title> + <para> + A note will point you to common mistakes and things that might not be + obvious. + </para> + </note> + <tip><title>This is a tip!</title> + <para> + Tips will be helpful for your everyday work using Ethereal. + </para> + </tip> + </section> + + <section id="PreDownload"> + <title>Where to get the latest copy of this document?</title> + <para> + The latest copy of this documentation can always be found at: + <ulink url="&EtherealUsersGuidePage;"/>. + </para> + </section> + + <section id="PreFeedback"> + <title>Providing feedback about this document</title> + <para> + Should you have any feedback about this document, please send them + to the authors through <ulink url="mailto:&EtherealDevMailList;">&EtherealDevMailList;</ulink>. + </para> + </section> +</preface> |