diff options
Diffstat (limited to 'docbook/wsug_src')
| -rw-r--r-- | docbook/wsug_src/EUG_app_files.xml | 460 | ||||
| -rw-r--r-- | docbook/wsug_src/EUG_app_howitworks.xml | 106 | ||||
| -rw-r--r-- | docbook/wsug_src/EUG_app_messages.xml | 101 | ||||
| -rw-r--r-- | docbook/wsug_src/EUG_app_protocols.xml | 15 | ||||
| -rw-r--r-- | docbook/wsug_src/EUG_app_tools.xml | 967 | ||||
| -rw-r--r-- | docbook/wsug_src/EUG_chapter_advanced.xml | 897 | ||||
| -rw-r--r-- | docbook/wsug_src/EUG_chapter_build_install.xml | 754 | ||||
| -rw-r--r-- | docbook/wsug_src/EUG_chapter_capture.xml | 1033 | ||||
| -rw-r--r-- | docbook/wsug_src/EUG_chapter_customize.xml | 827 | ||||
| -rw-r--r-- | docbook/wsug_src/EUG_chapter_introduction.xml | 614 | ||||
| -rw-r--r-- | docbook/wsug_src/EUG_chapter_io.xml | 875 | ||||
| -rw-r--r-- | docbook/wsug_src/EUG_chapter_statistics.xml | 508 | ||||
| -rw-r--r-- | docbook/wsug_src/EUG_chapter_troubleshoot.xml | 129 | ||||
| -rw-r--r-- | docbook/wsug_src/EUG_chapter_use.xml | 2063 | ||||
| -rw-r--r-- | docbook/wsug_src/EUG_chapter_work.xml | 1419 | ||||
| -rw-r--r-- | docbook/wsug_src/EUG_meta_info.xml | 38 | ||||
| -rw-r--r-- | docbook/wsug_src/EUG_preface.xml | 171 |
17 files changed, 10977 insertions, 0 deletions
diff --git a/docbook/wsug_src/EUG_app_files.xml b/docbook/wsug_src/EUG_app_files.xml new file mode 100644 index 0000000000..19ec579e27 --- /dev/null +++ b/docbook/wsug_src/EUG_app_files.xml @@ -0,0 +1,460 @@ +<!-- EUG Appendix Files --> +<!-- $Id$ --> + +<appendix id="AppFiles"> + <title>Configuration (and other) Files and Folders</title> + <para> + Ethereal uses a number of files and folders 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> + <tip><title>Tip</title> + <para>A list of the folders Ethereal actually uses can be found under the + <command>Folders</command> tab in the dialog box coming up, when you select + <command>About Ethereal</command> from the <command>Help</command> menu. + </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 and folders overview</title> + <tgroup cols="4"> + <colspec colnum="1" colwidth="72pt"/> + <colspec colnum="2" colwidth="80pt"/> + <colspec colnum="3" colwidth="80pt"/> + <thead> + <row> + <entry>File/Folder</entry> + <entry>Description</entry> + <entry>Unix/Linux folders</entry> + <entry>Windows folders</entry> + </row> + </thead> + <tbody> + <row> + <entry><command>preferences</command></entry> + <entry>Settings from the Preferences dialog box.</entry> + <entry>/etc/ethereal.conf, $HOME/.ethereal/preferences</entry> + <entry>%ETHEREAL%\ethereal.conf, %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>%ETHEREAL%\disabled_protos, %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>/etc/manuf</entry> + <entry>%ETHEREAL%\manuf</entry> + </row> + <row> + <entry><command>hosts</command></entry> + <entry>IPv4 and IPv6 name resolution.</entry> + <entry>$HOME/.ethereal/hosts</entry> + <entry>%APPDATA%\hosts</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/ethereal/plugins, + $HOME/.ethereal/plugins + </entry> + <entry>%ETHEREAL%\plugins\<version>, + %APPDATA%\Ethereal\plugins</entry> + </row> + <row> + <entry><command>temp</command></entry> + <entry>Temporary files.</entry> + <entry>Environment: TMPDIR</entry> + <entry>Environment: TMPDIR or TEMP</entry> + </row> + </tbody> + </tgroup> + </table> + <note><title>Windows folders</title> + <para> + %APPDATA% points to the personal configuration folder, typically + <filename>C:\Documents and Settings\<username>\Application Data</filename> + (for further details, have a look at <xref linkend="ChWindowsProfiles"/>), + %ETHEREAL% points to the Wireshark program folder, typically + <filename>C:\Program Files\Ethereal</filename> + </para> + </note> + <note><title>Unix/Linux folders</title> + <para> + The <filename>/etc</filename> folder is the global Ethereal configuration + folder. The folder actually used on your system + may vary, maybe something like: <filename>/usr/local/etc</filename>. + </para> + </note> + <para> + <variablelist> + <varlistentry> + <term><command>preferences/ethereal.conf</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 Wireshark 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 + addresses 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 Wireshark. + </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> + An example is: + <programlisting> +00:00:01 Xerox # XEROX CORPORATION + </programlisting> + </para> + <para> + The settings from this file are read in at program start and never + written by Wireshark. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><command>hosts</command></term> + <listitem> + <para> + Ethereal uses the files listed in <xref linkend="AppFilesTabFolders"/> + to translate IPv4 and IPv6 addresses into names. + </para> + <para> + This file has the same format as the usual /etc/hosts file in unix systems. + </para> + <para> + An example is: + <programlisting> +# Comments must be prepended by the # sign! +192.168.0.1 homeserver + </programlisting> + </para> + <para> + The settings from this file are read in at program start and never + written by Wireshark. + </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 Wireshark. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><command>plugins</command> folder</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> + <varlistentry> + <term><command>temp</command> folder</term> + <listitem> + <para> + If you start a new capture and don't specify a filename for it, + Ethereal uses this directory to place that file in, see + <xref linkend="ChCapCaptureFiles"/>. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + + <section id="ChWindowsFolder"><title>Windows folders</title> + <para> + Here you will find some details about the folders used in Wireshark + on different Windows versions. + </para> + <para> + As already mentioned, you can find the currently used folders in the + <command>About Ethereal</command> dialog. + </para> + + <section id="ChWindowsProfiles"><title>Windows profiles</title> + <para> + Windows uses some special directories to store user configuration files + in, named the user profile. This can be confusing, as the default directory location + changed from version to version and might also be different for english + and internationalized versions of windows. + </para> + <note><title>Note!</title> + <para> + If you upgraded to a new windows version, your profile might + be kept in the former location, so the defaults mentioned here might not + apply. + </para> + </note> + <para> + The following will try to guide + you to the right place where to look for Wiresharks profile data. + </para> + <para> + <variablelist> + <varlistentry> + <term><command>95/98/ME</command></term> + <listitem> + <para> + The default in Windows 95/98/ME is: all users work with the same profile, + which is located at: + <filename>C:\windows\Application Data\Ethereal</filename> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><command>98/ME (with enabled user profiles)</command></term> + <listitem> + <para> + In Windows 98 and ME you can enable separate user profiles. In that case, + something like: + <filename>C:\windows\Profiles\<username>\Application Data\Ethereal</filename> + is used. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><command>NT 4</command></term> + <listitem> + <para> + <filename>C:\WINNT\Profiles\<username>\Application Data\Ethereal</filename> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><command>2000/XP</command></term> + <listitem> + <para> + <filename>C:\Documents and Settings\<username>\Application Data</filename>, + "Documents and Settings" and "Application Data" might be internationalized. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </section> + + <section id="ChWindowsRoamingProfiles"> + <title>Windows NT/2000/XP roaming profiles</title> + <para> + The following will only be applicable if you are using roaming profiles. + This might be the case, if you work in a Windows domain environment + (used in huge company networks). The configurations of all + programs you use won't be saved on the local harddrive of the computer + you are currently working on, but on the domain server. + </para> + <para> + As Wireshark is using the correct places to store it's profile data, + your settings will travel with you, if you logon to a different computer + the next time. + </para> + <para> + There is an exception to this: The "Local Settings" folder in your profile + data (typically something like: + <filename>C:\Documents and Settings\<username>\Local Settings</filename>) + will not be transferred to the domain server. This is the default for + temporary capture files. + </para> + </section> + + <section id="ChWindowsTempFolder"> + <title>Windows temporary folder</title> + <para> + Ethereal uses the folder which is set by the TMPDIR or TEMP environment + variable. This variable will be set by the windows installer. + </para> + <para> + The default location for temporary files on NT 4 is just + <filename>C:\TEMP</filename>, and in 2000 the default location + is some directory under your profile directory but it might have + "Temporary Files" in the path name. + </para> + </section> + + </section> + +</appendix> +<!-- End of EUG Appendix Files --> diff --git a/docbook/wsug_src/EUG_app_howitworks.xml b/docbook/wsug_src/EUG_app_howitworks.xml new file mode 100644 index 0000000000..83e33beeff --- /dev/null +++ b/docbook/wsug_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/wsug_src/EUG_app_messages.xml b/docbook/wsug_src/EUG_app_messages.xml new file mode 100644 index 0000000000..a0631e7d2a --- /dev/null +++ b/docbook/wsug_src/EUG_app_messages.xml @@ -0,0 +1,101 @@ +<!-- EUG Appendix Messages --> +<!-- $Id$ --> + +<appendix id="AppMessages"> + <title>Ethereal Messages</title> + <para> + Ethereal provides you with additional information generated out of + the plain packet data or it may need to indicate dissection problems. + Messages generated by Wireshark are usually placed in [] parentheses. + </para> + <section id="AppMessagesList"><title>Packet List Messages</title> + <para> + These messages might appear in the packet list. + </para> + <section><title>[Malformed Packet]</title> + <para> + Malformed packet means that the protocol dissector can't work out the + contents of the packet any further. This can have various reasons: + <itemizedlist> + <listitem> + <para> + <command>Wrong dissector</command> + Ethereal errorneously has chosen the wrong protocol dissector for + this packet. This will happen e.g. if you are using a protocol + not on it's well known TCP or UDP port. You may try Analyze|Decode As + to circumvent this problem. + </para> + </listitem> + <listitem> + <para> + <command>Packet not reassembled</command> + The packet is longer than a single frame and it is not reassembled, + see <xref linkend="ChAdvReassemblySection"/> for further details. + </para> + </listitem> + <listitem> + <para> + <command>Packet is malformed</command> + The packet is actually wrong (malformed), meaning that a part of the + packet is just not as expected (not following the protocol + specifications). + </para> + </listitem> + <listitem> + <para> + <command>Dissector is buggy</command> + The corresponding protocol dissector is simply buggy or still + incomplete. + </para> + </listitem> + </itemizedlist> + </para> + <para> + Any of the above is possible. You'll have to look into the specific + situation to determine what it is. + You could disable the dissector by disabling the + protocol on the Analyze menu and check how Ethereal displays the packet + then. You could (if it's TCP) enable reassembly for TCP and the specific + dissector (if possible) in the Edit|Preferences menu. You could check the + packet contents yourself by reading the packet bytes and comparing it to + the protocol specification. This could reveil a dissector bug. Or you + could find out that the packet is indeed wrong. + </para> + </section> + <section><title>[Packet size limited during capture]</title> + <para> + The packet size was limited during capture, see "Limit each packet to n + bytes" at the <xref linkend="ChCapCaptureOptions"/>. + While dissecting, the current protocol + dissector was simply running out of packet bytes and had to give up. + There's nothing else you can do now, except to repeat the whole capture + process again with a higher (or no) packet size limitation. + </para> + </section> + </section> + + <section id="AppMessagesDetails"><title>Packet Details Messages</title> + <para> + These messages might appear in the packet details. + </para> + <section><title>[Response in frame: 123]</title> + <para> + The current packet is the request of a detected request/response pair. + You can directly jump to the corresponding response packet just + by double clicking on this message. + </para> + </section> + <section><title>[Request in frame: 123]</title> + <para> + Same as "Response in frame: 123" above, but the other way round. + </para> + </section> + <section><title>[Time from request: 0.123 seconds]</title> + <para> + The time between the request and the response packets. + </para> + </section> + </section> + +</appendix> +<!-- End of EUG Appendix Messages --> diff --git a/docbook/wsug_src/EUG_app_protocols.xml b/docbook/wsug_src/EUG_app_protocols.xml new file mode 100644 index 0000000000..4e8a9a787c --- /dev/null +++ b/docbook/wsug_src/EUG_app_protocols.xml @@ -0,0 +1,15 @@ +<!-- 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> +</appendix> +<!-- End of EUG Appendix Protocols --> diff --git a/docbook/wsug_src/EUG_app_tools.xml b/docbook/wsug_src/EUG_app_tools.xml new file mode 100644 index 0000000000..4c9364dac4 --- /dev/null +++ b/docbook/wsug_src/EUG_app_tools.xml @@ -0,0 +1,967 @@ +<!-- EUG Appendix Tools --> + +<!-- $Id$ --> + +<appendix id="AppTools"> + <title>Related command line tools</title> + + <section id="AppToolsIntroduction"> + <title>Introduction</title> + <para> + Beside the Wireshark 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><command>tcpdump</command>: 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 Wireshark 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><command>tethereal</command>: 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="AppToolscapinfos"> + <title><command>capinfos</command>: Print information about capture files + </title> + <para> + Included with Wireshark is a small utility called + <command>capinfos</command>, which is a command-line utility to + print information about binary capture files. + </para> + <para> + <example id="AppToolscapinfosEx"> + <title>Help information available from capinfos</title> + <programlisting> +$ capinfos -h +Usage: capinfos [-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><command>editcap</command>: Edit capture files</title> + <para> + Included with Wireshark 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>] [-E <probability>] + [-F <capture type>]> [-s <snaplen>] [-t <time adjustment>] + <infile> <outfile> [ <record#>[-<record#>] ... ] + where + -E <probability> specifies the probability (between 0 and 1) + that a particular byte will will have an error. + -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 + nettl - HP-UX nettl trace + visual - Visual Networks traffic capture + 5views - Accellent 5Views capture + niobserverv9 - Network Instruments Observer version 9 + default is libpcap + -h produces this help listing. + -r specifies that the records specified should be kept, not deleted, + default is to delete + -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 + -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-radiotap - IEEE 802.11 plus radiotap 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 + raw-icmp-nettl - Raw ICMP with nettl headers + raw-icmpv6-nettl - Raw ICMPv6 with nettl headers + gprs-llc - GPRS LLC + juniper-atm1 - Juniper ATM1 + juniper-atm2 - Juniper ATM2 + redback - Redback SmartEdge + rawip-nettl - Raw IP with nettl headers + ether-nettl - Ethernet with nettl headers + tr-nettl - Token Ring with nettl headers + fddi-nettl - FDDI with nettl headers + unknown-nettl - Unknown link-layer type with nettl headers + mtp2-with-phdr - MTP2 with pseudoheader + juniper-pppoe - Juniper PPPoE + gcom-tie1 - GCOM TIE1 + gcom-serial - GCOM Serial + x25-nettl - X25 with nettl headers + default is the same as the input file + -v specifies verbose operation, default is silent + + 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><command>mergecap</command>: + Merging multiple capture files into one + </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><command>text2pcap</command>: Converting ASCII hexdumps to network + captures + </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 with multiple 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><command>idl2eth</command>: + Creating dissectors from Corba IDL files + </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 procedure: + </para> + <orderedlist> + <title> + Procedure 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 don't 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/wsug_src/EUG_chapter_advanced.xml b/docbook/wsug_src/EUG_chapter_advanced.xml new file mode 100644 index 0000000000..db04444142 --- /dev/null +++ b/docbook/wsug_src/EUG_chapter_advanced.xml @@ -0,0 +1,897 @@ +<!-- EUG Chapter Advanced --> + +<!-- $Id: --> + +<chapter id="ChapterAdvanced"> + <title>Advanced Topics</title> + + <section id="ChAdvIntroduction"><title>Introduction</title> + <para> + In this chapter some of the advanced features of Ethereal will be described. + </para> + </section> + + <section id="ChAdvFollowTCPSection"><title>Following TCP streams</title> + <para> + If you are working with TCP based protocols it can be very helpful + to see the data from a TCP stream in the way 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. + Maybe you just need a display filter to show only the packets of that + TCP 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 packet list of the stream/connection + you are interested in and then select the Follow TCP Stream menu item + from the Wireshark Tools menu (or use the context menu in the packet + list). + Ethereal will set an appropriate display filter and pop up a dialog + box with all the data from the TCP stream laid out in order, + as shown in <xref linkend="ChAdvFollowStream"/>. + </para> + <note> + <title>Note!</title> + <para> + It is worthwhile noting that Follow TCP Stream installs a display filter + to select all the packets in the TCP stream you have selected. + </para> + </note> + <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> + The stream content is displayed in the same sequence as it appeared on + the network. + Traffic from A to B is marked in red, while traffic from B to A is + marked in blue. + If you like, you can change these colors in the Edit/Preferences + "Colors" page. + </para> + <para> + None printable characters will be replaced by dots. + XXX - What about line wrapping (maximum line length) and CRNL conversions? + </para> + <para> + The stream content won't be updated while doing a live capture. + To get the latest content you'll have to reopen the dialog. + </para> + <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, leaving the current + display filter in effect. + </para> + </listitem> + </orderedlist> + </para> + <para> + You can choose to view the data in one of the following formats: + <orderedlist> + <listitem> + <para> + <command>ASCII</command>. In this view you see the data from + each direction in ASCII. Obviously best for ASCII based protocols, + e.g. HTTP. + </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. + This will require a lot of screen space and is best used with + binary protocols. + </para> + </listitem> + <listitem> + <para> + <command>C Arrays</command>. This allows you to import the stream data + into your own C program. + </para> + </listitem> + <listitem> + <para> + <command>Raw</command>. This allows you to load the unaltered stream + data into a different program for further examination. + The display will look the same as the ASCII setting, but "Save As" + will result in a binary file. + </para> + </listitem> + </orderedlist> + </para> + </section> + </section> + + <section id="ChAdvTimestamps"><title>Time Stamps</title> + <para> + Time stamps, their precisions and all that can be quite + confusing, this section will provide you with information what's going + on while Ethereal processes time stamps. + </para> + <para> + While packets are captured, each packet is time stamped as it comes in. + These time stamps will be saved to the capture file, so they also will be + available for (later) analysis. + </para> + <para> + So where do these time stamps come from? + While capturing, Ethereal gets the time stamps from the libpcap (WinPcap) + library, which in turn get's them from the operating system kernel. + If the capture data is loaded from a capture file, Ethereal obviously gets + the data from that file. + </para> + <section><title>Ethereal internals</title> + <para> + The internal format that Ethereal uses to keep a packet time stamp consists + of the date (in days since 1.1.1970) and the time of day (in nanoseconds + since midnight). You can adjust the way Ethereal displays the time stamp data + in the packet list, see the "Time Display Format" item in the + <xref linkend="ChUseViewMenuSection"/> for details. + </para> + <para> + While reading or writing capture files, Ethereal converts the time stamp + data between the capture file format and the internal format as required. + </para> + <para> + While capturing, Ethereal uses the libpcap (WinPcap) capture library which + supports microsecond resolution. Unless you are working with specialized + capturing hardware, this resolution should be adequate. + </para> + </section> + <section><title>Capture file formats</title> + <para> + Every capture file format that Ethereal knows support time stamps. + The time stamp precision + supported by a specific capture file format differs widely and varies + from one second "0" to one nanosecond "0.123456789". + Most file formats store the time stamps with a fixed precision + (e.g. microseconds), while some file formats are even capable to store the + time stamp precision itself (whatever the benefit may be). + </para> + <para> + The common libpcap capture file format that is used by Wireshark (and a + lot of other tools) supports a fixed microsecond resolution "0.123456" + only. + </para> + <note> + <title>Note!</title> + <para> + Writing data into a capture file format that doesn't provide + the capability to store the actual precision will lead to loss of information. + Example: If you load a capture file with nanosecond resolution and + store the capture data to a libpcap file (with microsecond resolution) + Ethereal obviously must reduce the precision from nanosecond to microsecond. + </para> + </note> + </section> + <section><title>Accuracy</title> + <para> + It's often asked: "Which time stamp accuracy is provided by Wireshark?". + Well, Ethereal doesn't create any time stamps itself but simply get's them + from "somewhere else" and displays them. So accuracy will depend on the + capture system (operating system, performance, ...) that you use. + Because of this, the above question is difficult to answer in a + general way. + <note> + <title>Note!</title> + <para> + USB connected network adapters often provide a very bad time stamp + accuracy. The incoming packets have to take "a long and winding + road" to travel through the USB cable until they actually reach the + kernel. As the incoming packets are time stamped when they are processed + by the kernel, this time stamping mechanism becomes very inaccurate. + </para> + <para> + Conclusion: don't use USB connected NIC's when you need precise + time stamp accuracy! (XXX - are there any such NIC's that stamps already + on the USB hardware?) + </para> + </note> + </para> + </section> + </section> + + <section id="ChAdvTimezones"><title>Time Zones</title> + <para> + If you travel across the planet, time zones can be confusing. If you get a + capture file from somewhere around the world time zones can even be a lot + more confusing ;-) + </para> + <para> + First of all, there are two reasons why you may not need to think about + time zones at all: + <itemizedlist> + <listitem> + <para> + You are only interested in the time differences between the packet + time stamps and don't need to know the exact date and time of the + captured packets (which is often the case). + </para> + </listitem> + <listitem> + <para> + You don't get capture files from different time zones than your own, + so there are simply no time zone problems. For example: everyone in + your team is working in the same time zone than yourself. + </para> + </listitem> + </itemizedlist> + </para> + <sidebar><title>What are time zones?</title> + <para> + People expect that the time reflects the sunset. Dawn should be in the + morning maybe around 06:00 and dusk in the evening maybe at 20:00. + These times will obviously vary depending on the season. + It would be very confusing if everyone on earth would use the same + global time as this would correspond to the sunset only at a small part + of the world. + </para> + <para> + For that reason, the earth is split into several different time zones, + each zone with a local time that corresponds to the local sunset. + </para> + <para> + The time zone's base time is UTC (Coordinated Universal Time) or Zulu + Time (military and aviation). The older term GMT (Greenwich Mean Time) + shouldn't be used as it is slightly incorrect (up to 0.9 seconds + difference to UTC). + The UTC base time equals to 0 (based at Greenwich, England) and all + time zones have an offset to UTC between -12 to +14 hours! + </para> + <para> + For example: If you live in + Berlin you are in a time zone one hour earlier than UTC, so you are in + time zone "+1" (time difference in hours compared to UTC). If it's + 3 o'clock in Berlin it's 2 o'clock in UTC "at the same moment". + </para> + <para> + Be aware that at a few places on earth don't use time zones with even + hour offsets (e.g. New Delhi uses UTC+05:30)! + </para> + <para> + Further information can be found at: + <ulink url="&WikipediaTimezone;">&WikipediaTimezone;</ulink> and + <ulink url="&WikipediaUTC;">&WikipediaUTC;</ulink>. + </para> + + </sidebar> + <sidebar><title>What is daylight saving time (DST)?</title> + <para> + Daylight Saving Time (DST), also known as Summer Time, is intended to + "save" some daylight during the summer months. + To do this, a lot of countries (but not all!) add an DST hour to the + already existing UTC offset. + So you may need to take another hour (or in very rare cases even two + hours!) difference into your "time zone calculations". + </para> + <para> + Unfortunately, the date at which DST actually takes effect is different + throughout the world. You may also note, that the northern and southern + hemispheres have opposite DST's (e.g. while it's summer in Europe it's + winter in Australia). + </para> + <para> + Keep in mind: UTC remains the same all year around, regardless of DST! + </para> + <para> + Further information can be found at: + <ulink url="&WikipediaDaylightSaving;">&WikipediaDaylightSaving;</ulink>. + </para> + </sidebar> + <para> + Further time zone and DST information can be found at: + <ulink url="&TimezoneGMTSite;">&TimezoneGMTSite;</ulink> and + <ulink url="&TimezoneWorldClockSite;">&TimezoneWorldClockSite;</ulink>. + </para> + <section><title>Set your computer's time correct!</title> + <para> + If you work with people around the world, it's very helpful to set your + computer's time and time zone right. + </para> + <para> + You should set your computers time and time zone in the correct sequence: + <orderedlist> + <listitem> + <para> + Set your time zone to your current location + </para> + </listitem> + <listitem> + <para> + Set your computer's clock to the local time + </para> + </listitem> + </orderedlist> + This way you will tell your computer both the local time and also the time + offset to UTC. + <tip><title>Tip!</title> + <para> + If you travel around the world, it's an often made mistake to adjust the + hours of your computer clock to the local time. Don't adjust the + hours but your time zone setting instead! For your computer, the time is + essentially the same as before, you are simply in a different time zone + with a different local time! + </para> + </tip> + <tip><title>Tip!</title> + <para> + You can use the Network Time Protocol (NTP) to automatically adjust your + computer to the correct time, by synchronizing it to internet NTP clock + servers. NTP clients are available for all operating systems that + Ethereal supports (and for a lot more), for examples see: + <ulink url="&NTPSite;">&NTPSite;</ulink>. + </para> + </tip> + </para> + </section> + <section><title>Ethereal and Time Zones</title> + <para> + So what's the relationship between Ethereal and time zones anyway? + </para> + <para> + Ethereal's native capture file format (libpcap format), and some + other capture file formats, such as the Windows Sniffer, + EtherPeek, AiroPeek, and Sun snoop formats, save the arrival + time of packets as UTC values. + UN*X systems, and "Windows NT based" systems (Windows NT 4.0, + Windows 2000, Windows XP, Windows Server 2003, Windows Vista) + represent time internally as UTC. + When Wireshark is capturing, no conversion is necessary. + However, if the system time zone is not set + correctly, the system's UTC time might not be correctly set even + if the system clock appears to display correct local time. + "Windows 9x based" systems (Windows 95, Windows 98, Windows Me) + represent time internally as local time. + When capturing, WinPcap has to convert the time to UTC before + supplying it to Ethereal. + If the system's time zone is not set correctly, that conversion will + not be done correctly. + </para> + <para> + Other capture file formats, such as the Microsoft Network + Monitor, DOS-based Sniffer, and Network Instruments Observer + formats, save the arrival time of packets as local time values. + </para> + <para> + Internally to Ethereal, time stamps are represented in UTC; this + means that, when reading capture files that save the arrival + time of packets as local time values, Ethereal must convert + those local time values to UTC values. + </para> + <para> + Ethereal in turn will display the time stamps always in local + time. The displaying computer will convert them from UTC to + local time and displays this (local) time. For capture files + saving the arrival time of packets as UTC values, this means + that the arrival time will be displayed as the local time in + your time zone, which might not be the same as the arrival time + in the time zone in which the packet was captured. For capture + files saving the arrival time of packets as local time values, + the conversion to UTC will be done using your time zone's offset + from UTC and DST rules, which means the conversion will not be + done correctly; the conversion back to local time for display + might undo this correctly, in which case the arrival time will + be displayed as the arrival time in which the packet was + captured. + </para> + <para> + <table id="ChAdvTabTimezones" frame="none"> + <title>Time zone examples for UTC arrival times (without DST)</title> + <tgroup cols="7"> +<!-- <colspec colnum="1" colwidth="72pt"/> + <colspec colnum="2" colwidth="80pt"/> + <colspec colnum="3" colwidth="80pt"/>--> + <thead> + <row> + <entry></entry> + <entry>Los Angeles</entry> + <entry>New York</entry> + <entry>Madrid</entry> + <entry>London</entry> + <entry>Berlin</entry> + <entry>Tokyo</entry> + </row> + </thead> + <tbody> + <row> + <entry><command>Capture File (UTC)</command></entry> + <entry>10:00</entry> + <entry>10:00</entry> + <entry>10:00</entry> + <entry>10:00</entry> + <entry>10:00</entry> + <entry>10:00</entry> + </row> + <row> + <entry><command>Local Offset to UTC</command></entry> + <entry>-8</entry> + <entry>-5</entry> + <entry>-1</entry> + <entry>0</entry> + <entry>+1</entry> + <entry>+9</entry> + </row> + <row> + <entry><command>Displayed Time (Local Time)</command></entry> + <entry>02:00</entry> + <entry>05:00</entry> + <entry>09:00</entry> + <entry>10:00</entry> + <entry>11:00</entry> + <entry>19:00</entry> + </row> + </tbody> + </tgroup> + </table> + </para> + <para> + An example: + Let's assume that someone in Los Angeles captured a packet with + Ethereal at exactly 2 o'clock local time and sents you this + capture file. The capture file's time stamp will be represented + in UTC as 10 o'clock. You are located in Berlin and will see 11 + o'clock on your Ethereal display. + </para> + <para> + Now you have a phone call, video conference or internet meeting with that + one to talk about that capture file. + As you are both looking at the displayed time on your local computers, + the one in Los Angeles still sees 2 o'clock but you in Berlin will see + 11 o'clock. The time displays are different as both Ethereal displays + will show the (different) local times at the same point in time. + </para> + <para> + <command>Conclusion</command>: You may not bother about the date/time + of the time stamp you currently look at, unless you must make sure that + the date/time is as expected. + So, if you get a capture file from a different time zone and/or DST, you'll + have to find out the time zone/DST difference between the two local times + and "mentally adjust" the time stamps accordingly. + In any case, make sure that every computer in question has the correct + time and time zone setting. + </para> + </section> + </section> + + <section id="ChAdvReassemblySection"><title>Packet Reassembling</title> + <section><title>What is it?</title> + <para> + Network protocols often need 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 chunk boundaries + itself and (if required) spreading the data over multiple packets. + It obviously also needs a mechanism to find back the chunk boundaries on + the receiving side. + </para> + <tip><title>Tip!</title> + <para> + Ethereal calls this mechanism reassembling, although a specific protocol + specification might use a different term for this (e.g. desegmentation, + defragmentation, ...). + </para> + </tip> + </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 these 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 + (for information about this pane, see <xref + linkend="ChUsePacketBytesPaneSection"/>). + </para> + <para> + <figure id="ChAdvEtherealBytesPaneTabs"> + <title>The "Packet Bytes" pane with a reassembled tab</title> + <graphic entityref="EtherealBytesPaneTabs" format="PNG"/> + </figure> + </para> + + <note><title>Note!</title> + <para> + Reassembling might take place at 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> + An example: + 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> + <para> + Reassembling is enabled in the preferences by default. The defaults + were changed from disabled to enabled in September 2005. If you created + your preference settings before this date, you might look if reassembling + is actually enabled, as it can be extremely helpful while analyzing + network packets. + </para> + <para> + The enabling or disabling of the reassemble settings 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 + 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> + The tooltip of the higher level protocol setting will note you if and + which lower level protocol setting has to be considered too. + </para> + </section> + </section> + + <section id="ChAdvNameResolutionSection"><title>Name Resolution</title> + <para> + Name resolution tries to resolve some of the numerical address values into + a human readable format. There are two possible ways to do this + conversations, depending on the resolution to be done: calling + system/network services (like the gethostname function) and/or evaluate + from Ethereal specific configuration files. + For details about the configuration files Ethereal uses for name + resolution and alike, see <xref linkend="AppFiles"/>. + </para> + <para> + The name resolution feature can be en-/disabled separately for the + protocol layers of the following sections. + </para> + + <section><title>Name Resolution drawbacks</title> + <para> + Name resolution can be invaluable while working with Ethereal and may + save you even hours of work. Unfortunately, it also has it's drawbacks. + </para> + <itemizedlist> + <listitem> + <para> + <command>Name resolution will often fail.</command> The name to be + resolved might simply be unknown by the name servers asked or the servers + are just not available and the name is also not found in Wireshark's + configuration files. + </para> + </listitem> + <listitem> + <para> + <command>The resolved names are not stored in the capture file or + somewhere else.</command> + So the resolved names might not be available if you open the capture file + later or on a different machine. + Each time you open a capture file it may look "slightly different", + maybe simply because you can't connect a name server (which you could + connect before). + </para> + </listitem> + <listitem> + <para> + <command>DNS may add additional packets to your capture file.</command> + You may see packets to/from your machine in your capture file, which are + caused by name resolution network services of the machine Ethereal + captures from. + XXX - are there any other such packets than DNS ones? + </para> + </listitem> + <listitem> + <para> + <command>Resolved DNS names are cached by Wireshark.</command> + This is required for acceptable performance. + However, if the name resolution information + should change while Wireshark is running, + Ethereal won't notice a change to the name resolution information once + it's get cached. If this information changes while Wireshark is running, + e.g. a new DHCP lease takes effect, Ethereal won't notice it. + XXX - is this true for all or only for DNS info? + </para> + </listitem> + </itemizedlist> + <tip><title>Tip!</title> + <para> + The name resolution in the packet list is done while the list is filled. + If a name could be resolved after a packet was added to the list, that + former entry won't be changed. As the name resolution results are cached, + you can use "View/Reload" to rebuild the packet list, this time with the + correctly resolved names. However, this isn't possible while a capture is + in progress. + </para> + </tip> + </section> + + <section><title>Ethernet name resolution (MAC layer)</title> + <para> + Try to resolve an Ethernet MAC address (e.g. 00:09:5b:01:02:03) to + something more "human readable". + </para> + <para><command>ARP name resolution (system service)</command> + Ethereal will ask the operating system to 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 codes (ethers file)</command> + If the ARP name resolution failed, Ethereal tries to convert the ethernet + address to a known device name, which has been assigned by the user using + an ethers file (e.g. 00:09:5b:01:02:03 -> homerouter). + </para> + <para><command>Ethernet manufacturer codes (manuf file)</command> + If both ARP and ethers didn't returned a result, Ethereal tries to convert + the first 3 bytes of an ethernet address to an abbreviated manufacturer name, + which has been assigned by the IEC + (e.g. 00:09:5b:01:02:03 -> Netgear_01:02:03). + </para> + </section> + + <section><title>IP name resolution (network layer)</title> + <para> + Try to resolve an IP address (e.g. 65.208.228.223) to + something more "human readable". + </para> + <para><command>DNS/ADNS name resolution (system/library service)</command> + Ethereal will ask the operating system (or the ADNS library), + to convert an IP address to the hostname associated with it + (e.g. 65.208.228.223 -> www.ethereal.com). The DNS service is using + synchronous calls to the DNS server. So Ethereal will stop responding + until a response to a DNS request is returned. If possible, you might + consider using the ADNS library (which won't wait for a network response). + </para> + <warning> + <title>Warning!</title> + <para> + Enabling network name resolution when your name server is + unavailable may significantly slow down Ethereal while it waits + for all of the name server requests to time out. Use ADNS in that + case. + </para> + </warning> + <para> + <command>DNS vs. ADNS</command> + here's a short comparison: Both mechanisms are + used to convert an IP address to some human readable (domain) name. The + usual DNS call gethostname() will try to convert the address to a name. + To do this, it will first ask the systems hosts file (e.g. /etc/hosts) + if it finds a matching entry. If that fails, it will ask the configured + DNS server(s) about the name. + </para> + <para> + So the real difference between DNS and ADNS comes when the system has + to wait for the DNS server about a name resolution. + The system call gethostname() will wait until a name is resolved or an + error occurs. + If the DNS server is unavailable, this might take quite + a while (several seconds). + The ADNS service will work a bit differently. + It will also ask the DNS server, but it won't wait for the answer. + It will just return to Ethereal in a very short amount of time. + The actual (and the following) address fields won't show the resolved + name until the ADNS call returned. As mentioned above, the values get + cached, so you can use View/Reload to "update" these fields to show the + resolved values. + </para> + <para><command>hosts name resolution (hosts file)</command> + If DNS name resolution failed, Ethereal will try to convert an IP address + to the hostname associated with it, using an hosts file provided by the + user (e.g. 65.208.228.223 -> www.ethereal.com). + </para> + </section> + + <section><title>IPX name resolution (network layer)</title> + <para><command>ipxnet name resolution (ipxnets file)</command> + XXX - add ipxnets name resolution explanation. + </para> + </section> + + <section><title>TCP/UDP port name resolution (transport layer)</title> + <para> + Try to resolve a TCP/UDP port (e.g. 80) to + something more "human readable". + </para> + <para><command>TCP/UDP port conversion (system service)</command> + Ethereal will ask the operating system to convert a TCP or UDP port to + its well known name (e.g. 80 -> http). + </para> + <para> + XXX - mention the role of the /etc/services file + (but don't forget the files and folders section)! + </para> + </section> + </section> + + <section id="ChAdvChecksums"><title>Checksums</title> + <para> + Several network protocols use checksums to ensure data integrity. + </para> + <tip><title>Tip!</title> + <para> + Applying checksums as described here is also known as + <command>redundancy check</command>. + </para> + </tip> + <sidebar><title>What are checksums for?</title> + <para> + Checksums are used to ensure the integrity of data portions for data + transmission or storage. + A checksum is basically a calculated summary of such a data portion. + </para> + <para> + Network data transmissions often produce errors, such as toggled, missing + or duplicated bits. + As a result, the data received might not be identical to the data + transmitted, which is obviously a bad thing. + </para> + <para> + Because of these transmission errors, network protocols very often use + checksums to detect such errors. + The transmitter will calculate a checksum of the data and transmits the + data together with the checksum. + The receiver will calculate the checksum of the received data with the same + algorithm as the transmitter. + If the received and calculated checksums don't match a transmission error + has occured. + </para> + <para> + Some checksum algorithms are able to recover (simple) errors by + calculating where the expected error must be and repairing it. + </para> + <para> + If there are errors that cannot be recovered, the receiving side throws + away the packet. Depending on the network protocol, this data loss is + simply ignored or the sending side needs to detect this loss somehow and + retransmits the required packet(s). + </para> + <para> + Using a checksum drastically reduces the number of undetected transmission + errors. However, the usual checksum algorithms cannot guarantee an error + detection of 100%, so a very small number of transmission errors may + remain undetected. + </para> + <para> + There are several different kinds of checksum algorithms, an example of + an often used checksum algorithm is CRC32. + The checksum algorithm actually chosen for a specific network protocol + will depend on the expected error rate of the network medium, the + importance of error detection, the processor load to perform the + calculation, the performance needed and many other things. + </para> + <para> + Further information about checksums can be found at: + <ulink url="http://en.wikipedia.org/wiki/Checksum"/>. + </para> + </sidebar> + <section><title>Ethereal checksum validation</title> + <para> + Ethereal will validate the checksums of several potocols, e.g.: IP, TCP, ... + </para> + <para> + It will do the same calculation as a "normal receiver" would do, + and shows the checksum fields in the packet details with a comment, e.g.: + [correct], [invalid, must be 0x12345678] or alike. + </para> + <para> + Checksum validation can be switched off for various protocols in the + Ethereal protocol preferences, e.g. to (very slightly) increase + performance. + </para> + <para> + If the checksum validation is enabled and it detected an invalid checksum, + features like packet reassembling won't be processed. + This is avoided as incorrect connection data could "confuse" the internal + database. + </para> + </section> + + <section><title>Checksum offloading</title> + <para> + The checksum calculation might be done by the network driver, protocol + driver or even in hardware. + </para> + <para> + For example: The Ethernet transmitting hardware calculates the + Ethernet CRC32 checksum and the receiving hardware validates this + checksum. + If the received checksum is wrong Ethereal won't even see the packet, + as the Ethernet hardware internally throws away the packet. + </para> + <para> + Higher level checksums are "traditionally" calculated by the protocol + implementation and the completed packet is then handed over to the + hardware. + </para> + <para> + Recent network hardware can perform advanced features such as IP checksum + calculation, also known as checksum offloading. + The network driver won't calculate the checksum itself but simply hand + over an empty (zero or garbage filled) checksum field to the hardware. + </para> + <note><title>Note!</title> + <para> + Checksum offloading often causes confusion as the network packets to be + transmitted are handed over to Ethereal before the checksums are actually + calculated. + Ethereal gets these "empty" checksums and displays them as + invalid, even though the packets will contain valid checksums when they + leave the network hardware later. + </para> + </note> + <para> + Checksum offloading can be confusing and having a lot of [invalid] + messages on the screen can be quite annoying. + As mentioned above, invalid checksums may lead to unreassembled packets, + making the analysis of the packet data much harder. + </para> + <para> + You can do two things to avoid this checksum offloading problem: + <itemizedlist> + <listitem> + <para> + Turn off the checksum offloading in the network driver, if this option is + available. + </para> + </listitem> + <listitem> + <para> + Turn off checksum validation of the specific protocol in the Wireshark + preferences. + </para> + </listitem> + </itemizedlist> + </para> + </section> + </section> + +</chapter> +<!-- End of EUG Chapter Advanced --> + diff --git a/docbook/wsug_src/EUG_chapter_build_install.xml b/docbook/wsug_src/EUG_chapter_build_install.xml new file mode 100644 index 0000000000..2613270660 --- /dev/null +++ b/docbook/wsug_src/EUG_chapter_build_install.xml @@ -0,0 +1,754 @@ +<!-- 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 Wireshark + 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 required 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 Wireshark 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 Wireshark 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 Wireshark 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 Wireshark RPM that you have + downloaded from the Wireshark 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 the Windows platform. + </para> + <para> + For further information how to build Ethereal for Windows from the + sources, have a look at the Development Wiki: + <ulink url="http://wiki.ethereal.com/Development">http://wiki.ethereal.com/Development</ulink> + for the latest available development documentation. + </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. + </para> + <section id="ChBuildInstallEthereal"> + <title>Install Ethereal</title> + <para> + You may acquire a binary installer of Ethereal named something like: + <filename>ethereal-setup-x.y.z.exe</filename>. + </para> + <para> + Simply download the Wireshark installer from: + <ulink url="&EtherealBinariesPage;">&EtherealBinariesPage;</ulink> + and execute it. + </para> + <note><title>Note!</title> + <para> + <command>Since Ethereal Version 0.10.12, the WinPcap installer has become + part of the main Wireshark installer, so you don't need to download and + install two separate packages any longer!</command> + </para> + </note> + <section id="ChBuildInstallEtherealCommandLine"> + <title>Command line options</title> + <para> + You can simply start the Wireshark installer without any command line + parameters, it will show you the usual interactive installer. + </para> + <para> + There are some command line parameters available: + </para> + <itemizedlist> + <listitem> + <para> + <command>/NCRC</command> disables the CRC check + </para> + </listitem> + <listitem> + <para> + <command>/S</command> runs the installer or uninstaller silently with + default values. Please note: The silent installer won't install WinPCap! + </para> + </listitem> + <listitem> + <para> + <command>/desktopicon</command> installation of the desktop icon, + <command>=yes</command> - force installation, <command>=no</command> - + don't install, otherwise use defaults / user settings. + This option is available since 0.10.13 an can be useful for a silent + installer. + </para> + </listitem> + <listitem> + <para> + <command>/quicklaunchicon</command> installation of the quick launch icon, + <command>=yes</command> - force installation, <command>=no</command> - + don't install, otherwise use defaults / user settings. + This option is available since 0.10.13 an can be useful for a silent + installer. + </para> + </listitem> + <listitem> + <para> + <command>/D</command> sets the default installation directory + ($INSTDIR), overriding + InstallDir and InstallDirRegKey. It must be the last parameter used in + the command line and must not contain any quotes, even if the path + contains spaces. + </para> + </listitem> + </itemizedlist> + <para> Example: + <programlisting> +ethereal-setup-0.10.13.exe /NCRC /S /desktopicon=yes /quicklaunchicon=no /D=C:\Program Files\Foo + </programlisting> + </para> + </section> + <section id="ChBuildInstallComponents"> + <title>Components</title> + <para> + Beside the usual installer options like where to install the program, + there are several optional components. + </para> + <tip><title>Tip!</title> + <para> + If you are unsure which settings to select, just keep the default settings. + </para> + </tip> + <para> + The Components + (both Ethereal GTK1 and 2 cannot be installed at the same time): + <itemizedlist> + <listitem><para> + <command>Etheral GTK1</command> - Wireshark is a GUI network protocol + analyzer. + </para></listitem> + <listitem><para> + <command>Etheral GTK2</command> - Wireshark is a GUI network protocol + analyzer (using the modern GTK2 GUI toolkit, recommended). + </para></listitem> + <listitem><para> + <command>GTK-Wimp</command> - GTKWimp is the GTK2 windows impersonator + (native Win32 look and feel, recommended). + </para></listitem> + <listitem><para> + <command>Tethereal</command> - Tethereal is a command-line based network + protocol analyzer. + </para></listitem> + </itemizedlist> + The dissection extensions for Wireshark and Tethereal: + <itemizedlist> + <listitem><para> + <command>Dissector Plugins</command> - Plugins with some extended dissections. + </para></listitem> + <listitem><para> + <command>Tree Statistics Plugins</command> - Plugins with some extended statistics. + </para></listitem> + <listitem><para> + <command>Mate - Meta Analysis and Tracing Engine</command> - user + configurable extension(s) of the display filter engine, see + <ulink url="http://wiki.ethereal.com/Mate">http://wiki.ethereal.com/Mate</ulink> + for details. + </para></listitem> + <listitem><para> + <command>SNMP MIBs</command> - SNMP MIBs for a more detailed SNMP + dissection. + </para></listitem> + </itemizedlist> + The Tools: + <itemizedlist> + <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>Capinfos</command> - Capinfos is a program that provides + information on capture files. + </para></listitem> + </itemizedlist> + The Additional Tasks: + <itemizedlist> + <listitem><para> + <command>Start Menu Shortcuts</command> - add some start menu shortcuts. + </para></listitem> + <listitem><para> + <command>Desktop Icon</command> - add an Ethereal icon to the desktop. + </para></listitem> + <listitem><para> + <command>Quick Launch Icon</command> - add an Ethereal icon to the + Explorer quick launch toolbar. + </para></listitem> + <listitem><para> + <command>Associate file extensions to Ethereal</command> - Associate + standard network trace files to Ethereal. + </para></listitem> + </itemizedlist> + </para> + </section> + </section> + <section id="ChBuildInstallWinPcap"> + <title>Install WinPcap</title> + <note><title>Note!</title> + <para> + <command>As mentioned above, the Wireshark installer + (since version 0.10.12) takes care of the installation of WinPcap, + so usually you don't have to worry about WinPcap at all!</command> + </para> + </note> + <para> + If you do not have WinPcap installed you will be able to open saved + capture files, but you will not be able to capture live network traffic. + </para> + <para> + While running, the Wireshark installer detects which WinPcap version is + currently installed and will install WinPcap, if none or an older version is + detected. + </para> + <para> + More WinPcap info: + <itemizedlist> + <listitem><para> + Ethereal related: + <ulink url="http://wiki.ethereal.com/WinPcap">http://wiki.ethereal.com/WinPcap</ulink> + </para></listitem> + <listitem><para> + General WinPcap info: + <ulink url="&WinPcapWebsite;">&WinPcapWebsite;</ulink> + </para></listitem> + </itemizedlist> + </para> + <section id="ChBuildInstallWinPcapManually"> + <title>Manual WinPcap Installation</title> + <para> + The following is only necessary if you want to + try a different version than the one included in the Wireshark installer, + e.g. because a new WinPcap (beta) version was released. + </para> + <para> + Additional WinPcap versions (including newer alpha or beta releases) + can be downloaded from the following locations: + <itemizedlist> + <listitem><para> + The main WinPcap site: + <ulink url="&WinPcapWebsite;">&WinPcapWebsite;</ulink> + </para></listitem> + <listitem><para> + The ethereal.com mirror: + <ulink url="http://winpcap.mirror.ethereal.com"> + http://winpcap.mirror.ethereal.com</ulink> + </para></listitem> + <listitem><para> + The Wiretapped.net mirror: + <ulink url="http://www.mirrors.wiretapped.net/security/packet-capture/winpcap"> + http://www.mirrors.wiretapped.net/security/packet-capture/winpcap</ulink> + </para></listitem> + </itemizedlist> + </para> + <para> + At the download page 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. + </para> + </section> + </section> + + <section id="ChBuildInstallWinEtherealUpdate"> + <title>Update Ethereal</title> + <para> + From time to time you may want to update your installed Ethereal to a more + recent version. If you join Wireshark's announce mailing list, you will be + informed about new Ethereal versions, see <xref + linkend="ChIntroMailingLists"/> for details how to subscribe to this list. + </para> + <para> + New versions of Ethereal usually become available every 4-8 weeks. + Updating Wireshark 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> + </section> + + <section id="ChBuildInstallWinPcapUpdate"> + <title>Update WinPcap</title> + <para> + New versions of WinPcap are less frequently available, maybe only once in a + year. You will find WinPcap update instructions where you can download new + WinPcap versions. Usually you have to reboot the machine after installing + a new WinPcap version. + </para> + <warning><title>Warning!</title> + <para> + If you have an older version of WinPcap installed, you must un-install it + before installing the current version. Recent versions of the WinPcap + installer will take care of this. + </para> + </warning> + </section> + + <section id="ChBuildInstallWinUninstall"> + <title>Uninstall Ethereal</title> + <para> + You can uninstall Ethereal the usual way, using the "Add or Remove + Programs" option inside the Control Panel. Select the "Ethereal" entry to + start the uninstallation procedure. + </para> + <para> + The Wireshark uninstaller will provide several options which things to be + uninstalled, the default is to remove the core components but keep the personal + settings, WinPcap and alike. + </para> + <para> + WinPcap won't be uninstalled by default, as other programs than Ethereal + may use it as well. + </para> + </section> + + <section id="ChBuildInstallWinPcapUninstall"> + <title>Uninstall WinPcap</title> + <para> + You can uninstall WinPcap independantly of Ethereal, using the "WinPcap" + entry in the "Add or Remove Programs" of the Control Panel. + </para> + <note><title>Note!</title> + <para> + After uninstallation of WinPcap you can't capture anything with Ethereal. + </para> + </note> + <para> + It might be a good idea to reboot Windows afterwards. + </para> + </section> + </section> + +</chapter> +<!-- End of EUG Chapter 2 --> diff --git a/docbook/wsug_src/EUG_chapter_capture.xml b/docbook/wsug_src/EUG_chapter_capture.xml new file mode 100644 index 0000000000..9918b3e9fb --- /dev/null +++ b/docbook/wsug_src/EUG_chapter_capture.xml @@ -0,0 +1,1033 @@ +<!-- 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 Wireshark 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="ChCapPrerequisitesSection"><title>Prerequisites</title> + <para> + Setting up Ethereal to capture packets for the first time can be tricky. + </para> + <tip><title>Tip!</title><para> + A comprehensive guide "How To setup a Capture" is available at: + <ulink url="http://wiki.ethereal.com/CaptureSetup">http://wiki.ethereal.com/CaptureSetup</ulink>. + </para></tip> + <para> + Here are some common pitfalls: + <itemizedlist> + <listitem> + <para> + You need to have root / Administrator privileges to start a live + capture. + </para> + </listitem> + <listitem> + <para> + You need to choose the right network interface to capture packet data + from. + </para> + </listitem> + <listitem> + <para> + You need to capture at the right place in the network to see the + traffic you want to see. + </para> + </listitem> + <listitem> + <para> + ... and a lot more!. + </para> + </listitem> + </itemizedlist> + </para> + <para> + If you have any problems setting up your capture environment, you should + have a look at the guide mentioned above. + </para> + </section> + + <section id="ChCapCapturingSection"><title>Start Capturing</title> + <para> + One of the following methods can be used to start capturing packets with + Ethereal: + <itemizedlist> + <listitem> + <para> + You can get an overview of the available local interfaces using the + "<inlinegraphic entityref="EtherealToolbarCaptureInterfaces" format="PNG"/> + Capture Interfaces" dialog box, see + <xref linkend="ChCapCaptureInterfacesDialog"/>. You can start a + capture from this dialog box, using (one of) the "Capture" button(s). + </para> + </listitem> + <listitem> + <para> + You can start capturing using the + "<inlinegraphic entityref="EtherealToolbarCaptureOptions" format="PNG"/> + Capture Options" dialog box, see + <xref linkend="ChCapCaptureOptionsDialog"/>. + </para> + </listitem> + <listitem> + <para> + If you have selected the right capture options before, you can + immediately start a capture using the + "<inlinegraphic entityref="EtherealToolbarCaptureStart" format="PNG"/> + Capture Start" menu / toolbar item. The capture + process will start immediately. + </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, more details + can be found at: <xref linkend="ChCustCommandLine"/>. + </para> + </listitem> + </itemizedlist> + </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> + </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. + </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 allows you to stop capturing when + you have enough packets captured, for details 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 Wireshark 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="5"> + <colspec colnum="1" colwidth="72pt"/> + <colspec colnum="2" colwidth="80pt"/> + <colspec colnum="3" colwidth="80pt"/> + <colspec colnum="4" colwidth="80pt"/> + <thead> + <row> + <entry>"File" option</entry> + <entry>"Use multiple files" option</entry> + <entry>"Ring buffer with n files" option</entry> + <entry>Mode</entry> + <entry>Resulting filename(s) used</entry> + </row> + </thead> + <tbody> + <row> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry><command>Single temporary file</command></entry> + <entry>etherXXXXXX (where XXXXXX is a unique number)</entry> + </row> + <row> + <entry>foo.cap</entry> + <entry>-</entry> + <entry>-</entry> + <entry><command>Single named file</command></entry> + <entry>foo.cap</entry> + </row> + <row> + <entry>foo.cap</entry> + <entry>x</entry> + <entry>-</entry> + <entry><command>Multiple files, continuous</command></entry> + <entry>foo_00001_20040205110102.cap, foo_00002_20040205110102.cap, ...</entry> + </row> + <row> + <entry>foo.cap</entry> + <entry>x</entry> + <entry>x</entry> + <entry><command>Multiple files, ring buffer</command></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> + <tip> + <title>Tip!</title> + <para> + You will find a lot of Capture Filter examples at <ulink + url="&EtherealWikiCaptureFiltersPage;">&EtherealWikiCaptureFiltersPage;</ulink>. + </para> + </tip> + <para> + You enter the capture filter into the Filter field of the Wireshark + 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="&TcpdumpManpage;"/>. + </para> + <para> + A capture filter takes the form of a series of primitive expressions + connected by conjunctions (<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 page at + <ulink url="&TcpdumpManpage;"/> 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 + "<inlinegraphic entityref="EtherealToolbarStop" format="PNG"/> + 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/<inlinegraphic entityref="EtherealToolbarCaptureStop" format="PNG"/> + Stop". + </para> + </listitem> + <listitem> + <para>Using the <command>toolbar item</command> + "<inlinegraphic entityref="EtherealToolbarCaptureStop" format="PNG"/> + Stop". + </para> + </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 id="ChCapRestartSection"><title>Restart a running capture</title> + <para> + A running capture session can be restarted with the same capture options + than the last time, this will remove all packets previously captured. + This can be useful, if some uninteresting packets are captured and + there's no need to keep them. + </para> + <para> + Restart is a convenience function and + equivalent to a capture stop following by an immediate capture start. + A restart can be triggered in one of the following ways: + <orderedlist> + <listitem> + <para>Using the <command>menu item</command> + "Capture/<inlinegraphic entityref="EtherealToolbarCaptureRestart" format="PNG"/> + Restart". + </para> + </listitem> + <listitem> + <para>Using the <command>toolbar item</command> + "<inlinegraphic entityref="EtherealToolbarCaptureRestart" format="PNG"/> + Restart". + </para> + </listitem> + </orderedlist> + </para> + </section> + </section> + +</chapter> +<!-- End of EUG Chapter Capture --> + diff --git a/docbook/wsug_src/EUG_chapter_customize.xml b/docbook/wsug_src/EUG_chapter_customize.xml new file mode 100644 index 0000000000..5c9c9d23e3 --- /dev/null +++ b/docbook/wsug_src/EUG_chapter_customize.xml @@ -0,0 +1,827 @@ +<!-- 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 packet list + </para> + </listitem> + <listitem> + <para> + How to control protocol dissection + </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 ethereal 0.10.13 + (C) 1998-2005 Gerald Combs <gerald@wireshark.org> + +Compiled with GTK+ 2.6.9, with GLib 2.6.6, with WinPcap (version unknown), +with libz 1.2.3, with libpcre 6.3, with Net-SNMP 5.2.1.2, with ADNS. + +Running with WinPcap version 3.1 (packet.dll version 3, 1, 0, 27), based on libp +cap version 0.9[.x] on Windows XP Service Pack 2, build 2600. + +ethereal [ -vh ] [ -DklLnpQS ] [ -a <capture autostop condition> ] ... + [ -b <capture ring buffer option> ] ... + [ -B <capture buffer size> ] + [ -c <capture packet count> ] [ -f <capture filter> ] + [ -g <packet number> ] [ -i <capture interface> ] [ -m <font> ] + [ -N <name resolving flags> ] [ -o <preference/recent setting> ] ... + [ -r <infile> ] [ -R <read (display) filter> ] [ -s <capture snaplen> ] + [ -t <time stamp format> ] [ -w <savefile> ] [ -y <capture link type> ] + [ -X <eXtension option> ] [ -z <statistics> ] [ <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 Wireshark 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>:value</term> + <listitem><para> + Stop writing to a capture file after value of seconds have elapsed. + </para></listitem> + </varlistentry> + <varlistentry><term><command>filesize</command>:value</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). If + this option is used together with the -b option, Ethereal will + stop writing to the current capture file and switch to the next + one if filesize is reached. + </para></listitem> + </varlistentry> + <varlistentry><term><command>files</command>:value</term> + <listitem><para> + Stop writing to capture files after value number of files were + written. + </para></listitem> + </varlistentry> + </variablelist> + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>-b <capture ring buffer option></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> + <para> + <variablelist> + <varlistentry><term><command>duration</command>:value</term> + <listitem><para> + Switch to the next file after value seconds have elapsed, even + if the current file is not completely filled up. + </para></listitem> + </varlistentry> + <varlistentry><term><command>filesize</command>:value</term> + <listitem><para> + Switch to the next file after it reaches a size of value kilobytes + (where a kilobyte is 1000 bytes, not 1024 bytes). + </para></listitem> + </varlistentry> + <varlistentry><term><command>files</command>:value</term> + <listitem><para> + Begin again with the first file after value number of files were + written (form a ring buffer). + </para></listitem> + </varlistentry> + </variablelist> + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>-B <capture buffer size (Win32 only)></command></term> + <listitem> + <para> + Win32 only: set capture buffer size (in MB, default is 1MB). This + is used by the the capture driver to buffer packet data until that + data can be written to disk. If you encounter packet drops while + capturing, try to increase this size. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>-c <capture packet 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>-D</command></term> + <listitem> + <para> +Print a list of the interfaces on which Ethereal can capture, and +exit. For each network interface, a number and an +interface name, possibly followed by a text description of the +interface, is printed. The interface name or the number can be supplied +to the <command>-i</command> flag to specify an interface on which to capture. + </para> + <para> +This can be useful on systems that don't have a command to list them +(e.g., Windows systems, or UNIX systems lacking <command>ifconfig -a</command>); +the number can be useful on Windows 2000 and later systems, where the +interface name is a somewhat complex string. + </para> + <para> +Note that "can capture" means that Ethereal was able to open +that device to do a live capture; if, on your system, a program doing a +network capture must be run from an account with special privileges (for +example, as root), then, if Wireshark is run with the <command>-D</command> flag and +is not run from such an account, it will not list any interfaces. + </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>-g <packet number></command></term> + <listitem> + <para> + After reading in a capture file using the -r flag, go to the given + packet number. + </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 <capture interface></command></term> + <listitem> + <para> +Set the name of the network interface or pipe to use for live packet +capture. + </para> + <para> +Network interface names should match one of the names listed in +<command>ethereal -D</command> (described above); a number, as reported by +<command>ethereal -D</command>, can also be used. If you're using UNIX, <command>netstat +-i</command> or <command>ifconfig -a</command> might also work to list interface names, +although not all versions of UNIX support the <command>-a</command> flag to <command>ifconfig</command>. + </para> + <para> +If no interface is specified, Ethereal searches the list of +interfaces, choosing the first non-loopback interface if there are any +non-loopback interfaces, and choosing the first loopback interface if +there are no non-loopback interfaces; if there are no interfaces, +Ethereal reports an error and doesn't start the capture. + </para> + <para> +Pipe names should be either the name of a FIFO (named pipe) or ``-'' to +read data from the standard input. Data read from pipes must be in +standard libpcap format. + </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 <font></command></term> + <listitem> + <para> + This option sets the name of the font used for most text + displayed by Wireshark. 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 <name resolving flags></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/recent settings></command></term> + <listitem> + <para> + Sets a preference or recent value, overriding the default value and + any value read from a preference/recent 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/recent 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 Wireshark is running, broadcast traffic, and + multicast traffic to addresses received by that machine. + </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 Wireshark + to read and display. This capture file can be in one of the + formats Ethereal understands. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>-R <read (display) 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 <capture 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>-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 <capture 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>-X <eXtension option></command></term> + <listitem> + <para> + Specify an option to be passed to a Tethereal module. The eXtension + option is in the form extension_key:value, where extension_key can + be: + </para> + <para> + <command>lua_script</command>:lua_script_filename Tell Ethereal to load the given script in addition to the default Lua scripts. + </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 Wireshark is packet colorization. + You can set-up Ethereal so that it will colorize packets according to a + filter. This allows you to emphasize the packets you are usually + interested in. + </para> + <tip> + <title>Tip!</title> + <para> + You will find a lot of Coloring Rule examples at the <command>Ethereal + Wiki Coloring Rules page</command> at <ulink + url="&EtherealWikiColoringRulesPage;">&EtherealWikiColoringRulesPage;</ulink>. + </para> + </tip> + <para> + To colorize packets, select the Coloring Rules... menu item from + the View menu, 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 the coloring 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 Wireshark. 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> + The user can control how protocols are dissected. + </para> + <para> + Each protocol has its own dissector, so dissecting a complete 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 permanently, so they will be lost + when Wireshark 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 experiments 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 network layer + at which "Decode As" should take place. 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. + <note><title>Note!</title> + <para> + Preference settings are added frequently. For a recent explanation of + the preference pages and their settings have a look at the + <command>Ethereal Wiki Preferences page</command> at <ulink + url="&EtherealWikiPreferencesPage;">&EtherealWikiPreferencesPage;</ulink>. + </para> + </note> + <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> + <figure id="ChCustGUIPrefPage"> + <title>The preferences dialog box</title> + <graphic entityref="EtherealGUIPreferences" format="PNG"/> + </figure> + </section> + +</chapter> +<!-- End of EUG Chapter Customizing --> + diff --git a/docbook/wsug_src/EUG_chapter_introduction.xml b/docbook/wsug_src/EUG_chapter_introduction.xml new file mode 100644 index 0000000000..99f7e52957 --- /dev/null +++ b/docbook/wsug_src/EUG_chapter_introduction.xml @@ -0,0 +1,614 @@ +<!-- EUG Chapter Introduction --> +<!-- $Id$ --> + +<chapter id="ChapterIntroduction"> + <title>Introduction</title> + <!-- Introduction --> + <section id="ChIntroWhatIs"> + <title>What is <application>Ethereal?</application></title> + <para> + Wireshark 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 Wireshark) for a great many protocols: + see <xref linkend="AppProtocols"/>. + </para> + </section> + + <section><title>Open Source Software</title> + <para> + Wireshark 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 Wireshark 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> + Maintained: + <itemizedlist> + <listitem><para>Windows Server 2003 / XP / 2000 / NT 4.0</para></listitem> + <listitem><para>Windows Me / 98</para></listitem> + </itemizedlist> + </para> + <para> + Unsupported/Unmaintained (because lack of required libraries): + <itemizedlist> + <listitem><para>Windows CE</para></listitem> + <listitem><para>Windows NT / XP Embedded</para></listitem> + <listitem><para>Windows 95 is no longer actively maintained by WinPcap, + but still may work perfectly</para></listitem> + </itemizedlist> + </para> + <para> + No experiences (fresh versions): + <itemizedlist> + <listitem><para>Windows XP 64-bit Edition</para></listitem> + <listitem><para>Windows Vista (aka Longhorn)</para></listitem> + </itemizedlist> + Please provide your experiences about these fresh versions to: + <ulink url="mailto:&EtherealDevMailList;">&EtherealDevMailList;</ulink>. + </para> + </section> + + </section> + + <section id="ChIntroDownload"> + <title>Where to get Ethereal?</title> + <para> + You can get the latest copy of the program from the Wireshark 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 pronunciation 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 Wireshark is handled by the Wireshark 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> + Wireshark 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 Wireshark 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 Wireshark 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 Wireshark source code and binary kits for some platforms are all + available on the download page of the Wireshark 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="ChIntroHomepage"><title>Website</title> + <para> + You will find lot's of useful information on the Wireshark homepage at + <ulink url="&EtherealWebSite;">&EtherealWebSite;</ulink>. + </para> + </section> + + <section id="ChIntroWiki"><title>Wiki</title> + <para> + The Wireshark Wiki at <ulink + url="&EtherealWikiPage;">&EtherealWikiPage;</ulink> provides a wide range + of information related to Ethereal and packet capturing in general. + You will find a lot of information not part of this user's guide. For + example, there is an explanation how to capture on a switched network, + an ongoing effort to build a protocol reference and a lot more. + </para> + <para> + And best of all, if you would like to contribute your knowledge on a + specific topic (maybe a network protocol you know well), you can edit the + wiki pages by simply using your webbrowser. + </para> + </section> + + <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 Wireshark 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 Wireshark 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 Wireshark 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> + <warning><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> + </warning> + </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/wsug_src/EUG_chapter_io.xml b/docbook/wsug_src/EUG_chapter_io.xml new file mode 100644 index 0000000000..cadbefc353 --- /dev/null +++ b/docbook/wsug_src/EUG_chapter_io.xml @@ -0,0 +1,875 @@ +<!-- 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 menu or toolbar item: "File/ + <inlinegraphic entityref="EtherealToolbarOpen" format="PNG"/> + <command>Open</command>". + 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 Wireshark 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 also 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 extra time changing these settings later, so it + might be a good idea to set at least the filter 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> + <listitem><para>Catapult DCT2000 .out files</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="ChIOOutputFormatsSection"/>. + </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> + <listitem><para>HP-UX's nettl</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 Associates Sniffer Windows + </para> + </note> + </section> + </section> + + <section id="ChIOMergeSection"><title>Merging capture files</title> + <para> + Sometimes you need to merge several capture files into one. For example + this can be useful, if you have captured simultaneously from multiple + interfaces at once (e.g. using multiple instances of 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="ChIOFileSetSection"><title>File Sets</title> + <para> + When using the "Multiple Files" option while doing a capture + (see: <xref linkend="ChCapCaptureFiles"/>), + the capture data is spreaded over several capture files, called a file + set. + </para> + <para> + As it can become tedious to work with a file set by hand, Ethereal + provides some features to handle these file sets in a convenient way. + </para> + <sidebar><title>How does Ethereal detect the files of a file set?</title> + <para> + A filename in a file set uses the format Prefix_Number_DateTimeSuffix + which might look like this: "test_00001_20060420183910.pcap". + All files of a file set share the same prefix (e.g. "test") and suffix + (e.g. ".pcap") and a varying middle part. + </para> + <para> + To find the files of a file set, Ethereal scans the directory where the + currently loaded file resides and scans for files matching the same filename + pattern (prefix and suffix) than the currently loaded file. + </para> + <para> + This simple mechanism usually works well, but has it's drawbacks. If several + file sets were captured with the same prefix and suffix, Ethereal will detect + them as a single file set. If files were renamed or spreaded over several + directories the mechanism will fail to find all files of a set. + </para> + </sidebar> + <para> + The following features in the "File Set" submenu of the "File" menu are + available to work with file sets in a convenient way: + </para> + <itemizedlist> + <listitem><para> + The <command>List Files</command> dialog box will list the files + Ethereal has recognized as being part of the current file set. + </para></listitem> + <listitem><para> + <command>Next File</command> closes the current and opens the next + file in the file set. + </para></listitem> + <listitem><para> + <command>Previous File</command> closes the current and opens the + previous file in the file set. + </para></listitem> + </itemizedlist> + <section id="ChIOFileSetListDialog"> + <title>The "List Files" dialog box</title> + <figure> + <title>The "List Files" dialog box</title> + <graphic entityref="EtherealFileSetDialog" format="PNG"/> + </figure> + <para> + Each line contains information about a file of the file set: + <itemizedlist> + <listitem><para> + <command>Filename</command> the name of the file. If you click on + the filename (or the radio button left to it), the current file will + be closed and the corresponding capture file will be opened. + </para></listitem> + <listitem><para> + <command>Created</command> the creation time of the file + </para></listitem> + <listitem><para> + <command>Last Modified</command> the last time the file was modified + </para></listitem> + <listitem><para> + <command>Size</command> the size of the file + </para></listitem> + </itemizedlist> + The last line will contain info about the currently used directory where + all of the files in the file set can be found. + </para> + <para> + The content of this dialog box is updated each time a capture file is + opened/closed. + </para> + <para> + The Close button will, well, close the dialog box. + </para> + </section> + </section> + <section id="ChIOExportSection"><title>Exporting data</title> + <para> + 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="ChIOExportCSVDialog"> + <title>The "Export as CSV (Comma Seperated Values) File" dialog box</title> + <para>XXX - add screenshot</para> + <para> + Export packet summary into CSV, used e.g. by spreadsheet programs to + im-/export data. + <!--<figure> + <title>The "Export as Comma Seperated Values File" dialog box</title> + <graphic entityref="EtherealExportCSVDialog" format="PNG"/> + </figure>--> + <itemizedlist> + <listitem><para> + <command>Export to file:</command> frame chooses the file to export + the packet data to. + </para></listitem> + <listitem><para> + The <command>Packet Range</command> frame is described in <xref + linkend="ChIOPacketRangeSection"/>. + </para></listitem> + </itemizedlist> + </para> + </section> + <section id="ChIOExportPSMLDialog"> + <title>The "Export as PSML File" dialog box</title> + <para> + Export packet data into PSML. This is an XML based format including + only the packet summary. + <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>PostScript</command> specifies that + the packet print process should use PostScript to + generate a better print output on PostScript aware printers. + </para> + </listitem> + <listitem> + <para> + <command>Output to file:</command> specifies that printing + be done to a file, 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 by 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/wsug_src/EUG_chapter_statistics.xml b/docbook/wsug_src/EUG_chapter_statistics.xml new file mode 100644 index 0000000000..e360d39e05 --- /dev/null +++ b/docbook/wsug_src/EUG_chapter_statistics.xml @@ -0,0 +1,508 @@ +<!-- 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> + <note><title>Note!</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> + </note> + </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> + <note><title>Note!</title> + <para> + A single packet can contain the same protocol more than once. In this case, + the protocol is counted more than once. For example: in some tunneling + configurations the IP layer can appear twice. + </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>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 + slightly 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> + <para> + Some of these statistics are described at the + <ulink url="http://wiki.ethereal.com/Statistics"/> pages. + </para> + </section> + +</chapter> +<!-- End of EUG Chapter Statistics --> + diff --git a/docbook/wsug_src/EUG_chapter_troubleshoot.xml b/docbook/wsug_src/EUG_chapter_troubleshoot.xml new file mode 100644 index 0000000000..ffeb050f4a --- /dev/null +++ b/docbook/wsug_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> + Wireshark 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/wsug_src/EUG_chapter_use.xml b/docbook/wsug_src/EUG_chapter_use.xml new file mode 100644 index 0000000000..9852ce4b50 --- /dev/null +++ b/docbook/wsug_src/EUG_chapter_use.xml @@ -0,0 +1,2063 @@ +<!-- 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 Wireshark 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 well 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="ChCustPreferencesSection"/> for details! + </para> + </tip> + </para> + </section> + + <section id="ChUseMenuSection"><title>The Menu</title> + <para> + The Wireshark menu sits on top of the Wireshark 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 items 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 Wireshark 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>File Set > List Files</command></entry> + <entry></entry> + <entry><para> + This menu item allows you to show a list of files in a file set. + It pops up the Wireshark List File Set dialog box (which is + discussed further in <xref linkend="ChIOFileSetSection"/>). + </para></entry> + </row> + <row> + <entry><command>File Set > Next File</command></entry> + <entry></entry> + <entry><para> + If the currently loaded file is part of a file set, jump to the + next file in the set. If it isn't part of a file set or just the + last file in that set, this item is greyed out. + </para></entry> + </row> + <row> + <entry><command>File Set > Previous File</command></entry> + <entry></entry> + <entry><para> + If the currently loaded file is part of a file set, jump to the + previous file in the set. If it isn't part of a file set or just + the first file in that set, this item is greyed out. + </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 Wireshark 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 Wireshark Export dialog box (which is discussed further in + <xref linkend="ChIOExportPSDialog"/>). + </para></entry> + </row> + <row> + <entry><command>Export > as "CSV" (Comma Separated Values packet summary) file...</command></entry> + <entry></entry> + <entry><para> + This menu item allows you to export the (or some) of the packet summaries in + the capture file to a .csv file (e.g. used by spreadsheet programs). + It pops up the Wireshark Export dialog box (which is discussed further in + <xref linkend="ChIOExportCSVDialog"/>). + </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 Wireshark 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 Wireshark 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 Wireshark 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 Wireshark 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 (toggle)</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 (toggle)</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 Wireshark 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 > Date and Time of Day: 1970-01-01 01:02:03.123456</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"/>. + <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 > Time of Day: 01:02:03.123456</command></entry> + <entry></entry> + <entry><para> + Selecting this tells Ethereal to display time + stamps in time of day format, see + <xref linkend="ChWorkTimeFormatsSection"/>. + </para></entry> + </row> + <row> + <entry><command>Time Display Format > Seconds Since Beginning of Capture: 123.123456</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: 1.123456</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>Time Display Format > ------</command></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry><command>Time Display Format > Automatic (File Format Precision)</command></entry> + <entry></entry> + <entry><para> + Selecting this tells Ethereal to display time stamps with the + precision given by the capture file format used, see + <xref linkend="ChWorkTimeFormatsSection"/>. + <note><title>Note!</title> + <para> + The fields "Automatic", "Seconds" and "...seconds" are mutually exclusive. + </para> + </note> + </para></entry> + </row> + <row> + <entry><command>Time Display Format > Seconds: 0</command></entry> + <entry></entry> + <entry><para> + Selecting this tells Ethereal to display time stamps with a precision of one second, see + <xref linkend="ChWorkTimeFormatsSection"/>. + </para></entry> + </row> + <row> + <entry><command>Time Display Format > ...seconds: 0....</command></entry> + <entry></entry> + <entry><para> + Selecting this tells Ethereal to display time stamps with a precision of one second, decisecond, centisecond, millisecond, microsecond or nanosecond, 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>Colorize Packet List</command></entry> + <entry></entry> + <entry><para> + This item allows you to control wether or not Ethereal should colorize + the packet list.</para> + <note><title>Note!</title><para> + Enabling colorization will slow down the display + of new packets while capturing / loading capture files. + </para></note></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>Resize All Columns</command></entry> + <entry></entry> + <entry><para> + Resize all column widths so the content will fit into it. + </para> + <note><title>Note!</title><para> + Resizing may take a significant amount of time, especially if a + large capture file is loaded. + </para></note> + </entry> + </row> + <row> + <entry><command>------</command></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry><command>Expand Subtrees</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>Expand 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 expands all subtrees in all packets in + the capture. + </para></entry> + </row> + <row> + <entry><command>Collapse All</command></entry> + <entry></entry> + <entry><para> + This menu item collapses the tree view of all packets + in the capture list. + </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 Wireshark 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>Back</command></entry> + <entry>Alt+Left</entry> + <entry><para> + Jump to the recently visited packet in the packet + history, much like the page history in a web browser. + </para></entry> + </row> + <row> + <entry><command>Forward</command></entry> + <entry>Alt+Right</entry> + <entry><para> + Jump to the next visited packet in the packet + history, much like the page history in a web browser. + </para></entry> + </row> + <row> + <entry><command>Go to Packet...</command></entry> + <entry>Ctrl-G</entry> + <entry><para> + Bring 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> + Go 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> + Jump to the first packet of the capture file. + </para></entry> + </row> + <row> + <entry><command>Last Packet</command></entry> + <entry></entry> + <entry><para> + Jump 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 Wireshark 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>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>Options...</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>Start</command></entry> + <entry></entry> + <entry><para> + Immediately start capturing packets with the same settings than + the last time. + </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>Restart</command></entry> + <entry></entry> + <entry><para> + This menu item stops the currently running capture and starts + again with the same options, this is just for convenience. + </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 Wireshark 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 Wireshark 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>GSM</command></entry> + <entry></entry> + <entry><para>See <xref linkend="ChStatXXX"/></para></entry> + </row> + <row> + <entry><command>H.225...</command></entry> + <entry></entry> + <entry><para>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>MTP3</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>SCTP</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>VoIP Calls...</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> + <row> + <entry><command>------</command></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry><command>BOOTP-DHCP</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 Messages</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>TCP Stream Graph</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 Wireshark 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="EtherealToolbarCaptureInterfaces" format="PNG"/></entry> + <entry><command>Interfaces...</command></entry> + <entry>Capture/Interfaces...</entry> + <entry><para> + This item brings up the Capture Interfaces List + dialog box (discussed further in + <xref linkend="ChCapCapturingSection"/>). + </para> + </entry> + </row> + <row> + <entry><graphic entityref="EtherealToolbarCaptureOptions" format="PNG"/></entry> + <entry><command>Options...</command></entry> + <entry>Capture/Options...</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> + </entry> + </row> + <row> + <entry><graphic entityref="EtherealToolbarCaptureStart" format="PNG"/></entry> + <entry><command>Start</command></entry> + <entry>Capture/Start</entry> + <entry><para> + This item starts capturing packets with the options form + the last time. + </para> + </entry> + </row> + <row> + <entry><graphic entityref="EtherealToolbarCaptureStop" format="PNG"/></entry> + <entry><command>Stop</command></entry> + <entry>Capture/Stop</entry> + <entry><para> + This item stops the currently running live capture process + <xref linkend="ChCapCapturingSection"/>). + </para> + </entry> + </row> + <row> + <entry><graphic entityref="EtherealToolbarCaptureRestart" format="PNG"/></entry> + <entry><command>Restart</command></entry> + <entry>Capture/Restart</entry> + <entry><para> + This item stops the currently running live capture process + and restarts it again, for convenience. + </para> + </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 Wireshark 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="EtherealToolbarGoBack" format="PNG"/></entry> + <entry><command>Go Back</command></entry> + <entry>Go/Go Back</entry> + <entry><para> + This item jumps back in the packet history. + </para></entry> + </row> + <row> + <entry><graphic entityref="EtherealToolbarGoForward" format="PNG"/></entry> + <entry><command>Go Forward</command></entry> + <entry>Go/Go Forward</entry> + <entry><para> + This item jumps forward in the packet history. + </para></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="EtherealToolbarColorize" format="PNG"/></entry> + <entry><command>Colorize</command></entry> + <entry>View/Colorize</entry> + <entry><para> + Colorize the packet list (or not). + </para></entry> + </row> + <row> + <entry><graphic entityref="EtherealToolbarAutoScroll" format="PNG"/></entry> + <entry><command>Auto Scroll in Live Capture</command></entry> + <entry>View/Auto Scroll in Live Capture</entry> + <entry><para> + Auto scroll packet list while doing a live capture (or not). + </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><graphic entityref="EtherealToolbarResizeColumns" format="PNG"/></entry> + <entry><command>Resize Columns</command></entry> + <entry>View/Resize Columns</entry> + <entry><para> + Resize columns, so the content fits into them. + </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> + <row> + <entry><command>------</command></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry><graphic entityref="EtherealToolbarHelp" format="PNG"/></entry> + <entry><command>Help</command></entry> + <entry>Help/Contents</entry> + <entry><para> + This item brings up help dialog box. + </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 corresponds 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="ChCustPreferencesSection"/>. + </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 + Wireshark 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/wsug_src/EUG_chapter_work.xml b/docbook/wsug_src/EUG_chapter_work.xml new file mode 100644 index 0000000000..9d083939a3 --- /dev/null +++ b/docbook/wsug_src/EUG_chapter_work.xml @@ -0,0 +1,1419 @@ +<!-- 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 a 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 Wireshark 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 the packet list pane, and then + select "Show Packet in New Windows" from the Display menu. This + allows you to easily compare two or even 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 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>Mark Packet (toggle)</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>Expand Subtrees</command></entry> + <entry>-</entry> + <entry>X</entry> + <entry>-</entry> + <entry>View</entry> + <entry> + <para>Expand the currently selected subtree. + </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>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>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>Follow TCP stream</command></entry> + <entry>X</entry> + <entry>X</entry> + <entry>-</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>Wiki Protocol Page</command></entry> + <entry>-</entry> + <entry>X</entry> + <entry>-</entry> + <entry>-</entry> + <entry> + <para>Show the wiki page corresponding to the currently selected protocol in your web browser. + </para> + </entry> + </row> + <row> + <entry><command>Filter Field Reference</command></entry> + <entry>-</entry> + <entry>X</entry> + <entry>-</entry> + <entry>-</entry> + <entry> + <para>Show the filter field reference web page corresponding to the currently selected protocol in your web browser. + </para> + </entry> + </row> + <row> + <entry><command>Protocol Preferences...</command></entry> + <entry>-</entry> + <entry>X</entry> + <entry>-</entry> + <entry>-</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="ChCustPreferencesSection"/>. + </para> + </entry> + </row> + <row> + <entry><command>Decode As...</command></entry> + <entry>X</entry> + <entry>X</entry> + <entry>-</entry> + <entry>Analyze</entry> + <entry> + <para>.</para> + </entry> + </row> + + + + <row> + <entry><command>Print...</command></entry> + <entry>X</entry> + <entry>-</entry> + <entry>-</entry> + <entry>File</entry> + <entry> + <para>Print (the selected) packet(s).</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>View/Name Resolution</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>Copy</command></entry> + <entry>-</entry> + <entry>-</entry> + <entry>X</entry> + <entry>-</entry> + <entry> + <para>Copy the selected packet data to the clipboard (XXX - in which format). + </para> + </entry> + </row> + <row> + <entry><command>Export Selected Packet Bytes...</command></entry> + <entry>-</entry> + <entry>-</entry> + <entry>X</entry> + <entry>File->Export</entry> + <entry> + <para>Export raw packet bytes to a binary file.</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>Mark Packet (toggle)</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>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>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>Expand Subtrees</command></term> + <listitem> + <para> + This menu item expands the currently selected subtree. + </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>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>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>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>Wiki Protocol Page</command></term> + <listitem> + <para> + Show the wiki page corresponding to the currently selected protocol + in your web browser. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Filter Field Reference</command></term> + <listitem> + <para> + Show the filter field reference web page corresponding to the + currently selected protocol in your web browser. + </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>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>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> + </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>Copy</command></term> + <listitem> + <para> + Copy the selected packet data to the clipboard (XXX - in which format). + </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 while hiding the currently uninteresting ones. 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 Wireshark 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 but + 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 Wireshark 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> + <tip> + <title>Tip!</title> + <para> + You will find a lot of Display Filter examples at the <command>Ethereal + Wiki Display Filter page</command> at <ulink + url="&EtherealWikiDisplayFiltersPage;">&EtherealWikiDisplayFiltersPage;</ulink>. + </para> + </tip> + <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>Tip!</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 Wireshark 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 brackets [] 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> + <warning><title>Warning!</title> + <para> + Using the != operator on combined expressions like: eth.addr, ip.addr, + tcp.port, udp.port and alike will probably not work as expected! + </para> + </warning> + <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 one of them 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 one, 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 Back" command</title> + <para> + Go back in the packet history, works much like the page history in current + web browsers. + </para> + </section> + <section><title>The "Go Forward" command</title> + <para> + Go forward in the packet history, works much like the page history in + current web browsers. + </para> + </section> + <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 to simply 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 (toggle)</command> toggles 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 (toggle)" 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> + A detailed description of timestamps, timezones and alike can be found at: <xref + linkend="ChAdvTimestamps"/>. + </para> + <para> + The timestamp presentation format and the precision in the packet list can + be chosen using the View menu, see <xref linkend="ChUseEtherealViewMenu"/>. + </para> + <para> + The available presentation formats are: + <itemizedlist> + <listitem><para><command>Date and Time of Day: 1970-01-01 01:02:03.123456</command> + The absolute date and time of the day when the packet was captured.</para> + </listitem> + <listitem><para><command>Time of Day: 01:02:03.123456</command> + The absolute time of the day when the packet was captured.</para> + </listitem> + <listitem><para><command>Seconds Since Beginning of Capture: 123.123456</command> + 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: 1.123456</command> + The time relative to the previous packet.</para> + </listitem> + </itemizedlist> + </para> + <para> + The available precisions (aka. the number of displayed decimal places) are: + <itemizedlist> + <listitem><para><command>Automatic</command> + The timestamp precision of + the loaded capture file format will be used (the default).</para> + </listitem> + <listitem><para><command>Seconds, Deciseconds, Centiseconds, Milliseconds, + Microseconds or Nanoseconds</command> + The timestamp precision will be forced to the given setting. If the + actually available + precision is smaller, zeros will be appended. If the precision is larger, + the remaining decimal places will be cut off.</para> + </listitem> + </itemizedlist> + </para> + <para> + Precision example: If you have a timestamp and it's displayed using, + "Seconds Since Previous Packet", : the value might be 1.123456. This will + be displayed using the "Automatic" setting for libpcap files (which is + microseconds). If you use Seconds it would show simply 1 and if you use + Nanoseconds it shows 1.123456000. + </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/wsug_src/EUG_meta_info.xml b/docbook/wsug_src/EUG_meta_info.xml new file mode 100644 index 0000000000..62005e27d6 --- /dev/null +++ b/docbook/wsug_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/wsug_src/EUG_preface.xml b/docbook/wsug_src/EUG_preface.xml new file mode 100644 index 0000000000..665fc98423 --- /dev/null +++ b/docbook/wsug_src/EUG_preface.xml @@ -0,0 +1,171 @@ +<!-- $Id$ --> + +<preface id="Preface"> + <title>Preface</title> + <section id="PreForeword"> + <title>Foreword</title> + <para> + Wireshark 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 Wireshark 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. A lot of useful + information regarding these topics can be found at the Wireshark Wiki at + <ulink url="&EtherealWikiPage;">&EtherealWikiPage;</ulink> + </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 Wireshark 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 Wireshark 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> |