From 8931e0d12a3c8f214034112ab84dd3dccb2388d6 Mon Sep 17 00:00:00 2001 From: Gerald Combs Date: Tue, 30 May 2006 19:38:24 +0000 Subject: Ethereal -> Wireshark svn path=/trunk/; revision=18255 --- docbook/Makefile | 60 +- docbook/eth.css | 6 - docbook/eug_src/EUG_app_files.xml | 460 ------ docbook/eug_src/EUG_app_howitworks.xml | 106 -- docbook/eug_src/EUG_app_messages.xml | 101 -- docbook/eug_src/EUG_app_protocols.xml | 15 - docbook/eug_src/EUG_app_tools.xml | 967 ----------- docbook/eug_src/EUG_chapter_advanced.xml | 897 ----------- docbook/eug_src/EUG_chapter_build_install.xml | 754 --------- docbook/eug_src/EUG_chapter_capture.xml | 1033 ------------ docbook/eug_src/EUG_chapter_customize.xml | 827 ---------- docbook/eug_src/EUG_chapter_introduction.xml | 614 ------- docbook/eug_src/EUG_chapter_io.xml | 875 ---------- docbook/eug_src/EUG_chapter_statistics.xml | 508 ------ docbook/eug_src/EUG_chapter_troubleshoot.xml | 129 -- docbook/eug_src/EUG_chapter_use.xml | 2063 ------------------------ docbook/eug_src/EUG_chapter_work.xml | 1419 ---------------- docbook/eug_src/EUG_meta_info.xml | 38 - docbook/eug_src/EUG_preface.xml | 171 -- docbook/user-guide.xml | 34 +- docbook/ws.css | 6 + docbook/wsug_src/EUG_app_files.xml | 460 ++++++ docbook/wsug_src/EUG_app_howitworks.xml | 106 ++ docbook/wsug_src/EUG_app_messages.xml | 101 ++ docbook/wsug_src/EUG_app_protocols.xml | 15 + docbook/wsug_src/EUG_app_tools.xml | 967 +++++++++++ docbook/wsug_src/EUG_chapter_advanced.xml | 897 +++++++++++ docbook/wsug_src/EUG_chapter_build_install.xml | 754 +++++++++ docbook/wsug_src/EUG_chapter_capture.xml | 1033 ++++++++++++ docbook/wsug_src/EUG_chapter_customize.xml | 827 ++++++++++ docbook/wsug_src/EUG_chapter_introduction.xml | 614 +++++++ docbook/wsug_src/EUG_chapter_io.xml | 875 ++++++++++ docbook/wsug_src/EUG_chapter_statistics.xml | 508 ++++++ docbook/wsug_src/EUG_chapter_troubleshoot.xml | 129 ++ docbook/wsug_src/EUG_chapter_use.xml | 2063 ++++++++++++++++++++++++ docbook/wsug_src/EUG_chapter_work.xml | 1419 ++++++++++++++++ docbook/wsug_src/EUG_meta_info.xml | 38 + docbook/wsug_src/EUG_preface.xml | 171 ++ 38 files changed, 11030 insertions(+), 11030 deletions(-) delete mode 100644 docbook/eth.css delete mode 100644 docbook/eug_src/EUG_app_files.xml delete mode 100644 docbook/eug_src/EUG_app_howitworks.xml delete mode 100644 docbook/eug_src/EUG_app_messages.xml delete mode 100644 docbook/eug_src/EUG_app_protocols.xml delete mode 100644 docbook/eug_src/EUG_app_tools.xml delete mode 100644 docbook/eug_src/EUG_chapter_advanced.xml delete mode 100644 docbook/eug_src/EUG_chapter_build_install.xml delete mode 100644 docbook/eug_src/EUG_chapter_capture.xml delete mode 100644 docbook/eug_src/EUG_chapter_customize.xml delete mode 100644 docbook/eug_src/EUG_chapter_introduction.xml delete mode 100644 docbook/eug_src/EUG_chapter_io.xml delete mode 100644 docbook/eug_src/EUG_chapter_statistics.xml delete mode 100644 docbook/eug_src/EUG_chapter_troubleshoot.xml delete mode 100644 docbook/eug_src/EUG_chapter_use.xml delete mode 100644 docbook/eug_src/EUG_chapter_work.xml delete mode 100644 docbook/eug_src/EUG_meta_info.xml delete mode 100644 docbook/eug_src/EUG_preface.xml create mode 100644 docbook/ws.css create mode 100644 docbook/wsug_src/EUG_app_files.xml create mode 100644 docbook/wsug_src/EUG_app_howitworks.xml create mode 100644 docbook/wsug_src/EUG_app_messages.xml create mode 100644 docbook/wsug_src/EUG_app_protocols.xml create mode 100644 docbook/wsug_src/EUG_app_tools.xml create mode 100644 docbook/wsug_src/EUG_chapter_advanced.xml create mode 100644 docbook/wsug_src/EUG_chapter_build_install.xml create mode 100644 docbook/wsug_src/EUG_chapter_capture.xml create mode 100644 docbook/wsug_src/EUG_chapter_customize.xml create mode 100644 docbook/wsug_src/EUG_chapter_introduction.xml create mode 100644 docbook/wsug_src/EUG_chapter_io.xml create mode 100644 docbook/wsug_src/EUG_chapter_statistics.xml create mode 100644 docbook/wsug_src/EUG_chapter_troubleshoot.xml create mode 100644 docbook/wsug_src/EUG_chapter_use.xml create mode 100644 docbook/wsug_src/EUG_chapter_work.xml create mode 100644 docbook/wsug_src/EUG_meta_info.xml create mode 100644 docbook/wsug_src/EUG_preface.xml (limited to 'docbook') diff --git a/docbook/Makefile b/docbook/Makefile index a4a90a2426..08138bfd8d 100644 --- a/docbook/Makefile +++ b/docbook/Makefile @@ -12,15 +12,15 @@ FOP_OPTS=-Xmx256m # (comment this out, if you don't want pdf or don't have fop installed) # for win32 (cygwin) environments (as of fop-0.20 the cygwin script does # not use $FOP_OPTS) -FOP=fop-0.20.5/fop.bat +#FOP=fop-0.20.5/fop.bat # for unix like environments (if you have problems with fop, try to use an absolute path here) -#FOP="/usr/share/fop-0.20.5/fop.sh" +FOP="~/devel/fop-0.20.5/fop.sh" # One SUSE 9.1 and 9.2 uncomment the following line (make sure you have at least fop-0.20.5-71.2) #FOP=fop # html help compiler (Win32 only) # (comment this out, if you don't want chm or don't have hhc installed) -HHC="/cygdrive/c/Program Files/HTML Help Workshop/hhc.exe" +#HHC="/cygdrive/c/Program Files/HTML Help Workshop/hhc.exe" #HHC="true" # elinks (text version of release notes) @@ -41,23 +41,23 @@ XMLLINT="xmllint" FOP_OPTS="$(FOP_OPTS)" $(FOP) $< $@ EUG_FILES = \ - eug_src/EUG_app_files.xml \ - eug_src/EUG_app_howitworks.xml \ - eug_src/EUG_app_messages.xml \ - eug_src/EUG_app_protocols.xml \ - eug_src/EUG_app_tools.xml \ - eug_src/EUG_chapter_advanced.xml \ - eug_src/EUG_chapter_build_install.xml \ - eug_src/EUG_chapter_capture.xml \ - eug_src/EUG_chapter_customize.xml \ - eug_src/EUG_chapter_introduction.xml \ - eug_src/EUG_chapter_io.xml \ - eug_src/EUG_chapter_statistics.xml \ - eug_src/EUG_chapter_troubleshoot.xml \ - eug_src/EUG_chapter_use.xml \ - eug_src/EUG_chapter_work.xml \ - eug_src/EUG_meta_info.xml \ - eug_src/EUG_preface.xml + wsug_src/EUG_app_files.xml \ + wsug_src/EUG_app_howitworks.xml \ + wsug_src/EUG_app_messages.xml \ + wsug_src/EUG_app_protocols.xml \ + wsug_src/EUG_app_tools.xml \ + wsug_src/EUG_chapter_advanced.xml \ + wsug_src/EUG_chapter_build_install.xml \ + wsug_src/EUG_chapter_capture.xml \ + wsug_src/EUG_chapter_customize.xml \ + wsug_src/EUG_chapter_introduction.xml \ + wsug_src/EUG_chapter_io.xml \ + wsug_src/EUG_chapter_statistics.xml \ + wsug_src/EUG_chapter_troubleshoot.xml \ + wsug_src/EUG_chapter_use.xml \ + wsug_src/EUG_chapter_work.xml \ + wsug_src/EUG_meta_info.xml \ + wsug_src/EUG_preface.xml EUG_GRAPHICS = \ graphics/ethereal-3pane.png \ @@ -264,8 +264,8 @@ user-guide.html: $(EUG_SOURCE) mkdir -p eug_html/graphics/toolbar cp graphics/*.* eug_html/graphics cp graphics/toolbar/* eug_html/graphics/toolbar - cp eth.css eug_html - $(XSLTPROC) --stringparam base.dir eug_html/ --stringparam use.id.as.filename 1 --stringparam admon.graphics 1 --stringparam admon.graphics.path graphics/ --stringparam section.autolabel 1 --stringparam section.label.includes.component.label 1 --stringparam html.stylesheet eth.css --nonet http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl $< > eug_html/$@ + cp ws.css eug_html + $(XSLTPROC) --stringparam base.dir eug_html/ --stringparam use.id.as.filename 1 --stringparam admon.graphics 1 --stringparam admon.graphics.path graphics/ --stringparam section.autolabel 1 --stringparam section.label.includes.component.label 1 --stringparam html.stylesheet ws.css --nonet http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl $< > eug_html/$@ -chmod -R og+rX eug_html # create html chunked page files @@ -274,8 +274,8 @@ eug_html_chunked: $(EUG_SOURCE) mkdir -p eug_html_chunked/graphics/toolbar cp graphics/*.* eug_html_chunked/graphics cp graphics/toolbar/* eug_html_chunked/graphics/toolbar - cp eth.css eug_html_chunked - $(XSLTPROC) --stringparam base.dir eug_html_chunked/ --stringparam use.id.as.filename 1 --stringparam admon.graphics 1 --stringparam admon.graphics.path graphics/ --stringparam section.autolabel 1 --stringparam section.label.includes.component.label 1 --stringparam html.stylesheet eth.css --nonet http://docbook.sourceforge.net/release/xsl/current/html/chunk.xsl $< + cp ws.css eug_html_chunked + $(XSLTPROC) --stringparam base.dir eug_html_chunked/ --stringparam use.id.as.filename 1 --stringparam admon.graphics 1 --stringparam admon.graphics.path graphics/ --stringparam section.autolabel 1 --stringparam section.label.includes.component.label 1 --stringparam html.stylesheet ws.css --nonet http://docbook.sourceforge.net/release/xsl/current/html/chunk.xsl $< -chmod -R og+rX eug_html_chunked # create pdf file (through XSL-FO), portrait pages on US letter paper (the default) @@ -301,7 +301,7 @@ ifdef HHC mkdir -p eug_chm/graphics/toolbar -cp graphics/*.* eug_chm/graphics/ -cp graphics/toolbar/* eug_chm/graphics/toolbar/ - $(XSLTPROC) --stringparam base.dir eug_chm/ --stringparam use.id.as.filename 1 --stringparam admon.graphics 1 --stringparam admon.graphics.path graphics/ --stringparam section.autolabel 1 --stringparam section.label.includes.component.label 1 --stringparam html.stylesheet eth.css --nonet http://docbook.sourceforge.net/release/xsl/current/htmlhelp/htmlhelp.xsl $< + $(XSLTPROC) --stringparam base.dir eug_chm/ --stringparam use.id.as.filename 1 --stringparam admon.graphics 1 --stringparam admon.graphics.path graphics/ --stringparam section.autolabel 1 --stringparam section.label.includes.component.label 1 --stringparam html.stylesheet ws.css --nonet http://docbook.sourceforge.net/release/xsl/current/htmlhelp/htmlhelp.xsl $< -$(HHC) htmlhelp.hhp -mv htmlhelp.chm $@ -rm -r htmlhelp.hhp @@ -322,8 +322,8 @@ developer-guide.html: $(EDG_SOURCE) @ echo --- EDG - HTML SINGLE PAGE --- mkdir -p edg_html/edg_graphics cp edg_graphics/* edg_html/edg_graphics - cp eth.css edg_html - $(XSLTPROC) --stringparam base.dir edg_html/ --stringparam use.id.as.filename 1 --stringparam admon.graphics 1 --stringparam admon.graphics.path edg_graphics/ --stringparam section.autolabel 1 --stringparam section.label.includes.component.label 1 --stringparam html.stylesheet eth.css --nonet http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl $< > edg_html/$@ + cp ws.css edg_html + $(XSLTPROC) --stringparam base.dir edg_html/ --stringparam use.id.as.filename 1 --stringparam admon.graphics 1 --stringparam admon.graphics.path edg_graphics/ --stringparam section.autolabel 1 --stringparam section.label.includes.component.label 1 --stringparam html.stylesheet ws.css --nonet http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl $< > edg_html/$@ -chmod -R og+rX edg_html # create html chunked page files @@ -332,8 +332,8 @@ edg_html_chunked: $(EDG_SOURCE) mkdir -p edg_html_chunked mkdir -p edg_html_chunked/edg_graphics cp edg_graphics/* edg_html_chunked/edg_graphics - cp eth.css edg_html_chunked - $(XSLTPROC) --stringparam base.dir edg_html_chunked/ --stringparam use.id.as.filename 1 --stringparam admon.graphics 1 --stringparam admon.graphics.path edg_graphics/ --stringparam section.autolabel 1 --stringparam section.label.includes.component.label 1 --stringparam html.stylesheet eth.css --nonet http://docbook.sourceforge.net/release/xsl/current/html/chunk.xsl $< + cp ws.css edg_html_chunked + $(XSLTPROC) --stringparam base.dir edg_html_chunked/ --stringparam use.id.as.filename 1 --stringparam admon.graphics 1 --stringparam admon.graphics.path edg_graphics/ --stringparam section.autolabel 1 --stringparam section.label.includes.component.label 1 --stringparam html.stylesheet ws.css --nonet http://docbook.sourceforge.net/release/xsl/current/html/chunk.xsl $< -chmod -R og+rX edg_html_chunked # create pdf file (through XSL-FO), portrait pages on US letter paper (the default) @@ -358,7 +358,7 @@ ifdef HHC @ echo --- EDG - MICROSOFT HTML HELP --- mkdir -p edg_chm/edg_graphics cp edg_graphics/* edg_chm/edg_graphics - $(XSLTPROC) --stringparam base.dir edg_chm/ --stringparam use.id.as.filename 1 --stringparam admon.graphics 1 --stringparam admon.graphics.path edg_graphics/ --stringparam section.autolabel 1 --stringparam section.label.includes.component.label 1 --stringparam html.stylesheet eth.css --nonet http://docbook.sourceforge.net/release/xsl/current/htmlhelp/htmlhelp.xsl $< + $(XSLTPROC) --stringparam base.dir edg_chm/ --stringparam use.id.as.filename 1 --stringparam admon.graphics 1 --stringparam admon.graphics.path edg_graphics/ --stringparam section.autolabel 1 --stringparam section.label.includes.component.label 1 --stringparam html.stylesheet ws.css --nonet http://docbook.sourceforge.net/release/xsl/current/htmlhelp/htmlhelp.xsl $< -$(HHC) htmlhelp.hhp -mv htmlhelp.chm $@ -rm -r htmlhelp.hhp diff --git a/docbook/eth.css b/docbook/eth.css deleted file mode 100644 index 3fb57fc987..0000000000 --- a/docbook/eth.css +++ /dev/null @@ -1,6 +0,0 @@ -div.sidebar { - background-color: #DDDDDD; - border: 1px solid black; - margin: 6px; - padding: 0px 6px 0px 6px; -} \ No newline at end of file diff --git a/docbook/eug_src/EUG_app_files.xml b/docbook/eug_src/EUG_app_files.xml deleted file mode 100644 index 19ec579e27..0000000000 --- a/docbook/eug_src/EUG_app_files.xml +++ /dev/null @@ -1,460 +0,0 @@ - - - - - Configuration (and other) Files and Folders - - 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. - - Tip - A list of the folders Ethereal actually uses can be found under the - Folders tab in the dialog box coming up, when you select - About Ethereal from the Help menu. - - - - 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. - - - Configuration files and folders overview - - - - - - - File/Folder - Description - Unix/Linux folders - Windows folders - - - - - preferences - Settings from the Preferences dialog box. - /etc/ethereal.conf, $HOME/.ethereal/preferences - %ETHEREAL%\ethereal.conf, %APPDATA%\Ethereal\preferences - - - recent - Recent GUI settings (e.g. recent files lists). - $HOME/.ethereal/recent - %APPDATA%\Ethereal\recent - - - cfilters - Capture filters. - $HOME/.ethereal/cfilters - %ETHEREAL%\cfilters, %APPDATA%\Ethereal\cfilters - - - dfilters - Display filters. - $HOME/.ethereal/dfilters - %ETHEREAL%\dfilters, %APPDATA%\Ethereal\dfilters - - - colorfilters - Coloring rules. - $HOME/.ethereal/colorfilters - %ETHEREAL%\colorfilters, %APPDATA%\Ethereal\colorfilters - - - disabled_protos - Disabled protocols. - $HOME/.ethereal/disabled_protos - %ETHEREAL%\disabled_protos, %APPDATA%\Ethereal\disabled_protos - - - ethers - Ethernet name resolution. - /etc/ethers, $HOME/.ethereal/ethers - %ETHEREAL%\ethers, %APPDATA%\Ethereal\ethers - - - manuf - Ethernet name resolution. - /etc/manuf - %ETHEREAL%\manuf - - - hosts - IPv4 and IPv6 name resolution. - $HOME/.ethereal/hosts - %APPDATA%\hosts - - - ipxnets - IPX name resolution. - $HOME/.ethereal/ipxnets - %ETHEREAL%\ipxnets - - - plugins - Plugin directories. - /usr/share/ethereal/plugins, - /usr/local/share/ethereal/plugins, - $HOME/.ethereal/plugins - - %ETHEREAL%\plugins\<version>, - %APPDATA%\Ethereal\plugins - - - temp - Temporary files. - Environment: TMPDIR - Environment: TMPDIR or TEMP - - - -
- Windows folders - - %APPDATA% points to the personal configuration folder, typically - C:\Documents and Settings\<username>\Application Data - (for further details, have a look at ), - %ETHEREAL% points to the Wireshark program folder, typically - C:\Program Files\Ethereal - - - Unix/Linux folders - - The /etc folder is the global Ethereal configuration - folder. The folder actually used on your system - may vary, maybe something like: /usr/local/etc. - - - - - - preferences/ethereal.conf - - - This file contains your Ethereal preferences, - including defaults for capturing and displaying packets. - It is a simple text file containing statements of the form: - -variable: value - - 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. - - - - - recent - - - 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: - -variable: value - - It is read at program start and written at program exit. - - - - cfilters - - - 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: - -"<filter name>" <filter string> - - 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. - - - - dfilters - - - 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: - -"<filter name>" <filter string> - - 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. - - - - - colorfilters - - - 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: - -@<filter name>@<filter string> -@[<bg RGB(16-bit)>][<fg RGB(16-bit)>] - - - - 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. - - - - - disabled_protos - - - Each line in this file specifies a disabled protocol name. The - following are some examples: - -tcp -udp - - - - 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. - - - - - - ethers - - - - When Wireshark is trying to translate Ethernet hardware - addresses to names, it consults the files listed in - . - If an address is not found in /etc/ethers, - Ethereal looks in $HOME/.ethereal/ethers - - - 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: - -ff-ff-ff-ff-ff-ff Broadcast -c0-00-ff-ff-ff-ff TR_broadcast -00.2b.08.93.4b.a1 Freds_machine - - The settings from this file are read in at program start and never - written by Wireshark. - - - - - manuf - - - Ethereal uses the files listed in - 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. - - - An example is: - -00:00:01 Xerox # XEROX CORPORATION - - - - The settings from this file are read in at program start and never - written by Wireshark. - - - - - hosts - - - Ethereal uses the files listed in - to translate IPv4 and IPv6 addresses into names. - - - This file has the same format as the usual /etc/hosts file in unix systems. - - - An example is: - -# Comments must be prepended by the # sign! -192.168.0.1 homeserver - - - - The settings from this file are read in at program start and never - written by Wireshark. - - - - - ipxnets - - - Ethereal uses the files listed in - to translate IPX network numbers into names. - - - An example is: - -C0.A8.2C.00 HR -c0-a8-1c-00 CEO -00:00:BE:EF IT_Server1 -110f FileServer3 - - - - The settings from this file are read in at program start and never - written by Wireshark. - - - - - plugins folder - - - Ethereal searches for plugins in the directories listed in - . - They are searched in the order listed. - - - - - temp folder - - - If you start a new capture and don't specify a filename for it, - Ethereal uses this directory to place that file in, see - . - - - - - - -
Windows folders - - Here you will find some details about the folders used in Wireshark - on different Windows versions. - - - As already mentioned, you can find the currently used folders in the - About Ethereal dialog. - - -
Windows profiles - - 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. - - Note! - - 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. - - - - The following will try to guide - you to the right place where to look for Wiresharks profile data. - - - - - 95/98/ME - - - The default in Windows 95/98/ME is: all users work with the same profile, - which is located at: - C:\windows\Application Data\Ethereal - - - - - 98/ME (with enabled user profiles) - - - In Windows 98 and ME you can enable separate user profiles. In that case, - something like: - C:\windows\Profiles\<username>\Application Data\Ethereal - is used. - - - - - NT 4 - - - C:\WINNT\Profiles\<username>\Application Data\Ethereal - - - - - 2000/XP - - - C:\Documents and Settings\<username>\Application Data, - "Documents and Settings" and "Application Data" might be internationalized. - - - - - -
- -
- Windows NT/2000/XP roaming profiles - - 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. - - - 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. - - - There is an exception to this: The "Local Settings" folder in your profile - data (typically something like: - C:\Documents and Settings\<username>\Local Settings) - will not be transferred to the domain server. This is the default for - temporary capture files. - -
- -
- Windows temporary folder - - Ethereal uses the folder which is set by the TMPDIR or TEMP environment - variable. This variable will be set by the windows installer. - - - The default location for temporary files on NT 4 is just - C:\TEMP, and in 2000 the default location - is some directory under your profile directory but it might have - "Temporary Files" in the path name. - -
- -
- - - diff --git a/docbook/eug_src/EUG_app_howitworks.xml b/docbook/eug_src/EUG_app_howitworks.xml deleted file mode 100644 index 83e33beeff..0000000000 --- a/docbook/eug_src/EUG_app_howitworks.xml +++ /dev/null @@ -1,106 +0,0 @@ - - - - - How Ethereal Works - - 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. - - -
Program start - - When Etheral starts, a lot of things are done: - - - initialize the dissectors (register the protocol tree), including plugins - - - load and set values from the preferences file - - - load the capture filters from the cfilters file - - - load the display filters from the dfilters file - - - load and set the disabled protocols from the disabled_protos file - - - init libpcap/winpcap (the capturing engine) - - - process command line parameters - - - load and set the recently used GUI settings from the recent file - - - init and show the main screen - - - if specified by command line, load a capture file or start capturing - - - - - - -
- -
Protocol dissectors - - 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. - - - So Ethereal will dissect a packet from the lowest to the highest protocol - layers. - - - But how does Ethereal know, which dissector to choose? - - - 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: - - - static 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). - - - heuristic 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. - - - - - 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. - - - You can control the way how Ethereal calls it's dissectors, see for details. - -
- - - diff --git a/docbook/eug_src/EUG_app_messages.xml b/docbook/eug_src/EUG_app_messages.xml deleted file mode 100644 index a0631e7d2a..0000000000 --- a/docbook/eug_src/EUG_app_messages.xml +++ /dev/null @@ -1,101 +0,0 @@ - - - - - Ethereal Messages - - 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. - -
Packet List Messages - - These messages might appear in the packet list. - -
[Malformed Packet] - - Malformed packet means that the protocol dissector can't work out the - contents of the packet any further. This can have various reasons: - - - - Wrong dissector - 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. - - - - - Packet not reassembled - The packet is longer than a single frame and it is not reassembled, - see for further details. - - - - - Packet is malformed - The packet is actually wrong (malformed), meaning that a part of the - packet is just not as expected (not following the protocol - specifications). - - - - - Dissector is buggy - The corresponding protocol dissector is simply buggy or still - incomplete. - - - - - - 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. - -
-
[Packet size limited during capture] - - The packet size was limited during capture, see "Limit each packet to n - bytes" at the . - 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. - -
-
- -
Packet Details Messages - - These messages might appear in the packet details. - -
[Response in frame: 123] - - 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. - -
-
[Request in frame: 123] - - Same as "Response in frame: 123" above, but the other way round. - -
-
[Time from request: 0.123 seconds] - - The time between the request and the response packets. - -
-
- - - diff --git a/docbook/eug_src/EUG_app_protocols.xml b/docbook/eug_src/EUG_app_protocols.xml deleted file mode 100644 index 4e8a9a787c..0000000000 --- a/docbook/eug_src/EUG_app_protocols.xml +++ /dev/null @@ -1,15 +0,0 @@ - - - - - Protocols and Protocol Fields - - Ethereal distinguishes between protocols (e.g. tcp) and protocol fields - (e.g. tcp.port). - - - A comprehensive list of all protocols and protocol fields can be found - at: &EtherealProtocolsPage; - - - diff --git a/docbook/eug_src/EUG_app_tools.xml b/docbook/eug_src/EUG_app_tools.xml deleted file mode 100644 index 4c9364dac4..0000000000 --- a/docbook/eug_src/EUG_app_tools.xml +++ /dev/null @@ -1,967 +0,0 @@ - - - - - - Related command line tools - -
- Introduction - - 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. - -
- -
- <command>tcpdump</command>: Capturing with tcpdump for viewing - with Ethereal - - There are occasions when you want to capture packets using - tcpdump rather than ethereal, - 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). - - - However, the default tcpdump parameters result in a - capture file where each packet is truncated, because - tcpdump, by default, does only capture the first 68 - bytes of each packet. - - - To ensure that you capture complete packets, use the following command: - -tcpdump -i <interface> -s 1500 -w <some-file> - - You will have to specify the correct interface and - the name of a file to save into. In addition, - you will have to terminate the capture with ^C when you believe you - have captured enough packets. - - Note! - - tcpdump is not part of the Wireshark distribution. You can get it from: - http://www.tcpdump.org for various - platforms. - - -
- -
- <command>tethereal</command>: Terminal-based Ethereal - - Tethereal 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 ethereal. For more - information on tethereal, see the manual pages - (man tethereal). - -
- -
- <command>capinfos</command>: Print information about capture files - - - Included with Wireshark is a small utility called - capinfos, which is a command-line utility to - print information about binary capture files. - - - - Help information available from capinfos - -$ 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 - - - -
- -
- <command>editcap</command>: Edit capture files - - Included with Wireshark is a small utility called - editcap, 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. - - - - - Help information available from editcap - -$ 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 - - - - Where each option has the following meaning: - - -r - - - This option specifies that the frames listed should be kept, - not deleted. The default is to delete the listed frames. - - - - -h - This option provides help. - - -v - - - This option specifies verbose operation. The default is - silent operation. - - - - -T {encap type} - - - This option specifies the frame encapsulation type to use. - - - It is mainly for converting funny captures to something - that Ethereal can deal with. - - - The default frame - encapsulation type is the same as the input encapsulation. - - - - - -F {capture type} - - - This option specifies the capture file format to write - the output file in. - - - The default is libpcap format. - - - - -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. - - - - {infile} - - - This parameter specifies the input file to use. It must be - present. - - - - {outfile} - - - This parameter specifies the output file to use. It must - be present. - - - - - [record#[-][record# ...]] - - - This optional parameter specifies the records to include - or exclude (depending on the -r option. - You can specify individual records or a range of records. - - - - - -
- -
- <command>mergecap</command>: - Merging multiple capture files into one - - - 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. - - - 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. - - - 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. - - - 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). - - - - 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). - - - Help information available from mergecap - -$ 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 - - - - -h - - Prints the version and options and exits. - - - -v - - - Causes mergecap to print a number of messages - while it's working. - - - - -a - - - 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 -a 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. - - - - -s - - Sets the snapshot length to use when writing the data. - - - -w - - Sets the output filename. - - - -T - - - Sets the packet encapsulation type of the output capture file. - - - - -F - - Sets the file format of the output capture file. - - - - - A simple example merging dhcp-capture.libpcap - and imap-1.libpcap into - outfile.libpcap is shown below. - - - Simple example of using mergecap - $ mergecap -w outfile.libpcap dhcp-capture.libpcap imap-1.libpcap - - -
- -
- <command>text2pcap</command>: Converting ASCII hexdumps to network - captures - - - There may be some occasions when you wish to convert a hex dump of some - network traffic into a libpcap file. - - Text2pcap 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. - - - 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: - - -000000 00 e0 1e a7 05 6f 00 10 ........ -000008 5a a0 b9 12 08 00 46 00 ........ -000010 03 68 00 00 00 00 0a 2e ........ -000018 ee 33 0f 19 08 7f 0f 19 ........ -000020 03 80 94 04 00 00 10 01 ........ -000028 16 a2 0a 00 03 50 00 0c ........ -000030 01 01 0f 19 03 80 11 01 ........ - - - There is no limit on the width or number of bytes per line. Also the - text dump at the end of the line is ignored. 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.) - - - 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. - - - 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. - - - Help information available for text2pcap - -$ 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. - - - - -w <filename> - - - Write the capture file generated by text2pcap - to <filename>. The default is to write to standard - output. - - - - -h - - Display the help message - - - -d - - - Displays debugging information during the process. Can be - used multiple times to generate more debugging information. - - - - -q - - Be completely quiet during the process. - - - -o hex|oct - - Specify the radix for the offsets (hex or octal). Defaults to - hex. This corresponds to the -A option for od. - - - - -l - - - 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. - - - - -e l3pid - - - 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. - - - 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. - - - - -u srcport destport - - - 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. - - - - -
- -
- <command>idl2eth</command>: - Creating dissectors from Corba IDL files - - - 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. - -
- What is it? - - As you have probably guessed from the name, - idl2eth 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. - - - idl2eth 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. - - It consists of 4 main files. - - README.idl2eth - - This document - - - ethereal_be.py - - The main compiler backend - - - ethereal_gen.py - - A helper class, that generates the C code. - - - idl2eth - - A simple shell script wrapper that the end user should - use to generate the dissector from the IDL file(s). - - - -
-
- Why do this? - - 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. - - - 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". - - - It is also COOL to work on a great Open Source project such as - the case with "Ethereal" ( - http://www.ethereal.com - ) - -
-
How to use idl2eth - - To use the idl2eth to generate ethereal dissectors, you - need the following: - - - Prerequisites to using idl2eth - - - Python must be installed. See - - - - - - omniidl from the the omniORB package must be available. See - - - - - - Of course you need ethereal installed to compile the - code and tweak it if required. idl2eth is part of the - standard Ethereal distribution - - - - - To use idl2eth to generate an ethereal dissector from an idl file - use the following procedure: - - - - Procedure for converting a Corba idl file into an ethereal - dissector - - - - To write the C code to stdout. - idl2eth <your file.idl> - eg: idl2eth echo.idl - - - - - To write to a file, just redirect the output. - idl2eth echo.idl > packet-test-idl.c - You may wish to comment out the register_giop_user_module() code - and that will leave you with heuristic dissection. - - - - - If you don't want to use the shell script wrapper, then try - steps 3 or 4 instead. - - - To write the C code to stdout. - Usage: omniidl -p ./ -b ethereal_be <your file.idl> - eg: - omniidl -p ./ -b ethereal_be echo.idl - - - - - To write to a file, just redirect the output. - omniidl -p ./ -b ethereal_be echo.idl > packet-test-idl.c - You may wish to comment out the register_giop_user_module() code - and that will leave you with heuristic dissection. - - - - - Copy the resulting C code to your ethereal src directory, - edit the 2 make files to include the packet-test-idl.c - -cp packet-test-idl.c /dir/where/ethereal/lives/ -edit Makefile.am -edit Makefile.nmake - - - - - Run configure - ./configure (or ./autogen.sh) - - - - Compile the code - make - - - - Good Luck !! - - -
-
TODO - - - - Exception code not generated (yet), but can be added manually. - - - - - Enums not converted to symbolic values (yet), but can be added - manually. - - - - Add command line options etc - - - More I am sure :-) - - -
-
Limitations - - See the TODO list inside packet-giop.c - -
-
Notes - - - - 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. - - - - - 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/ - - - -
-
- - - - diff --git a/docbook/eug_src/EUG_chapter_advanced.xml b/docbook/eug_src/EUG_chapter_advanced.xml deleted file mode 100644 index db04444142..0000000000 --- a/docbook/eug_src/EUG_chapter_advanced.xml +++ /dev/null @@ -1,897 +0,0 @@ - - - - - - Advanced Topics - -
Introduction - - In this chapter some of the advanced features of Ethereal will be described. - -
- -
Following TCP streams - - 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. - - - 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 . - - - Note! - - It is worthwhile noting that Follow TCP Stream installs a display filter - to select all the packets in the TCP stream you have selected. - - -
The "Follow TCP Stream" dialog box -
- The "Follow TCP Stream" dialog box - -
- - 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. - - - None printable characters will be replaced by dots. - XXX - What about line wrapping (maximum line length) and CRNL conversions? - - - The stream content won't be updated while doing a live capture. - To get the latest content you'll have to reopen the dialog. - - - You can choose from the following actions: - - - - Save As Save the stream data in the currently - selected format. - - - - - Print Print the stream data in the currently - selected format. - - - - - Direction Choose the stream direction to be - displayed ("Entire conversation", "data from A to B only" or "data - from B to A only"). - - - - - Filter out this stream Apply a display filter - removing the current TCP stream data from the display. - - - - - Close Close this dialog box, leaving the current - display filter in effect. - - - - - - You can choose to view the data in one of the following formats: - - - - ASCII. In this view you see the data from - each direction in ASCII. Obviously best for ASCII based protocols, - e.g. HTTP. - - - - - EBCDIC. For the big-iron freaks out there. - - - - - HEX Dump. This allows you to see all the - data. - This will require a lot of screen space and is best used with - binary protocols. - - - - - C Arrays. This allows you to import the stream data - into your own C program. - - - - - Raw. 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. - - - - -
-
- -
Time Stamps - - 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. - - - 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. - - - 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. - -
Ethereal internals - - 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 - for details. - - - While reading or writing capture files, Ethereal converts the time stamp - data between the capture file format and the internal format as required. - - - 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. - -
-
Capture file formats - - 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). - - - 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. - - - Note! - - 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. - - -
-
Accuracy - - 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! - - 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. - - - 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?) - - - -
-
- -
Time Zones - - 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 ;-) - - - First of all, there are two reasons why you may not need to think about - time zones at all: - - - - 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). - - - - - 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. - - - - - What are time zones? - - 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. - - - For that reason, the earth is split into several different time zones, - each zone with a local time that corresponds to the local sunset. - - - 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! - - - 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". - - - 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)! - - - Further information can be found at: - &WikipediaTimezone; and - &WikipediaUTC;. - - - - What is daylight saving time (DST)? - - 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". - - - 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). - - - Keep in mind: UTC remains the same all year around, regardless of DST! - - - Further information can be found at: - &WikipediaDaylightSaving;. - - - - Further time zone and DST information can be found at: - &TimezoneGMTSite; and - &TimezoneWorldClockSite;. - -
Set your computer's time correct! - - If you work with people around the world, it's very helpful to set your - computer's time and time zone right. - - - You should set your computers time and time zone in the correct sequence: - - - - Set your time zone to your current location - - - - - Set your computer's clock to the local time - - - - This way you will tell your computer both the local time and also the time - offset to UTC. - Tip! - - 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! - - - Tip! - - 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: - &NTPSite;. - - - -
-
Ethereal and Time Zones - - So what's the relationship between Ethereal and time zones anyway? - - - 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. - - - 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. - - - 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. - - - 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. - - - - Time zone examples for UTC arrival times (without DST) - - - - - - Los Angeles - New York - Madrid - London - Berlin - Tokyo - - - - - Capture File (UTC) - 10:00 - 10:00 - 10:00 - 10:00 - 10:00 - 10:00 - - - Local Offset to UTC - -8 - -5 - -1 - 0 - +1 - +9 - - - Displayed Time (Local Time) - 02:00 - 05:00 - 09:00 - 10:00 - 11:00 - 19:00 - - - -
- - - 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. - - - 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. - - - Conclusion: 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. - -
-
- -
Packet Reassembling -
What is it? - - 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. - - - 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. - - Tip! - - Ethereal calls this mechanism reassembling, although a specific protocol - specification might use a different term for this (e.g. desegmentation, - defragmentation, ...). - - -
-
How Ethereal handles it - - 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 ). - - -
- The "Packet Bytes" pane with a reassembled tab - -
- - - Note! - - Reassembling might take place at several protocol layers, so it's possible - that multiple tabs in the "Packet Bytes" pane appear. - - - Note! - - You will find the reassembled data in the last packet of the chunk. - - - - An example: - In a HTTP 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. - - - 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. - - - The enabling or disabling of the reassemble settings of a protocol typically - requires two things: - - - - the lower level protocol (e.g., TCP) must support - reassembly. Often this reassembly can be enabled or disabled - via the protocol preferences. - - - - - 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. - - - - - - The tooltip of the higher level protocol setting will note you if and - which lower level protocol setting has to be considered too. - -
-
- -
Name Resolution - - 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 . - - - The name resolution feature can be en-/disabled separately for the - protocol layers of the following sections. - - -
Name Resolution drawbacks - - Name resolution can be invaluable while working with Ethereal and may - save you even hours of work. Unfortunately, it also has it's drawbacks. - - - - - Name resolution will often fail. 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. - - - - - The resolved names are not stored in the capture file or - somewhere else. - So the resolved names might not be available if you open the capture file - later or on 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). - - - - - DNS may add additional packets to your capture file. - 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? - - - - - Resolved DNS names are cached by Wireshark. - 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? - - - - Tip! - - 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. - - -
- -
Ethernet name resolution (MAC layer) - - Try to resolve an Ethernet MAC address (e.g. 00:09:5b:01:02:03) to - something more "human readable". - - ARP name resolution (system service) - 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). - - Ethernet codes (ethers file) - 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). - - Ethernet manufacturer codes (manuf file) - 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). - -
- -
IP name resolution (network layer) - - Try to resolve an IP address (e.g. 65.208.228.223) to - something more "human readable". - - DNS/ADNS name resolution (system/library service) - 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). - - - Warning! - - 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. - - - - DNS vs. ADNS - 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. - - - 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. - - hosts name resolution (hosts file) - 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). - -
- -
IPX name resolution (network layer) - ipxnet name resolution (ipxnets file) - XXX - add ipxnets name resolution explanation. - -
- -
TCP/UDP port name resolution (transport layer) - - Try to resolve a TCP/UDP port (e.g. 80) to - something more "human readable". - - TCP/UDP port conversion (system service) - Ethereal will ask the operating system to convert a TCP or UDP port to - its well known name (e.g. 80 -> http). - - - XXX - mention the role of the /etc/services file - (but don't forget the files and folders section)! - -
-
- -
Checksums - - Several network protocols use checksums to ensure data integrity. - - Tip! - - Applying checksums as described here is also known as - redundancy check. - - - What are checksums for? - - 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. - - - 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. - - - 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. - - - Some checksum algorithms are able to recover (simple) errors by - calculating where the expected error must be and repairing it. - - - 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). - - - 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. - - - 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. - - - Further information about checksums can be found at: - . - - -
Ethereal checksum validation - - Ethereal will validate the checksums of several potocols, e.g.: IP, TCP, ... - - - 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. - - - Checksum validation can be switched off for various protocols in the - Ethereal protocol preferences, e.g. to (very slightly) increase - performance. - - - 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. - -
- -
Checksum offloading - - The checksum calculation might be done by the network driver, protocol - driver or even in hardware. - - - 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. - - - Higher level checksums are "traditionally" calculated by the protocol - implementation and the completed packet is then handed over to the - hardware. - - - 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. - - Note! - - 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. - - - - 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. - - - You can do two things to avoid this checksum offloading problem: - - - - Turn off the checksum offloading in the network driver, if this option is - available. - - - - - Turn off checksum validation of the specific protocol in the Wireshark - preferences. - - - - -
-
- - - - diff --git a/docbook/eug_src/EUG_chapter_build_install.xml b/docbook/eug_src/EUG_chapter_build_install.xml deleted file mode 100644 index 2613270660..0000000000 --- a/docbook/eug_src/EUG_chapter_build_install.xml +++ /dev/null @@ -1,754 +0,0 @@ - - - - - Building and Installing Ethereal -
- Introduction - - As with all things, there must be a beginning, and so it is with - Ethereal. To use Ethereal, you must: - - - - Obtain a binary package for your operating system, or - - - - - Obtain the source and build Ethereal for your operating system. - - - - - - 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. - - - This chapter shows you how to obtain source and binary packages, - and how to build Ethereal from source, should you choose to do so. - - - The following are the general steps you would use: - - - - Download the relevant package for your needs, e.g. source or - binary distribution. - - - - - Build the source into a binary, if you have downloaded the - source. - - - This may involve building and/or installing other necessary packages. - - - - - Install the binaries into their final destinations. - - - - -
- -
- Obtaining the source and binary distributions - - You can obtain both source and binary distributions from the Wireshark - web site: &EtherealWebSite;. - 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. - - - Download all required files! - - 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. - - - - Once you have downloaded the relevant files, you can go on to the - next step. - - - Note! - - 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. - - - For this reason, you might want to pull down the source distribution - and build it, as the process is relatively simple. - - -
- -
- Before you build <application>Ethereal</application> under UNIX - - Before you build Ethereal from sources, or install a binary package, - you must ensure that you have the following other packages installed: - - - GTK+, The GIMP Tool Kit. - - You will also need Glib. Both can be obtained from - www.gtk.org - - - - - libpcap, the packet capture software that Ethereal uses. - - - You can obtain libpcap from - www.tcpdump.org - - - - 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. - - - If you have downloaded the source for GTK+, the instructions shown - in may provide some help in building it: - - Building GTK+ from source - -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> - - - - Note! - - You may need to change the version number of gtk+ in - 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, - tar xvf - will show you the name of the - directory you should change to. - - - - Note! - - If you use Linux, or have GNU tar installed, - you can use tar zxvf gtk+-1.2.10.tar.gz. It - is also possible to use gunzip -c or - gzcat rather than gzip -dc - on many UNIX systems. - - - - Note! - - If you downloaded gtk+ or any other tar file using Windows, - you may find your file called gtk+-1_2_8_tar.gz. - - - - - You should consult the GTK+ web site if any errors occur in carrying - out the instructions in . - - - If you have downloaded the source to libpcap, the general instructions - shown in will assist in building it. Also, - if your operating system does not support tcpdump, - you might also want to download it from the - tcpdump web site and - install it. - - Building and installing libpcap - -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> - - - - - Note! - - The directory you should change to will depend on the version of - libpcap you have downloaded. In all cases, - tar xvf - will show you the name of the - directory that has been unpacked. - - - - When installing the include files, you might get the error shown - in when you submit the command - make install-incl. - - Errors while installing the libpcap include files - -/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 - - - If you do, simply create the missing directory with the following - command: - -mkdir /usr/local/include/net - - and rerun the command make install-incl. - - - 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 - will install all the needed RPMs if they are not already installed. - - - Installing required RPMs under RedHat Linux 6.2 and beyond - - -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 - - - - - - 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. - - - - Under Debian you can install Ethereal using apt-get. apt-get will - handle any dependency issues for you. shows - how to do this. - - Installing debs under Debian - -apt-get install ethereal - - - -
- -
- Building Ethereal from source under UNIX - - Use the following general steps if you are building Ethereal from - source under a UNIX operating system: - - - - Unpack the source from its gzip'd - tar file. If you are using Linux, or your - version of UNIX uses GNU tar, you can use the - following command: - -tar zxvf ethereal-&EtherealCurrentVersion;-tar.gz - - - - For other versions of UNIX, You will want to use the following - commands: - -gzip -d ethereal-&EtherealCurrentVersion;-tar.gz -tar xvf ethereal-&EtherealCurrentVersion;-tar - - - Note! - - The pipeline - - gzip -dc ethereal-&EtherealCurrentVersion;-tar.gz | tar xvf - - will work here as well. - - - - Note! - - 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. - - - - - - - Change directory to the Wireshark source directory. - - - - - Configure your source so it will build correctly for your - version of UNIX. You can do this with the following command: - -./configure - - - - If this step fails, you will have to rectify the problems and - rerun configure. Troubleshooting hints are - provided in . - - - - - Build the sources into a binary, with the make - command. For example: - -make - - - - - - Install the software in its final destination, using the command: - -make install - - - - - - - Once you have installed Ethereal with make install - above, you should be able to run it by entering - ethereal. - -
- -
- Installing the binaries under UNIX - - 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 smit to - install the Wireshark binary package, while under Tru64 UNIX - (formerly Digital UNIX) you would use setld. - - -
- Installing from rpm's under RedHat and alike - - Use the following command to install the Wireshark RPM that you have - downloaded from the Wireshark web site: - -rpm -ivh ethereal-0.10.5-0.2.2.i386.rpm - - If the above step fails because of missing dependencies, install the - dependencies first, and then retry the step above. See - for information on what RPMs you will need - to have installed. - -
- -
- Installing from deb's under Debian - - Use the following command to install Ethereal under Debian: - -apt-get install ethereal - - apt-get should take care of all of the dependency issues for you. - -
-
- -
- Troubleshooting during the install on Unix - - A number of errors can occur during the installation process. - Some hints on solving these are provided here. - - - If the configure stage fails, you will need to find - out why. You can check the file config.log in the - source directory to find out what failed. The last few lines of this - file should help in determining the problem. - - - 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 - configure will also fail if you do not have libpcap - (at least the required include files) on your system. - - - Another common problem is for the final compile and link stage to - terminate with a complaint of: Output too long. - This is likely to be caused by an antiquated sed - (such as the one shipped with Solaris). Since sed is - used by the libtool script to construct the final - link command, this leads to mysterious problems. This can be - resolved by downloading a recent version of sed from - . - - - If you cannot determine what the problems are, send mail to the - ethereal-dev mailing list explaining your problem, - and including the output from config.log and - anything else you think is relevant, like a trace of the - make stage. - -
- -
- Building from source under Windows - - It is recommended to use the binary installer for Windows, - until you want to start developing Ethereal on the Windows platform. - - - For further information how to build Ethereal for Windows from the - sources, have a look at the Development Wiki: - http://wiki.ethereal.com/Development - for the latest available development documentation. - -
- -
- Installing Ethereal under Windows - - In this section we explore installing Ethereal under Windows from the - binary packages. - -
- Install Ethereal - - You may acquire a binary installer of Ethereal named something like: - ethereal-setup-x.y.z.exe. - - - Simply download the Wireshark installer from: - &EtherealBinariesPage; - and execute it. - - Note! - - 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 line options - - You can simply start the Wireshark installer without any command line - parameters, it will show you the usual interactive installer. - - - There are some command line parameters available: - - - - - /NCRC disables the CRC check - - - - - /S runs the installer or uninstaller silently with - default values. Please note: The silent installer won't install WinPCap! - - - - - /desktopicon installation of the desktop icon, - =yes - force installation, =no - - don't install, otherwise use defaults / user settings. - This option is available since 0.10.13 an can be useful for a silent - installer. - - - - - /quicklaunchicon installation of the quick launch icon, - =yes - force installation, =no - - don't install, otherwise use defaults / user settings. - This option is available since 0.10.13 an can be useful for a silent - installer. - - - - - /D 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. - - - - Example: - -ethereal-setup-0.10.13.exe /NCRC /S /desktopicon=yes /quicklaunchicon=no /D=C:\Program Files\Foo - - -
-
- Components - - Beside the usual installer options like where to install the program, - there are several optional components. - - Tip! - - If you are unsure which settings to select, just keep the default settings. - - - - The Components - (both Ethereal GTK1 and 2 cannot be installed at the same time): - - - Etheral GTK1 - Wireshark is a GUI network protocol - analyzer. - - - Etheral GTK2 - Wireshark is a GUI network protocol - analyzer (using the modern GTK2 GUI toolkit, recommended). - - - GTK-Wimp - GTKWimp is the GTK2 windows impersonator - (native Win32 look and feel, recommended). - - - Tethereal - Tethereal is a command-line based network - protocol analyzer. - - - The dissection extensions for Wireshark and Tethereal: - - - Dissector Plugins - Plugins with some extended dissections. - - - Tree Statistics Plugins - Plugins with some extended statistics. - - - Mate - Meta Analysis and Tracing Engine - user - configurable extension(s) of the display filter engine, see - http://wiki.ethereal.com/Mate - for details. - - - SNMP MIBs - SNMP MIBs for a more detailed SNMP - dissection. - - - The Tools: - - - Editcap - Editcap is a program that reads a capture - file and writes some or all of the packets into another capture file. - - - Text2Pcap - Text2pcap is a program that reads in an - ASCII hex dump and writes the data into a libpcap-style capture file. - - - Mergecap - Mergecap is a program that combines multiple - saved capture files into a single output file. - - - Capinfos - Capinfos is a program that provides - information on capture files. - - - The Additional Tasks: - - - Start Menu Shortcuts - add some start menu shortcuts. - - - Desktop Icon - add an Ethereal icon to the desktop. - - - Quick Launch Icon - add an Ethereal icon to the - Explorer quick launch toolbar. - - - Associate file extensions to Ethereal - Associate - standard network trace files to Ethereal. - - - -
-
-
- Install WinPcap - Note! - - 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! - - - - 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. - - - While running, the Wireshark installer detects which WinPcap version is - currently installed and will install WinPcap, if none or an older version is - detected. - - - More WinPcap info: - - - Ethereal related: - http://wiki.ethereal.com/WinPcap - - - General WinPcap info: - &WinPcapWebsite; - - - -
- Manual WinPcap Installation - - 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. - - - Additional WinPcap versions (including newer alpha or beta releases) - can be downloaded from the following locations: - - - The main WinPcap site: - &WinPcapWebsite; - - - The ethereal.com mirror: - - http://winpcap.mirror.ethereal.com - - - The Wiretapped.net mirror: - - http://www.mirrors.wiretapped.net/security/packet-capture/winpcap - - - - - 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. - -
-
- -
- Update Ethereal - - 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 for details how to subscribe to this list. - - - 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. - -
- -
- Update WinPcap - - 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. - - Warning! - - 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. - - -
- -
- Uninstall Ethereal - - 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. - - - 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. - - - WinPcap won't be uninstalled by default, as other programs than Ethereal - may use it as well. - -
- -
- Uninstall WinPcap - - You can uninstall WinPcap independantly of Ethereal, using the "WinPcap" - entry in the "Add or Remove Programs" of the Control Panel. - - Note! - - After uninstallation of WinPcap you can't capture anything with Ethereal. - - - - It might be a good idea to reboot Windows afterwards. - -
-
- - - diff --git a/docbook/eug_src/EUG_chapter_capture.xml b/docbook/eug_src/EUG_chapter_capture.xml deleted file mode 100644 index 9918b3e9fb..0000000000 --- a/docbook/eug_src/EUG_chapter_capture.xml +++ /dev/null @@ -1,1033 +0,0 @@ - - - - - Capturing Live Network Data - -
- Introduction - - Capturing live network data is one of the major features of Ethereal. - - - The Wireshark capture engine provides the following features: - - - - - Capture from different kinds of network hardware (Ethernet, Token Ring, - ATM, ...). - - - Stop the capture on different triggers like: amount of captured data, - captured time, captured number of packets. - - - Simultaneously show decoded packets while keep on capturing. - - - Filter packets, reducing the amount of data to be captured, see . - - - 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 . - - - The capture engine still lacks the following features: - - - Simultaneous capturing from multiple network interfaces (however, you - can start multiple instances of Ethereal and merge capture files later). - - - Stop capturing (or doing some other action), depending on the captured - data. - - - -
- -
Prerequisites - - Setting up Ethereal to capture packets for the first time can be tricky. - - Tip! - A comprehensive guide "How To setup a Capture" is available at: - http://wiki.ethereal.com/CaptureSetup. - - - Here are some common pitfalls: - - - - You need to have root / Administrator privileges to start a live - capture. - - - - - You need to choose the right network interface to capture packet data - from. - - - - - You need to capture at the right place in the network to see the - traffic you want to see. - - - - - ... and a lot more!. - - - - - - If you have any problems setting up your capture environment, you should - have a look at the guide mentioned above. - -
- -
Start Capturing - - One of the following methods can be used to start capturing packets with - Ethereal: - - - - You can get an overview of the available local interfaces using the - " - Capture Interfaces" dialog box, see - . You can start a - capture from this dialog box, using (one of) the "Capture" button(s). - - - - - You can start capturing using the - " - Capture Options" dialog box, see - . - - - - - If you have selected the right capture options before, you can - immediately start a capture using the - " - Capture Start" menu / toolbar item. The capture - process will start immediately. - - - - - If you already know the name of the capture interface, you can start - Ethereal from the command line and use the following: - -ethereal -i eth0 -k - - This will start Ethereal capturing on interface eth0, more details - can be found at: . - - - - -
- -
- The "Capture Interfaces" dialog box - - When you select "Interfaces..." from the Capture menu, Ethereal pops - up the "Capture Interfaces" dialog box as shown in - . - Warning! - - 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. - - - Note! - - 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. - - -
- The "Capture Interfaces" dialog box - -
- - Description - - - The interface description provided by the operating system. - - - - IP - - - 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). - - - - Packets - - - 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. - - - - Packets/s - - - Number of packets captured in the last second. Will be greyed out, - if no packet was captured in the last second. - - - - Stop - - - Stop a currently running capture. - - - - Capture - - - Start a capture on this interface immediately, using the settings - from the last capture. - - - - Prepare - - - Open the Capture Options dialog with this interface selected, see - . - - - - Close - - - Close this dialog box. - - - - - -
- -
- The "Capture Options" dialog box - - 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 - . - -
- The "Capture Options" dialog box - -
- Tip! - - 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. - - - - You can set the following fields in this dialog box: - -
Capture frame - - Interface - - - 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). - - - This field performs the same function as the - -i <interface> command line option. - - - - IP address - - - The IP address(es) of the selected interface. If no address could - be resolved from the system, "unknown" will be shown. - - - - Link-layer header type - - - Unless you are in the rare situation that you need this, just keep - the default. For a detailed description, see - - - - - Buffer size: n megabyte(s) - - - 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. - - - Note - This option is only available on Windows platforms. - - - - - - Capture packets in promiscuous mode - - - - 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). - - - Note - - 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 - - - - Note - - Even in promiscuous mode you still won't necessarily see all packets - on your LAN segment, see for - some more explanations. - - - - - Limit each packet to n bytes - - - 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 snaplen. If disabled, - the default is 65535, which will be sufficient for most - protocols. Some rules of thumb: - - - - - If you are unsure, just keep the default value. - - - - - 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. - - - - - 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. - - - - - - Capture Filter - - - This field allows you to specify a capture filter. - Capture filters are discussed in more details in - . It defaults to empty, or - no filter. - - - 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 - - - - - -
-
Capture File(s) frame - - An explanation about capture file usage can be found in . - - - File - - - 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 for - details. - - - You can also click on the button to the right of this field to - browse through the filesystem. - - - - Use multiple files - - - Instead of using a single file, Ethereal will automatically switch - to a new one, if a specific trigger condition is reached. - - - - Next file every n megabyte(s) - - - Multiple files only: Switch to the next file after the given - number of byte(s)/kilobyte(s)/megabyte(s)/gigabyte(s) have been - captured. - - - - Next file every n minute(s) - - - Multiple files only: Switch to the next file after the given - number of second(s)/minutes(s)/hours(s)/days(s) have elapsed. - - - - Ring buffer with n files - - - Multiple files only: Form a ring buffer of the capture files, with - the given number of files. - - - - Stop capture after n file(s) - - - Multiple files only: Stop capturing after switching to the next - file the given number of times. - - - - -
-
Stop Capture... frame - - ... after n packet(s) - - - Stop capturing after the given number of packets have been - captured. - - - - ... after n megabytes(s) - - - 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. - - - - ... after n minute(s) - - - Stop capturing after the given number of - second(s)/minutes(s)/hours(s)/days(s) have elapsed. - - - - -
-
Display Options frame - - - - Update list of packets in real time - - - - 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. - - - - - - Automatic scrolling in live capture - - - - 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. - - - - - - Hide capture info dialog - - - - If this option is checked, the following capture info dialog will be - hidden. - - - - -
-
Name Resolution frame - - - Enable MAC name resolution - - - This option allows you to control whether or not - Ethereal translates MAC addresses into names, see - . - - - - - Enable network name resolution - - - This option allows you to control whether or not - Ethereal translates network addresses into names, see - . - - - - - Enable transport name resolution - - - This option allows you to control whether or not - Ethereal translates transport addresses into protocols, see - . - - - - -
-
Buttons - - Once you have set the values you desire and have selected the - options you need, simply click on OK to commence the - capture, or Cancel to cancel the capture. - - - If you start a capture, Ethereal allows you to stop capturing when - you have enough packets captured, for details see - . - -
-
- -
Capture files and file modes - - 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. - - - - Different modes of operation are available when saving this packet data to - the capture file(s). - - - Tip! - - 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. - - - Note! - - 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. - - - Tip! - - Information about the folders used for the capture file(s), can be found - in . - - - - Capture file mode selected by capture options - - - - - - - - "File" option - "Use multiple files" option - "Ring buffer with n files" option - Mode - Resulting filename(s) used - - - - - - - - - - - Single temporary file - etherXXXXXX (where XXXXXX is a unique number) - - - foo.cap - - - - - Single named file - foo.cap - - - foo.cap - x - - - Multiple files, continuous - foo_00001_20040205110102.cap, foo_00002_20040205110102.cap, ... - - - foo.cap - x - x - Multiple files, ring buffer - foo_00001_20040205110102.cap, foo_00002_20040205110102.cap, ... - - - -
- - - Single temporary file - - - 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. - - - - - Single named file - - - A single capture file will be used. If you want to place the new capture - file to a specific folder, choose this mode. - - - - - Multiple files, continuous - - - 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). - - - - - Multiple files, ring buffer - - - 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"). - - - This mode will limit the maximum disk usage, even for an unlimited amount of - capture input data, keeping the latest captured data. - - - - -
- -
Link-layer header type - - 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: - - - 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". - - - 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". - - - 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". - - - 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". - -
- -
Filtering while capturing - - 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. - - - Tip! - - You will find a lot of Capture Filter examples at &EtherealWikiCaptureFiltersPage;. - - - - You enter the capture filter into the Filter field of the Wireshark - Capture Options dialog box, as shown in - . The following is an outline - of the syntax of the tcpdump capture filter language. - See the expression option at the tcpdump manual page for details: - . - - - A capture filter takes the form of a series of primitive expressions - connected by conjunctions (and/or) and optionally - preceded by not: - -[not] primitive [and|or [not] primitive ...] - - An example is shown in . - - - - A capture filter for telnet than captures traffic to and from a - particular host - - -tcp port 23 and host 10.0.0.5 - - - This example captures telnet traffic to and from the host - 10.0.0.5, and shows how to use two primitives and the - and conjunction. Another example is shown in - , and shows how to capture all - telnet traffic except that from 10.0.0.5. - - - Capturing all telnet traffic not from 10.0.0.5 - -tcp port 23 and not host 10.0.0.5 - - - - - - XXX - add examples to the following list. - - - A primitive is simply one of the following: - - - [src|dst] host <host> - - - This primitive allows you to filter on a host IP - address or name. You can optionally precede the - primitive with the keyword src|dst - 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. - - - - - - ether [src|dst] host <ehost> - - - - This primitive allows you to filter on Ethernet host - addresses. You can optionally include the keyword - src|dst between the keywords - ether and host - 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. - - - - - gateway host <host> - - - This primitive allows you to filter on packets that - used host as a gateway. That is, where - the Ethernet source or destination was - host but neither the source nor - destination IP address was host. - - - - - - - [src|dst] net <net> [{mask <mask>}|{len <len>}] - - - - - This primitive allows you to filter on network numbers. - You can optionally precede this primitive with the - keyword src|dst 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. - - - - - - [tcp|udp] [src|dst] port <port> - - - - This primitive allows you to filter on TCP and UDP port - numbers. You can optionally precede this primitive with - the keywords src|dst and - tcp|udp which allow you to specify - that you are only interested in source or destination - ports and TCP or UDP packets respectively. The - keywords tcp|udp must appear before - src|dst. - - - 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. - - - - - less|greater <length> - - - 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. - - - - - ip|ether proto <protocol> - - - This primitive allows you to filter on the specified - protocol at either the Ethernet layer or the IP layer. - - - - - ether|ip broadcast|multicast - - - This primitive allows you to filter on either - Ethernet or IP broadcasts or multicasts. - - - - - <expr> relop <expr> - - - 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 - for more details. - - - - - -
- -
While a Capture is running ... - - While a capture is running, the following dialog box is shown: -
- The "Capture Info" dialog box - -
- 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. - - Tip! - - This Capture Info dialog box can be hidden, using the "Hide capture info - dialog" option in the Capture Options dialog box. - - -
Stop the running capture - - A running capture session will be stopped in one of the following ways: - - - Using the - " - Stop" button from the Capture Info dialog box - . - - Note! - - The Capture Info dialog box might be hidden, if the option "Hide capture - info dialog" is used. - - - - - Using the menu item - "Capture/ - Stop". - - - - Using the toolbar item - " - Stop". - - - - Pressing the accelerator keys: Ctrl+E. - - - - The capture will be automatically stopped, if one of the - Stop Conditions is exceeded, e.g. the maximum amount - of data was captured. - - - - -
-
Restart a running capture - - 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. - - - 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: - - - Using the menu item - "Capture/ - Restart". - - - - Using the toolbar item - " - Restart". - - - - -
-
- - - - diff --git a/docbook/eug_src/EUG_chapter_customize.xml b/docbook/eug_src/EUG_chapter_customize.xml deleted file mode 100644 index 5c9c9d23e3..0000000000 --- a/docbook/eug_src/EUG_chapter_customize.xml +++ /dev/null @@ -1,827 +0,0 @@ - - - - - Customizing Ethereal - -
Introduction - - 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: - - - - How to start Ethereal with command line parameters - - - - - How to colorize the packet list - - - - - How to control protocol dissection - - - - - How to use the various preference settings - - - - -
- -
Start Ethereal from the command line - - You can start Ethereal 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. - - - Ethereal supports a large number of - command line parameters. To see what they are, simply enter the - command ethereal -h and the help information - shown in (or something similar) should be - printed. - - Help information available from Ethereal - -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> ] - - - We will examine each of the command line options in turn. - - - The first thing to notice is that issuing the command - ethereal by itself will bring up - Ethereal. - 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? - - -a <capture autostop condition> - - - 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: - - duration:value - - Stop writing to a capture file after value of seconds have elapsed. - - - filesize:value - - 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. - - - files:value - - Stop writing to capture files after value number of files were - written. - - - - - - - -b <capture ring buffer option> - - - 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. - - - 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. - - - 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. - - - - duration:value - - Switch to the next file after value seconds have elapsed, even - if the current file is not completely filled up. - - - filesize:value - - Switch to the next file after it reaches a size of value kilobytes - (where a kilobyte is 1000 bytes, not 1024 bytes). - - - files:value - - Begin again with the first file after value number of files were - written (form a ring buffer). - - - - - - - -B <capture buffer size (Win32 only)> - - - 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. - - - - -c <capture packet count> - - - This option specifies the maximum number of packets to capture - when capturing live data. It would be used in conjunction - with the -k option. - - - - -D - - -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 -i flag to specify an interface on which to capture. - - -This can be useful on systems that don't have a command to list them -(e.g., Windows systems, or UNIX systems lacking ifconfig -a); -the number can be useful on Windows 2000 and later systems, where the -interface name is a somewhat complex string. - - -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 -D flag and -is not run from such an account, it will not list any interfaces. - - - - -f <capture filter> - - - This option sets the initial capture filter expression to - be used when capturing packets. - - - - -g <packet number> - - - After reading in a capture file using the -r flag, go to the given - packet number. - - - - -h - - - The -h option requests Ethereal to print - its version and usage instructions (as shown above) and exit. - - - - -i <capture interface> - - -Set the name of the network interface or pipe to use for live packet -capture. - - -Network interface names should match one of the names listed in -ethereal -D (described above); a number, as reported by -ethereal -D, can also be used. If you're using UNIX, netstat --i or ifconfig -a might also work to list interface names, -although not all versions of UNIX support the -a flag to ifconfig. - - -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. - - -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. - - - - -k - - - The -k option specifies that Ethereal - should start capturing packets immediately. This option - requires the use of the -i parameter to - specify the interface that packet capture will occur from. - - - - -l - - - 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 -S - flag). - - - - -L - - - List the data link types supported by the interface and exit. - - - - -m <font> - - - This option sets the name of the font used for most text - displayed by Wireshark. XXX - add an example! - - - - -n - - - Disable network object name resolution (such as hostname, TCP and UDP - port names). - - - - -N <name resolving flags> - - - Turns on name resolving for particular types of addresses - and port numbers; the argument is a string that may contain - the letters m to enable MAC address - resolution, n to enable network address - resolution, and t to enable transport-layer - port number resolution. This overrides -n - if both -N and -n are - present. The letter C enables concurrent (asynchronous) DNS lookups. - - - - - -o <preference/recent settings> - - - 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 - -o <preference settings> can be - given on a single command line. - - An example of setting a single preference would be: - - - ethereal -o mgcp.display_dissect_tree:TRUE - - - - An example of setting multiple preferences would be: - - - - ethereal -o mgcp.display_dissect_tree:TRUE -o mgcp.udp.callagent_port:2627 - - - Tip! - - You can get a list of all available preference strings from the - preferences file, see . - - - - - -p - - - 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. - - - - -Q - - - This option forces Ethereal to exit when capturing is - complete. It can be used with the -c option. - It must be used in conjunction with the - -i and -w options. - - - - -r <infile> - - - 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. - - - - -R <read (display) filter> - - - 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 - . Packets not - matching the filter are discarded. - - - - -s <capture snaplen> - - - This option specifies the snapshot length to use when - capturing packets. Ethereal will only capture - <snaplen> bytes of data for each packet. - - - - -S - - - 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. - - - - - -t <time stamp format> - - - This option sets the format of packet timestamps that are - displayed in the packet list window. The format can be one of: - - - - r relative, which specifies timestamps are - displayed relative to the first packet captured. - - - - - a absolute, which specifies that actual times - be displayed for all packets. - - - - - ad absolute with date, which specifies that - actual dates and times be displayed for all packets. - - - - - d delta, which specifies that timestamps - are relative to the previous packet. - - - - - - - -v - - - The -v option requests - Ethereal to print out its version information and exit. - - - - -w <savefile> - - - This option sets the name of the savefile - to be used when saving a capture file. - - - - -y <capture link type> - - - 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. - - - - -X <eXtension option> - - - 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: - - - lua_script:lua_script_filename Tell Ethereal to load the given script in addition to the default Lua scripts. - - - - -z <statistics-string> - - - 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! - - - - - -
- -
Packet colorization - - 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. - - - Tip! - - You will find a lot of Coloring Rule examples at the Ethereal - Wiki Coloring Rules page at &EtherealWikiColoringRulesPage;. - - - - 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 . - -
- The "Coloring Rules" dialog box - -
- - 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. - - Note! - - 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). - - - - 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 - . - -
- The "Edit Color Filter" dialog box - -
- - In the Edit Color dialog box, simply enter a name for the color filter, - and enter a filter string in the Filter text field. - shows the values - arp and arp which means that - the name of the color filter is arp and the filter - will select protocols of type arp. Once you have - entered these values, you can choose a foreground and background - color for packets that match the filter expression. Click on - Foreground color... or - Background color... to achieve this and - Ethereal will pop up the Choose foreground/background color for - protocol dialog box as shown in - . - -
- The "Choose color" dialog box - -
- - Select the color you desire for the selected packets and click on OK. - - - Note! - - 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. - - - - 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. - -
- Using color filters with Ethereal - -
-
- -
- Control Protocol dissection - - The user can control how protocols are dissected. - - - 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. - - - 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. - -
The "Enabled Protocols" dialog - box - - 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. - - Note! - - 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. - - -
- The "Enabled Protocols" dialog box - -
- - To disable or enable a protocol, simply click on it using the - mouse or press the space bar when the protocol is highlighted. - - Warning! - - 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. - - - - You can choose from the following actions: - - - - Enable All Enable all protocols in the list. - - - - - Disable All Disable all protocols in the list. - - - - - Invert Toggle the state of all protocols in the - list. - - - - - OK Apply the changes and close the dialog box. - - - - - Apply Apply the changes and keep the dialog box - open. - - - - - Save Save the settings to the disabled_protos, see - for details. - - - - - Cancel Cancel the changes and close the dialog box. - - - - -
- -
User Specified Decodes - - 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. - - -
- The "Decode As" dialog box - -
- The content of this dialog box depends on the selected packet when it - was opened. - Warning! - - The user specified decodes can not be saved. If you quit Ethereal, - these settings will be lost. - - - - - - Decode Decode packets the selected way. - - - - - Do not decode Do not decode packets the selected - way. - - - - - Link/Network/Transport 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. - - - - - Show Current Open a dialog box showing the - current list of user specified decodes. - - - - - OK Apply the currently selected decode and close - the dialog box. - - - - - Apply Apply the currently selected decode and keep - the dialog box open. - - - - - Cancel Cancel the changes and close the dialog box. - - - - -
- -
Show User Specified Decodes - - This dialog box shows the currently active user specified decodes. -
- The "Decode As: Show" dialog box - -
- - - - OK Close this dialog box. - - - - - Clear Removes all user specified decodes. - - - - -
-
- -
Preferences - - 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 - , with the "User Interface" page as - default. On the left side is a tree where you can select the page to be - shown. - Note! - - Preference settings are added frequently. For a recent explanation of - the preference pages and their settings have a look at the - Ethereal Wiki Preferences page at &EtherealWikiPreferencesPage;. - - - - Warning! - - The OK or Apply button will not save the preference settings, - you'll have to save the settings by clicking the Save button. - - - - - - The OK button will apply the preferences - settings and close the dialog. - - - - - The Apply button will apply the preferences - settings and keep the dialog open. - - - - - The Save button will apply the preferences - settings, save the settings on the harddisk and keep the dialog open. - - - - - The Cancel button will restore all preferences - settings to the last saved state. - - - - -
- The preferences dialog box - -
-
- - - - diff --git a/docbook/eug_src/EUG_chapter_introduction.xml b/docbook/eug_src/EUG_chapter_introduction.xml deleted file mode 100644 index 99f7e52957..0000000000 --- a/docbook/eug_src/EUG_chapter_introduction.xml +++ /dev/null @@ -1,614 +0,0 @@ - - - - - Introduction - -
- What is <application>Ethereal?</application> - - 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. - - - 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). - - - In the past, such tools were either very expensive, proprietary, or both. - However, with the advent of Ethereal, all that has changed. - - - Ethereal is perhaps one of the best open - source packet analyzers available today. - - -
Some intended purposes - - Here are some examples people use Ethereal for: - - - network administrators use it to troubleshoot network - problems - - - network security engineers use it to examine security - problems - - - developers use it to debug protocol implementations - - - people use it to learn network protocol - internals - - - Beside these examples, Ethereal can be helpful in many other situations - too. - -
- -
Features - - The following are some of the many features Ethereal provides: - - - Available for UNIX and Windows. - - - - Capture live packet data from a network interface. - - - - - Display packets with very detailed protocol information. - - - - - Open and Save packet data captured. - - - - - Import and Export packet data from and to a lot of - other capture programs. - - - - Filter packets on many criteria. - - - Search for packets on many criteria. - - - Colorize packet display based on filters. - - - Create various statistics. - - - ... and a lot more! - - - However, to really appreciate its power, you have to start using it. - - - shows Ethereal - having captured some packets and waiting for you to examine - them. -
- - <application>Ethereal</application> captures packets and allows - you to examine their content. - - -
- -
- -
- Live capture from many different network media - - 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: - . - -
- -
Import files from many other capture programs - - Ethereal can open packets captured from a large number of - other capture programs. For a list of input formats see - . - -
-
Export files for many other capture programs - - Ethereal can save packets captured in a large number of formats of - other capture programs. For a list of output formats see - . - -
- -
- Many protocol decoders - - There are protocol decoders (or dissectors, as they are - known in Wireshark) for a great many protocols: - see . - -
- -
Open Source Software - - Wireshark is an open source software project, and is released under - the GNU General Public Licence (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! - -
- -
What Wireshark is not - - Here are some things Ethereal does not provide: - - - 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. - - - 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). - - - -
-
- -
- Platforms Ethereal runs on - - Ethereal currently runs on most UNIX platforms and various Windows - platforms. It requires GTK+, GLib, libpcap and some other libraries in - order to run. - - - 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 &EtherealDevMailList;. - - - Binary packages are available for at least the following platforms: - - -
Unix - - - Apple Mac OS X - BeOS - FreeBSD - HP-UX - IBM AIX - NetBSD - OpenBSD - SCO UnixWare/OpenUnix - SGI Irix - Sun Solaris/Intel - Sun Solaris/Sparc - Tru64 UNIX (formerly Digital UNIX) - - -
- -
Linux - - - Debian GNU/Linux - Gentoo Linux - IBM S/390 Linux (Red Hat) - Mandrake Linux - PLD Linux - Red Hat Linux - Rock Linux - Slackware Linux - Suse Linux - - -
- -
Microsoft Windows - - Maintained: - - Windows Server 2003 / XP / 2000 / NT 4.0 - Windows Me / 98 - - - - Unsupported/Unmaintained (because lack of required libraries): - - Windows CE - Windows NT / XP Embedded - Windows 95 is no longer actively maintained by WinPcap, - but still may work perfectly - - - - No experiences (fresh versions): - - Windows XP 64-bit Edition - Windows Vista (aka Longhorn) - - Please provide your experiences about these fresh versions to: - &EtherealDevMailList;. - -
- -
- -
- Where to get Ethereal? - - You can get the latest copy of the program from the Wireshark website: - &EtherealDownloadPage;. The - website allows you to choose from among several mirrors for - downloading. - - - A new Ethereal version will typically become available every 4-8 weeks. - - - 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 . - -
- -
- A rose by any other name - - William Shakespeare wrote: - - "A rose by any other name would smell as sweet." - - And so it is with Ethereal, as there appears to be two different - ways that people pronounce the name. - - - Some people pronounce it ether-real, while others pronounce it - e-the-real, as in ghostly, insubstantial, etc. - - - 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". - -
- -
- A brief history of Ethereal - - 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. - - - 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. - - - Not long after that Gilbert Ramirez saw its potential and contributed - a low-level dissector to it. - - - 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. - - - 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. - - - 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. - -
- -
- - Development and maintenance of <application>Ethereal</application> - - - 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. - - - 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 authors page on the - Ethereal web site. - - - Wireshark is an open source software project, and is released under - the GNU General Public Licence (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. - - - You gain three benefits by contributing your improvements back to the - community: - - - - 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. - - - - - 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. - - - - - 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. - - - - - - The Wireshark source code and binary kits for some platforms are all - available on the download page of the Wireshark website: - &EtherealDownloadPage;. - -
- -
- Reporting problems and getting help - - 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). - - -
Website - - You will find lot's of useful information on the Wireshark homepage at - &EtherealWebSite;. - -
- -
Wiki - - The Wireshark Wiki at &EtherealWikiPage; 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. - - - 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. - -
- -
FAQ - - The "Frequently Asked Questions" will list often asked questions and - the corresponding answers. - Read the FAQ! - - 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). - - - You will find the FAQ inside Ethereal by clicking the menu item - Help/Contents and selecting the FAQ page in the upcoming dialog. - - - An online version is available at the ethereal website: - &EtherealFAQPage;. You might - prefer this online version, as it's typically more up to date and the HTML - format is easier to use. - -
- -
Mailing Lists - - There are several mailing lists of specific Ethereal topics available: - - ethereal-announce - - - This mailing list will inform you about new program - releases, which usually appear about every 4-8 weeks. - - - - ethereal-users - - - This list is for users of Ethereal. People post - questions about building and using Ethereal, others (hopefully) - provide answers. - - - - ethereal-dev - - - This list is for Wireshark developers. If you want to start - developing a protocol dissector, join this list. - - - - - You can subscribe to each of these lists from the Wireshark web site: - &EtherealWebSite;. Simply - select the mailing lists link on the left hand - side of the site. The lists are archived at the Wireshark web site - as well. - Tip! - - 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. - - - -
- -
Reporting Problems - Note! - - Before reporting any problems, please make sure you have installed the - latest version of Ethereal. - - - - When reporting problems with Ethereal, it is helpful if you supply the - following information: - - - - The version number of Ethereal and the dependent libraries linked with - it, eg GTK+, etc. You can obtain this with the command - ethereal -v. - - - - - Information about the platform you run Ethereal on. - - - - - A detailed description of your problem. - - - - - 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. - - - - - Don't send large files! - - 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. - - - Don't send confidential information! - - If you send captured data to the mailing lists, be sure they don't contain - any sensitive or confidential information like passwords or such. - - -
- -
Reporting Crashes on UNIX/Linux platforms - - When reporting crashes with Ethereal, it is helpful if you supply the - traceback information (besides the information mentioned in "Reporting - Problems"). - - - You can obtain this traceback information with the following commands: - -& bt.txt -backtrace -^D -$ -]]> - - - - Type the characters in the first line verbatim! Those are - back-tics there! - - - - - backtrace is a gdb 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 gdb to exit. This will - leave you with a file called - bt.txt in the current directory. - Include the file with your bug report. - - - - - If you do not have gdb available, you - will have to check out your operating system's debugger. - - - - - You should mail the traceback to the - &EtherealDevMailList; - mailing list. - -
- -
Reporting Crashes on Windows platforms - - 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. - -
-
- - - diff --git a/docbook/eug_src/EUG_chapter_io.xml b/docbook/eug_src/EUG_chapter_io.xml deleted file mode 100644 index cadbefc353..0000000000 --- a/docbook/eug_src/EUG_chapter_io.xml +++ /dev/null @@ -1,875 +0,0 @@ - - - - - File Input / Output and Printing - -
Introduction - - This chapter will describe input and output of capture data. - - - - Open/Import capture files in various capture file formats - - - - - Save/Export capture files in various capture file formats - - - - - Merge capture files together - - - - - Print packets - - - - -
- -
Open capture files - - Ethereal can read in previously saved capture files. - To read them, simply select the menu or toolbar item: "File/ - - Open". - Ethereal will then pop up the File - Open dialog box, which is discussed in more detail in - . - - Note! - - You can also use drag-and-drop 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. - - - - 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). - - - 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 for the list of - capture formats Ethereal understands. - - -
The "Open Capture File" dialog box - - The "Open Capture File" dialog box allows you to search for a - capture file containing previously captured packets for display in - Ethereal. shows an example - of the Wireshark Open File Dialog box. - - - Note - - 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. - - -
- The "Open Capture File" Dialog box - -
- - With this dialog box, you can perform the following actions: - - - - The "+ Add" button allows you to add a directory, selected in the - right-hand pane, to the favorites (bookmarks?) list. Those changes - are persistent. - - - - - The "- Remove" button allows you to remove a selected directory from - that list again (the items like: "Home", "Desktop", and "Filesystem" - cannot be removed). - - - - - Select files and directories with the list boxes. - - - - - View file preview information (like the filesize, the number of - packets, ...), while browsing the filesystem. - - - - - 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 - ). - - - - - 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 - . - - - - - 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. - - - - - Click the Cancel button to go back to Ethereal and not load a capture - file. - - - - 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. - -
- -
- Input File Formats - - The following file formats from other capture tools can be opened by - Ethereal: - - libpcap, tcpdump and various other tools using tcpdump's capture format - Sun snoop and atmsnoop - Shomiti/Finisar Surveyor captures - Novell LANalyzer captures - Microsoft Network Monitor captures - AIX's iptrace captures - Cinco Networks NetXray captures - Network Associates Windows-based Sniffer and Sniffer Pro captures - Network General/Network Associates DOS-based Sniffer (compressed or uncompressed) captures - AG Group/WildPackets EtherPeek/TokenPeek/AiroPeek/EtherHelp/PacketGrabber captures - RADCOM's WAN/LAN Analyzer captures - Network Instruments Observer version 9 captures - Lucent/Ascend router debug output - HP-UX's nettl - Toshiba's ISDN routers dump output - ISDN4BSD i4btrace utility - traces from the EyeSDN USB S0 - IPLog format from the Cisco Secure Intrusion Detection System - pppd logs (pppdump format) - the output from VMS's TCPIPtrace/TCPtrace/UCX$TRACE utilities - the text output from the DBS Etherwatch VMS utility - Visual Networks' Visual UpTime traffic capture - the output from CoSine L2 debug - the output from Accellent's 5Views LAN agents - Endace Measurement Systems' ERF format captures - Linux Bluez Bluetooth stack hcidump -w traces - Catapult DCT2000 .out files - - - Note! - - 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. - - - -
- -
- -
Saving captured packets - - 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. - -
- The "Save Capture File As" dialog box - - The "Save Capture File As" dialog box allows you to save - the current capture to a file. - shows an example of this - dialog box. - - - Note - - 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. - - -
- The "Save Capture File As" dialog box - -
- - With this dialog box, you can perform the following actions: - - - - Type in the name of the file you wish to save the captured - packets in, as a standard file name in your file system. - - - - - Select the directory to save the file into. - - - - - Select the range of the packets to be saved, see - - - - - - 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 . - - - Note! - - Some capture formats may not be available, depending on the - packet types captured. - - - - Tip! - - You can convert capture files from one format to another - by reading in a capture file and writing it out using a - different format. - - - - - - Use "Browse for other folders" to browse files and folders in your - file system. - - - - - 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. - - - - - Click on the Cancel button to go back to Ethereal and not save the - captured packets. - - - - -
-
- Output File Formats - - The following file formats can be saved by Ethereal, - so other capture tools can read the capture data from: - - libpcap (tcpdump) - Novell LANalyzer - Network Associates Sniffer - Sun snoop - Microsoft Network Monitor - Visual Networks Visual UpTime traffic - Accellent 5Views - Networks Instruments Observer version 9 - HP-UX's nettl - - - - - Other protocol analyzers may require that the file has a certain suffix - in order to read the files you generate with Ethereal, e.g.: - - - ".DMP" for Tcpdump/libpcap - - - ".CAP" for Network Associates Sniffer Windows - - -
-
- -
Merging capture files - - Sometimes you need to merge several capture files into one. For example - this can be useful, if you have captured simultaneously from multiple - interfaces at once (e.g. using multiple instances of Ethereal). - - - Merging capture files can be done in three ways: - - - Use the menu item "Merge" from the "File" menu, - to open the merge dialog, see . - This menu item will be disabled, until you have loaded a capture file. - - - Use drag-and-drop 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. - - - Use the mergecap tool, which is a command - line tool to merge capture files. This tool provides the most options - to merge capture files, see . - - - -
The "Merge with Capture File" dialog box - - This dialog box let you select a file to be merged into the currently - loaded file. - - Note! - If your current data wasn't saved before, you will be asked to save - it first, before this dialog box is shown. - -
- The "Merge with Capture File" dialog box - -
- - - Prepend packets to existing file - - - Prepend the packets from the selected file before the currently loaded - packets. - - - - - Merge packets chronologically - - - Merge both the packets from the selected and currently loaded file in - chronological order. - - - - - Append packets to existing file - - - Append the packets from the selected file after the currently loaded - packets. - - - - - - All other controls will work the same way as in the "Open Capture File" - dialog box, see . - -
-
- -
File Sets - - When using the "Multiple Files" option while doing a capture - (see: ), - the capture data is spreaded over several capture files, called a file - set. - - - 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. - - How does Ethereal detect the files of a file set? - - 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. - - - 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. - - - 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. - - - - The following features in the "File Set" submenu of the "File" menu are - available to work with file sets in a convenient way: - - - - The List Files dialog box will list the files - Ethereal has recognized as being part of the current file set. - - - Next File closes the current and opens the next - file in the file set. - - - Previous File closes the current and opens the - previous file in the file set. - - -
- The "List Files" dialog box -
- The "List Files" dialog box - -
- - Each line contains information about a file of the file set: - - - Filename the name of the file. If you click on - the filename (or the radio button left to it), the current file will - be closed and the corresponding capture file will be opened. - - - Created the creation time of the file - - - Last Modified the last time the file was modified - - - Size the size of the file - - - The last line will contain info about the currently used directory where - all of the files in the file set can be found. - - - The content of this dialog box is updated each time a capture file is - opened/closed. - - - The Close button will, well, close the dialog box. - -
-
-
Exporting data - - Ethereal provides several ways and formats to export packet data. This - section describes general ways to export data from Ethereal. - - Note! - - There are more specialized functions to export specific data, - which will be described at the appropriate places. - - - - XXX - add detailed descriptions of the output formats and some sample - output, too. - -
- The "Export as Plain Text File" dialog box - - Export packet data into a plain ASCII text file, much like the format - used to print packets. -
- The "Export as Plain Text File" dialog box - -
- - - Export to file: frame chooses the file to export - the packet data to. - - - The Packet Range frame is described in . - - - The Packet Details frame is described in . - - - -
-
- The "Export as PostScript File" dialog box - - Export packet data into PostScript, much like the format used - to print packets. - Tip! - - You can easily convert PostScript files to PDF files using ghostscript. - For example: export to a file named foo.ps and then call: - ps2pdf foo.ps - - -
- The "Export as PostScript File" dialog box - -
- - - Export to file: frame chooses the file to export - the packet data to. - - - The Packet Range frame is described in . - - - The Packet Details frame is described in . - - - -
-
- The "Export as CSV (Comma Seperated Values) File" dialog box - XXX - add screenshot - - Export packet summary into CSV, used e.g. by spreadsheet programs to - im-/export data. - - - - Export to file: frame chooses the file to export - the packet data to. - - - The Packet Range frame is described in . - - - -
-
- The "Export as PSML File" dialog box - - Export packet data into PSML. This is an XML based format including - only the packet summary. -
- The "Export as PSML File" dialog box - -
- - - Export to file: frame chooses the file to export - the packet data to. - - - The Packet Range frame is described in . - - - There's no such thing as a packet details frame for PSML export, as the - packet format is defined by the PSML specification. - -
-
- The "Export as PDML File" dialog box - - Export packet data into PDML. This is an XML based format including - the packet details. The PDML file specification is available at: - - PDML specification. - - - 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. - - -
- The "Export as PDML File" dialog box - -
- - - Export to file: frame chooses the file to export - the packet data to. - - - The Packet Range frame is described in . - - - There's no such thing as a packet details frame for PDML export, as the - packet format is defined by the PDML specification. - -
-
- The "Export selected packet bytes" dialog box - - Export the bytes selected in the "Packet Bytes" pane into a raw - binary file. -
- The "Export Selected Packet Bytes" dialog box - -
- - - Name: the filename to export the packet data to. - - - The Save in folder: field lets you select the - folder to save to (from some predefined folders). - - - Browse for other folders provides a flexible - way to choose a folder. - - - -
-
- -
Printing packets - - 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 - . - -
The "Print" dialog box -
- The "Print" dialog box - -
- - The following fields are available in the Print dialog box: - - Printer - - - This field contains a pair of mutually exclusive radio buttons: - - - - Plain Text specifies that - the packet print should be in plain text. - - - - - PostScript specifies that - the packet print process should use PostScript to - generate a better print output on PostScript aware printers. - - - - - Output to file: specifies that printing - be done to a file, which name is entered in the field or selected - using the browse button. - - - This field is where you enter the file to - print to if you have selected Print to a file, or you can click the - button to browse the filesystem. It is greyed out if Print to a file - is not selected. - - - - - Print command specifies that a - command be used for printing. - - Note! - - These Print command fields are not available on - windows platforms. - - - - This field specifies the command to use for printing. It - is typically lpr. You would change it - to specify a particular queue if you need to print to a - queue other than the default. An example might be: - -lpr -Pmypostscript - - This field is greyed out if Output to file: is - checked above. - - - - - - - - Packet Range - - - Select the packets to be printed, see - - - - - Packet Format - - - Select the output format of the packets to be printed. You can - choose, how each packet is printed, see - - - - - - -
-
- -
The Packet Range frame - - The packet range frame is a part of various output related dialog boxes. - It provides options to select which packets should be processed by the - output function. -
- The "Packet Range" frame - -
- - - If the Captured button is set (default), all packets - from the selected rule will be processed. If the Displayed - button is set, only the currently displayed packets are taken - into account to the selected rule. - - - - - - All packets will process all packets. - - - - - Selected packet only process only the selected - packet. - - - - - Marked packets only process only the marked - packets. - - - - - From first to last marked packet process the - packets from the first to the last marked one. - - - - - Specify a packet range process a user specified - range of packets, e.g. specifying 5,10-15,20- will - process the packet number five, the packets from packet number ten - to fifteen (inclusive) and every packet from number twenty to the - end of the capture. - - - - -
- -
The Packet Format frame - - The packet format frame is a part of various output related dialog boxes. - It provides options to select which parts of a packet should be used for - the output function. -
- The "Packet Format" frame - -
- - - - Packet summary line enable the output of the - summary line, just as in the "Packet List" pane. - - - - - Packet details enable the output of the packet - details tree. - - - - - All collapsed the info from the "Packet Details" - pane in "all collapsed" state. - - - - - As displayed the info from the "Packet Details" - pane in the current state. - - - - - All expanded the info from the "Packet Details" - pane in "all expanded" state. - - - - - - - Packet bytes enable the output of the packet - bytes, just as in the "Packet Bytes" pane. - - - - - Each packet on a new page put each packet on a - separate page (e.g. when saving/printing to a text file, this will - put a form feed character between the packets). - - - - -
- - - - diff --git a/docbook/eug_src/EUG_chapter_statistics.xml b/docbook/eug_src/EUG_chapter_statistics.xml deleted file mode 100644 index e360d39e05..0000000000 --- a/docbook/eug_src/EUG_chapter_statistics.xml +++ /dev/null @@ -1,508 +0,0 @@ - - - - - Statistics -
- Introduction - - Ethereal provides a wide range of network statistics. - - - 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). - - - - General statistics: - - - - Summary about the capture file. - - - Protocol Hierarchy of the captured packets. - - - Endpoints e.g. traffic to and from an IP - addresses. - - - Conversations e.g. traffic between specific IP - addresses. - - - IO Graphs visualizing the number of packets (or - similar) in time. - - - - - - Protocol specific statistics: - - - - Service Response Time between request and response - of some protocols. - - - Various other protocol specific statistics. - - - - - Note! - - 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. - - - -
- -
- The "Summary" window - - General statistics about the current capture file. - -
The "Summary" window - -
- - - File general information about the capture file. - - - - Time the timestamps when the first and the - last packet were capturing (and the time between them). - - - Capture 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). - - - Display some display related information. - - - - Traffic some statistics of the network traffic seen. - If a display filter is set, you will see values in both columns. The - values in the Captured column will remain the same as - before, while the values in the Displayed column will - reflect the values corresponding to the packets shown in the display. - - - -
- -
- The "Protocol Hierarchy" window - - The protocol hierarchy of the captured packets. -
The "Protocol Hierarchy" window - -
- 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. - - - Each row contains the statistical values of one protocol. - - - The following columns containing the statistical values are available: - - - Protocol this protocol's name - - - % Packets the percentage of protocol packets, - relative to all packets in the capture - - - Packets the absolute number of packets of this - protocol - - - Bytes the absolute number of bytes of this - protocol - - - MBit/s the bandwidth of this protocol, relative - to the capture time - - - - End Packets the absolute number of packets of this - protocol (where this protocol were the highest protocol to decode) - - - - - End Bytes the absolute number of bytes of this protocol - (where this protocol were the highest protocol to decode) - - - - - End MBit/s the bandwidth of this protocol, relative to - the capture time (where this protocol were the highest protocol to decode) - - - - - Note! - - 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%). - - - Note! - - 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. - - -
- -
- Endpoints - - Statistics of the endpoints captured. - Tip! - - If you are looking for a feature other network tools call a - hostlist, here is the right place to look. The list of - Ethernet or IP endpoints is usually what you're looking for. - - - -
What is an Endpoint? - - 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: - - - - - Ethernet an Ethernet endpoint is identical to the - Ethernet's MAC address. - - - - - Fibre Channel XXX - insert info here. - - - - - FDDI a FDDI endpoint is identical to the FDDI MAC - address. - - - - - IPv4 an IP endpoint is identical to its IP address. - - - - - IPX XXX - insert info here. - - - - - TCP 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. - - - - - Token Ring a Token Ring endpoint is identical to the - Token Ring MAC address. - - - - - UDP 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. - - - - Broadcast / multicast endpoints - - 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. - - -
-
- The "Endpoints" window - - This window shows statistics about the endpoints captured. - -
The "Endpoints" window - -
- - 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). - - - Each row in the list shows the statistical values for exactly one endpoint. - - - Name resolution 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. - - Tip! - - 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. - - -
-
- The protocol specific "Endpoint List" windows - - 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. - -
-
- -
- Conversations - - Statistics of the captured conversations. - -
What is a Conversation? - - 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 - . - -
-
The "Conversations" window - - Beside the list content, the conversations window work the same way as the - endpoint ones, see for a - description how it works. -
The "Conversations" window - -
- -
-
- The protocol specific "Conversation List" windows - - 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. - -
-
- -
- The "IO Graphs" window - - User configurable graph of the captured network packets. - - - You can define up to five differently colored graphs. - - -
The "IO Graphs" window - -
- - - The user can configure the following things: - - - Graphs - - - - Graph 1-5 enable the graph 1-5 (only graph 1 is enabled - by default) - - - - - Color the color of the graph (cannot be changed) - - - - - Filter: a display filter for this graph (only the - packets that pass this filter will be taken into account for that graph) - - - - - Style: the style of the graph (Line/Impulse/FBar) - - - - - - - - X Axis - - - - Tick interval an interval in x direction lasts - (10/1/0.1/0.01/0.001 seconds) - - - - - Pixels per tick use 10/5/2/1 pixels per tick interval - - - - - - - - Y Axis - - - - Unit the unit for the y direction (Packets/Tick, - Bytes/Tick, Advanced...) - - - - - Scale the scale for the y unit - (10,20,50,100,200,500,...) - - - - - - - - XXX - describe the Advanced feature. - -
- -
- Service Response Time - - The service response time is the time between a request and the - corresponding response. This information is available for many protocols. - - - Service response time statistics are currently available for the following - protocols: - - - DCE-RPC - - - Fibre Channel - - - H.225 RAS - - - LDAP - - - MGCP - - - ONC-RPC - - - SMB - - - As an example, the DCE-RPC service response time is described in more - detail. - Note! - - The other Service Response Time windows will work the same way (or only - slightly different) compared to the following description. - - - -
- The "Service Response Time DCE-RPC" window - - The service response time of DCE-RPC is the time between the request and - the corresponding response. - - - First of all, you have to select the DCE-RPC interface: - -
The "Compute DCE-RPC statistics" window - -
- - You can optionally set a display filter, to reduce the amount of packets. - -
The "DCE-RPC Statistic for ..." window - -
- - 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. - -
-
- -
- The protocol specific statistics windows - - The protocol specific statistics windows display detailed information - of specific protocols and might be described in a later - version of this document. - - - Some of these statistics are described at the - pages. - -
- - - - diff --git a/docbook/eug_src/EUG_chapter_troubleshoot.xml b/docbook/eug_src/EUG_chapter_troubleshoot.xml deleted file mode 100644 index ffeb050f4a..0000000000 --- a/docbook/eug_src/EUG_chapter_troubleshoot.xml +++ /dev/null @@ -1,129 +0,0 @@ - - - - - Troubleshooting with <application>Ethereal</application> -
- An approach to troubleshooting with Ethereal - - 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: - - - - It allows you to focus in on specific packets and protocols, - as you can see a large amount of detail associated with - various protocols. - - - - - It supports a large number of protocols, and the list of - protocols supported is growing as more people contribute - dissectors - - - - - 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. - - - - - - The following general approach is suggested: - - - - Determine that the problem looks like a networking problem. - There is no point in capturing packets if the problem is not - networking related. - - - - - 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 for more details. - - - Because Ethereal can read many capture file formats, you can - capture using any conventient tool. One useful approach is - to use tcpdump to capture on remote - systems and then copy the capture file to your system for - later analysis. For more details on capturing with - tcpdump, see . - - - - - 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. - - - - - Examine the appropriate fields within the packets where - the problem appears to be. These can often help to reveal - the problem. - - - - -
-
- Capturing in the presence of switches and routers - - 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. - - - 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. - - - 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. - - - There are some ways to circumvent this. - - - 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 - - Configuring the Catalyst Switched Port Analyzer (SPAN) Feature - - -
-
- Examples of troubleshooting - - 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. - -
- - - diff --git a/docbook/eug_src/EUG_chapter_use.xml b/docbook/eug_src/EUG_chapter_use.xml deleted file mode 100644 index 9852ce4b50..0000000000 --- a/docbook/eug_src/EUG_chapter_use.xml +++ /dev/null @@ -1,2063 +0,0 @@ - - - - - User Interface -
Introduction - - By now you have installed Ethereal and - are most likely keen to get started capturing your first packets. In - the next chapters we will explore: - - - - How the Wireshark user interface works - - - - - How to capture packets in Ethereal - - - - - How to view packets in Ethereal - - - - - How to filter packets in Ethereal - - - - - ... and many other things! - - - - -
- -
Start Ethereal - - You can start Ethereal from your shell or window manager. - Tip! - - When starting Ethereal it's possible to specify optional settings using - the command line. See for details. - - - Note! - - 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. - - - -
- -
The Main window - - Lets look at Ethereal's user interface. shows - Ethereal as you would usually see it after some packets captured or loaded - (how to do this will be described later). -
- The Main window - -
- - - Ethereal's main window consist of parts that are commonly known from many - other GUI programs. - - - - The menu (see ) - is used to start actions. - - - - - The main toolbar (see ) - provides quick access to frequently used items from the menu. - - - - - The filter toolbar (see ) - provides a way to directly manipulate the currently used display filter - (see ). - - - - - The packet list pane (see ) - displays a summary of each packet captured. By clicking on packets - in this pane you control what is displayed in the other two panes. - - - - - The packet details pane (see ) - displays the packet selected in the packet list pane in more detail. - - - - - The packet bytes pane (see ) - displays the data from the packet selected in the packet list pane, and - highlights the field selected in the packet details pane. - - - - - The statusbar (see ) - shows some detailed information about the current program state and - the captured data. - - - - Tip! - - The layout of the main window can be customized by changing preference settings. - See for details! - - - -
- -
The Menu - - The Wireshark menu sits on top of the Wireshark window. - An example is shown in . - - Note! - - 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. - - - -
The Menu - -
- - - It contains the following items: - - File - - - 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 . - - - - Edit - - - 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 . - - - - View - - 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 . - - - - Go - - This menu contains items to go to a specific packet. - See . - - - - Capture - - This menu allows you to start and stop captures and to edit capture filters. - See . - - - - Analyze - - - 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 . - - - - Statistics - - - 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 . - - - - Help - - - 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 . - - - - - Each of these menu items is described in more detail in the sections - that follow. - - Tip! - - 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. - - -
- -
The "File" menu - - The Wireshark file menu contains the fields shown in - . - -
- The "File" Menu - -
- File menu items - - - - - - Menu Item - Accelerator - Description - - - - - Open... - Ctrl+O - - 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 . - - - - Open Recent - - - 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. - - - - Merge... - - - 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 . - - - - Close - Ctrl+W - - 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). - - - - ------ - - - - - Save - Ctrl+S - - 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 ). - - Note! - - If you have already saved the current capture, this - menu item will be greyed out. - - - Note! - - You cannot save a live capture while it is in - progress. You must stop the capture in order to - save. - - - - - Save As... - Shift+Ctrl+S - - 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 ). - - - - ------ - - - - - File Set > List Files - - - 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 ). - - - - File Set > Next File - - - 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. - - - - File Set > Previous File - - - 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. - - - - ------ - - - - - Export > as "Plain Text" file... - - - 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 - ). - - - - Export > as "PostScript" file... - - - 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 - ). - - - - Export > as "CSV" (Comma Separated Values packet summary) file... - - - 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 - ). - - - - Export > as "PSML" file... - - - 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 - ). - - - - Export > as "PDML" file... - - - 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 - ). - - - - Export > Selected Packet Bytes... - Ctrl+H - - 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 - ) - - - - ------ - - - - - Print... - Ctrl+P - - 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 - ). - - - - ------ - - - - - Quit - Ctrl+Q - - 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). - - - - -
-
- -
The "Edit" menu - - The Wireshark Edit menu contains the fields shown in - . - -
- The "Edit" Menu - -
- - Edit menu items - - - - - - Menu Item - Accelerator - Description - - - - - Find Packet... - Ctrl+F - - 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 - . - - - - Find Next - Ctrl+N - - This menu item tries to find the next packet matching the - settings from "Find Packet...". - - - - Find Previous - Ctrl+B - - This menu item tries to find the previous packet matching the - settings from "Find Packet...". - - - - ------ - - - - - Time Reference > Set Time Reference (toggle) - Ctrl+T - - This menu item set a time reference on the currently selected - packet. See for more information - about the time referenced packets. - - - - Time Reference > Find Next - - - This menu item tries to find the next time referenced packet. - - - - Time Reference > Find Previous - - - This menu item tries to find the previous time referenced packet. - - - - Mark Packet (toggle) - Ctrl+M - - This menu item "marks" the currently selected packet. See - for details. - - - - Mark All Packets - - - This menu item "marks" all packets. - - - - Unmark All Packets - - This menu item "unmarks" all marked packets. - - - - ------ - - - - - Preferences... - Shift+Ctrl+P - - 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 . - - - - -
-
- -
The "View" menu - - The Wireshark View menu contains the fields shown in - . - -
- The "View" Menu - -
- - View menu items - - - - - - Menu Item - Accelerator - Description - - - - - Main Toolbar - - - This menu item hides or shows the main toolbar, see - . - - - - Filter Toolbar - - - This menu item hides or shows the filter toolbar, see - . - - - - Statusbar - - - This menu item hides or shows the statusbar, see - . - - - - ------ - - - - - Packet List - - - This menu item hides or shows the packet list pane, see - . - - - - Packet Details - - - This menu item hides or shows the packet details pane, see - . - - - - Packet Bytes - - - This menu item hides or shows the packet bytes pane, see - . - - - - ------ - - - - - Time Display Format > Date and Time of Day: 1970-01-01 01:02:03.123456 - - - Selecting this tells Ethereal to display the - time stamps in date and time of day format, see - . - Note! - - The fields "Time of Day", "Date and Time of - Day", "Seconds Since Beginning of Capture" and "Seconds Since - Previous Packet" are mutually exclusive. - - - - - - Time Display Format > Time of Day: 01:02:03.123456 - - - Selecting this tells Ethereal to display time - stamps in time of day format, see - . - - - - Time Display Format > Seconds Since Beginning of Capture: 123.123456 - - - Selecting this tells Ethereal to display time - stamps in seconds since beginning of capture format, see - . - - - - Time Display Format > Seconds Since Previous Packet: 1.123456 - - - Selecting this tells Ethereal to display time stamps in - seconds since previous packet format, see - . - - - - Time Display Format > ------ - - - - - Time Display Format > Automatic (File Format Precision) - - - Selecting this tells Ethereal to display time stamps with the - precision given by the capture file format used, see - . - Note! - - The fields "Automatic", "Seconds" and "...seconds" are mutually exclusive. - - - - - - Time Display Format > Seconds: 0 - - - Selecting this tells Ethereal to display time stamps with a precision of one second, see - . - - - - Time Display Format > ...seconds: 0.... - - - Selecting this tells Ethereal to display time stamps with a precision of one second, decisecond, centisecond, millisecond, microsecond or nanosecond, see - . - - - - Name Resolution > Resolve Name - - - This item allows you to trigger a name resolve of the current packet - only, see . - - - - Name Resolution > Enable for MAC Layer - - - This item allows you to control whether or not - Ethereal translates MAC addresses into names, see - . - - - - Name Resolution > Enable for Network Layer - - - This item allows you to control whether or not - Ethereal translates network addresses into names, see - . - - - - Name Resolution > Enable for Transport Layer - - - This item allows you to control whether or not - Ethereal translates transport addresses into names, see - . - - - - Colorize Packet List - - - This item allows you to control wether or not Ethereal should colorize - the packet list. - Note! - Enabling colorization will slow down the display - of new packets while capturing / loading capture files. - - - - Auto Scroll in Live Capture - - - 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. - - - - ------ - - - - - Zoom In - Ctrl++ - - Zoom into the packet data (increase the font size). - - - - Zoom Out - Ctrl+- - - Zoom out of the packet data (decrease the font size). - - - - Normal Size - Ctrl+= - - Set zoom level back to 100% (set font size back to normal). - - - - Resize All Columns - - - Resize all column widths so the content will fit into it. - - Note! - Resizing may take a significant amount of time, especially if a - large capture file is loaded. - - - - - ------ - - - - - Expand Subtrees - - - This menu item expands the currently selected subtree in the - packet details tree. - - - - Expand All - - - 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. - - - - Collapse All - - - This menu item collapses the tree view of all packets - in the capture list. - - - - ------ - - - - - Coloring Rules... - - - 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 - . - - - - ------ - - - - - Show Packet in New Window - - - This menu item brings up the selected packet in a - separate window. The separate window shows only the - tree view and byte view panes. - - - - Reload - Ctrl-R - - This menu item allows you to reload the current - capture file. - - - - -
-
- -
The "Go" menu - - The Wireshark Go menu contains the fields shown in - . - -
- The "Go" Menu - -
- - Go menu items - - - - - - Menu Item - Accelerator - Description - - - - - Back - Alt+Left - - Jump to the recently visited packet in the packet - history, much like the page history in a web browser. - - - - Forward - Alt+Right - - Jump to the next visited packet in the packet - history, much like the page history in a web browser. - - - - Go to Packet... - Ctrl-G - - Bring up a dialog box that allows you - to specify a packet number, and then goes to that packet. See - for details. - - - - Go to Corresponding Packet - - - 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. - - - - ------ - - - - - First Packet - - - Jump to the first packet of the capture file. - - - - Last Packet - - - Jump to the last packet of the capture file. - - - - -
-
- -
The "Capture" menu - - The Wireshark Capture menu contains the fields shown in - . - -
- The "Capture" Menu - -
- - Capture menu items - - - - - - Menu Item - Accelerator - Description - - - - - Interfaces... - - - This menu item brings up a dialog box that shows what's going on - at the network interfaces Ethereal knows of, see - ) . - - - - Options... - Ctrl+K - - This menu item brings up the Capture Options - dialog box (discussed further in - ) and allows you to - start capturing packets. - - - - Start - - - Immediately start capturing packets with the same settings than - the last time. - - - - Stop - Ctrl+E - - This menu item stops the currently running capture, see - ) . - - - - Restart - - - This menu item stops the currently running capture and starts - again with the same options, this is just for convenience. - - - - Capture Filters... - - - 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 - - - - - -
-
- -
The "Analyze" menu - - The Wireshark Analyze menu contains the fields shown in - . - -
- The "Analyze" Menu - -
- Analyze menu items - - - - - - Menu Item - Accelerator - Description - - - - - Display Filters... - - - 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 - - - - - Apply as Filter > ... - - - 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. - - - - Prepare a Filter > ... - - - 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. - - - - ------ - - - - - Enabled Protocols... - Shift+Ctrl+R - - This menu item allows the user to enable/disable protocol - dissectors, see - - - - Decode As... - - - This menu item allows the user to force Ethereal to - decode certain packets as a particular protocol, see - - - - - User Specified Decodes... - - - This menu item allows the user to force Ethereal to - decode certain packets as a particular protocol, see - - - - - ------ - - - - - Follow TCP Stream - - - 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 - - - - - -
-
- -
The "Statistics" menu - - The Wireshark Statistics menu contains the fields shown in - . - -
- The "Statistics" Menu - -
- - All menu items will bring up a new window showing specific statistical - information. - - - Statistics menu items - - - - - - Menu Item - Accelerator - Description - - - - - Summary - - - Show information about the data captured, see . - - - - Protocol Hierarchy - - - Display a hierarchical tree of protocol statistics, see . - - - - Conversations - - - Display a list of conversations (traffic between two endpoints), - see . - - - - Endpoints - - - Display a list of endpoints (traffic to/from an address), see - . - - - - IO Graphs - - - Display user specified graphs (e.g. the number of packets in the - course of time), see . - - - - ------ - - - - - Conversation List - - - Display a list of conversations, obsoleted by the combined window - of Conversations above, see - . - - - - Endpoint List - - - Display a list of endpoints, obsoleted by the combined window - of Endpoints above, see - . - - - - Service Response Time - - - Display the time between a request and the corresponding response, see - . - - - - ------ - - - - - ANSI - - See - - - GSM - - See - - - H.225... - - See - - - ISUP Message Types - - See - - - MTP3 - - See - - - RTP - - See - - - SCTP - - See - - - SIP - - See - - - VoIP Calls... - - See - - - WAP-WSP... - - See - - - ------ - - - - - BOOTP-DHCP - - See - - - HTTP - - HTTP request/response statistics, see - - - ISUP Messages - - See - - - ONC-RPC Programs - - See - - - TCP Stream Graph - - See - - - -
-
- -
The "Help" menu - - The Wireshark Help menu contains the fields shown in - . - -
- The "Help" Menu - -
- - Help menu items - - - - - - Menu Item - Accelerator - Description - - - - - Contents - F1 - - This menu item brings up a basic help system. - - - - Supported Protocols - - - This menu item brings up a dialog box showing the supported - protocols and protocol fields. - - - - Manual Pages > ... - - - This menu item starts a Web browser showing one of the locally - installed html manual pages. - - - - Ethereal Online > ... - - - This menu item starts a Web browser showing the chosen - webpage from: - &EtherealWebSite;. - - - - ------ - - - - - About Ethereal - - - This menu item brings up an information window that - provides some information on Ethereal, such as the plugins, the - used folders, ... - - - - -
- Note! - - Calling a Web browser might be unsupported in your version of Ethereal. - If this is the case, the corresponding menu items will be hidden. - - - Note! - - 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. - - -
- -
The "Main" toolbar - - 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. - - - 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). -
- The "Main" toolbar - -
- - - Main toolbar items - - - - - - - Toolbar Icon - Toolbar Item - Corresponding Menu Item - Description - - - - - - Interfaces... - Capture/Interfaces... - - This item brings up the Capture Interfaces List - dialog box (discussed further in - ). - - - - - - Options... - Capture/Options... - - This item brings up the Capture Options - dialog box (discussed further in - ) and allows you to - start capturing packets. - - - - - - Start - Capture/Start - - This item starts capturing packets with the options form - the last time. - - - - - - Stop - Capture/Stop - - This item stops the currently running live capture process - ). - - - - - - Restart - Capture/Restart - - This item stops the currently running live capture process - and restarts it again, for convenience. - - - - - ------ - - - - - - Open... - File/Open... - - 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 . - - - - - Save As... - File/Save As... - - 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 ). - - Note! - - If you currently have a temporary capture file, the Save icon - will be - shown instead. - - - - - - Close - File/Close - - This item closes the current capture. If you - have not saved the capture, you will be asked to save it first. - - - - - Reload - View/Reload - - This item allows you to reload the current capture file. - - - - - Print... - File/Print... - - 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 - ). - - - - ------ - - - - - - Find Packet... - Edit/Find Packet... - - This item brings up a dialog box that allows you - to find a packet. There is further information on finding packets - in . - - - - - Go Back - Go/Go Back - - This item jumps back in the packet history. - - - - - Go Forward - Go/Go Forward - - This item jumps forward in the packet history. - - - - - Go to Packet... - Go/Go to Packet... - - This item brings up a dialog box that allows you - to specify a packet number to go to that packet. - - - - - Go To First Packet - Go/First Packet - - This item jumps to the first packet of the capture file. - - - - - Go To Last Packet - Go/Last Packet - - This item jumps to the last packet of the capture file. - - - - ------ - - - - - - Colorize - View/Colorize - - Colorize the packet list (or not). - - - - - Auto Scroll in Live Capture - View/Auto Scroll in Live Capture - - Auto scroll packet list while doing a live capture (or not). - - - - ------ - - - - - - Zoom In - View/Zoom In - - Zoom into the packet data (increase the font size). - - - - - Zoom Out - View/Zoom Out - - Zoom out of the packet data (decrease the font size). - - - - - Normal Size - View/Normal Size - - Set zoom level back to 100%. - - - - - Resize Columns - View/Resize Columns - - Resize columns, so the content fits into them. - - - - ------ - - - - - - Capture Filters... - Capture/Capture Filters... - - 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 - . - - - - - Display Filters... - Analyze/Display Filters... - - 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 - . - - - - - Coloring Rules... - View/Coloring Rules... - - 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 - . - - - - - Preferences... - Edit/Preferences - - 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 - - - - ------ - - - - - - Help - Help/Contents - - This item brings up help dialog box. - - - - -
-
- -
The "Filter" toolbar - - The filter toolbar lets you quickly edit and apply display filters. More information on - display filters is available in . -
- The "Filter" toolbar - -
- - - - The leftmost button labeled "Filter:" can be clicked to - bring up the filter construction dialog, described in . - - - - - The left middle text box provides an area to enter or edit display - filter strings, see - . 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. - - Note! - - 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. - - - Note! - - This field is also where the current filter in effect is displayed. - - - - - - 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 - - - - - - The right middle button labeled "Clear" resets the current - display filter and clears the edit area. - - - - - The rightmost button labeled "Apply" applies the current - value in the edit area as the new display filter. - - - - - Note! - - Applying a display filter on large capture files might take quite a long time! - - -
- -
The "Packet List" pane - - The packet list pane displays all the packets in the current capture - file. -
- The "Packet List" pane - -
- 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. - - - 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. - - - 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. - - - There are a lot of different columns available. Which columns are - displayed can be selected by preference settings, see - . - - - The default columns will show: - - - No. - The number of the packet in the capture file. This number won't change, - even if a display filter is used. - - - - Time - The timestamp of the packet. The presentation format of this timestamp - can be changed, see . - - - - Source - The address where this packet is coming from. - - - - Destination - The address where this packet is going to. - - - - Protocol - The protocol name in a short (perhaps abbreviated) version. - - - - Info - Additional information about the packet content. - - - - - - There is a context menu (right mouse click) available, see details in - . - -
- -
The "Packet Details" pane - - The packet details pane shows the current packet (selected in the "Packet List" - pane) in a more detailed form. -
- The "Packet Details" pane - -
- - - 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. - - - There is a context menu (right mouse click) available, see details in - . - - - Some protocol fields are specially displayed. - - - - - Generated fields - 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. - - - - - Links - 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. - - - -
- -
The "Packet Bytes" pane - - The packet bytes pane shows the data of the current packet (selected in the "Packet List" - pane) in a hexdump style. -
- The "Packet Bytes" pane - -
- - - 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. - - - There is a context menu (right mouse click) available, see details in - . - - - 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 . 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. -
- The "Packet Bytes" pane with tabs - -
- - Note! - - The additional pages might contain data picked from multiple packets. - - - - 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. - -
- -
The Statusbar - - The statusbar displays informational messages. - - - In general, the left side will show context related information, while the - right side will show the current number of packets. - - -
- The initial Statusbar - -
- This statusbar is shown while no capture file is loaded, e.g. when - Wireshark is started. - - -
- The Statusbar with a loaded capture file - -
- The left side shows information about the capture file, its - name, its size and the elapsed time while it was being captured. - - - The right side shows the current number of packets in the - capture file. The following values are displayed: - - - P: the number of captured packets - - - D: the number of packets currently being - displayed - - - M: the number of marked packets - - - - -
- The Statusbar with a selected protocol field - -
- This is displayed if you have selected a protocol field from the - "Packet Details" pane. - - Tip! - - The value between the brackets (in this example - arp.opcode) can be used as a display filter string, - representing the selected protocol field. - - -
- - - diff --git a/docbook/eug_src/EUG_chapter_work.xml b/docbook/eug_src/EUG_chapter_work.xml deleted file mode 100644 index 9d083939a3..0000000000 --- a/docbook/eug_src/EUG_chapter_work.xml +++ /dev/null @@ -1,1419 +0,0 @@ - - - - - Working with captured packets - -
Viewing packets you have captured - - 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. - - - You can then expand any part of the tree view by clicking on the - plus 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 - . It also has the Acknowledgment number - in the TCP header selected, which shows up in the byte view as the - selected bytes. -
- Ethereal with a TCP packet selected for viewing - -
- - - 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. - - - In addition, you can view individual packets in a separate window as - shown in . 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. -
- Viewing a packet in a separate window - -
- - - 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. - - - 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. - - - Function overview of the pop-up menus - - - - - - - - - Item - List - Details - Bytes - Menu - Description - - - - - Mark Packet (toggle) - X - - - - - Edit - - Mark a packet. - - - - Time Reference - X - - - - - Edit - - Set/reset and find time references. - - - - Expand Subtrees - - - X - - - View - - Expand the currently selected subtree. - - - - - Expand All - - - X - - - View - - Expand all subtrees in all packets in the capture. - - - - - Collapse All - - - X - - - View - - - 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. - - - - - Apply as Filter - X - X - - - Analyze - - . - - - - Prepare a Filter - X - X - - - Analyze - - . - - - - Follow TCP stream - X - X - - - Analyze - - View all the data on a TCP stream between a pair of nodes. - - - - Wiki Protocol Page - - - X - - - - - - Show the wiki page corresponding to the currently selected protocol in your web browser. - - - - - Filter Field Reference - - - X - - - - - - Show the filter field reference web page corresponding to the currently selected protocol in your web browser. - - - - - Protocol Preferences... - - - X - - - - - - 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 . - - - - - Decode As... - X - X - - - Analyze - - . - - - - - - - Print... - X - - - - - File - - Print (the selected) packet(s). - - - - Show Packet in New Window - X - - - - - View - - Display the selected packet in another window. - - - - Resolve name - - - X - - - View/Name Resolution - - Cause a name resolution to be performed for the selected packet, - but NOT for every packet in the capture. - - - - Go to Corresponding Packet - - - X - - - Go - - 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. - - - - - Copy - - - - - X - - - - Copy the selected packet data to the clipboard (XXX - in which format). - - - - - Export Selected Packet Bytes... - - - - - X - File->Export - - Export raw packet bytes to a binary file. - - - - -
- -
- Pop-up menu of "Packet List" pane - -
- - Mark Packet (toggle) - - - This menu item is the same as the Edit menu item of the same - name. It allows you to mark a packet. - - - - Time Reference - - - 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. - - - - Apply as Filter - - - This menu item is the same as the Analyze menu items of the same - name. - - - - Prepare a Filter - - - This menu item is the same as the Analyze menu items of the same - name. - - - - Follow TCP Stream - - - 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. - - - - Decode As... - - - This menu item is the same as the Analyze menu item of the - same name. - - - - Print... - - - This menu item is the same as the File menu item of the same - name. It allows you to print packets. - - - - - Show Packet in New Window - - - 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. - - - - - - -
- Pop-up menu of "Packet Details" pane - -
- - Expand Subtrees - - - This menu item expands the currently selected subtree. - - - - Expand All - - - This menu item expands all subtrees in all packets in the - capture. - - - - Collapse All - - - 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. - - - - Apply as Filter - - - This menu item is the same as the Analyze menu items of the same - name. - - - - Prepare a Filter - - - This menu item is the same as the Analyze menu items of the same - name. - - - - Follow TCP Stream - - - 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. - - - - Wiki Protocol Page - - - Show the wiki page corresponding to the currently selected protocol - in your web browser. - - - - Filter Field Reference - - - Show the filter field reference web page corresponding to the - currently selected protocol in your web browser. - - - - Protocol Properties... - - - 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 - . - - - - Decode As... - - - This menu item is the same as the Analyze menu item of the - same name. - - - - Resolve Name - - - This menu item causes name resolution to be performed for - the selected packet, but NOT every packet in the capture. - - - - Go to Corresponding Packet - - - If the selected field has a corresponding packet, go to it. - Corresponding packets will usually be a request/response packet pair - or such. - - - - - - -
- Pop-up menu of "Packet Bytes" pane - -
- - Copy - - - Copy the selected packet data to the clipboard (XXX - in which format). - - - - Export Selected Packet Bytes... - - - 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. - - - - - -
- -
Filtering packets while viewing - - 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 . - - - 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: - - Protocol - The presence of a field - The values of fields - A comparison between fields - ... and a lot more! - - - - To select packets based on protocol type, simply type the protocol you - are interested in in the Filter: field in the filter - toolbar of the Wireshark window and press enter to initiate - the filter. shows an example of what - happens when you type tcp in the filter field. - - - Note! - - All protocol and field names are entered in lowercase. Also, don't - forget to press enter after entering the filter expression. - - -
Filtering on the TCP protocol - -
- - 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. - - - Note! - - 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! - - - - 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 - Add Expression... dialog box. You can find more - information on the Add Expression... dialog box - in . - - - For example, to narrow the packet list pane down to only those - packets to or from the IP address 192.168.0.1, use - ip.addr==192.168.0.1. - - - Note! - - To remove the filter, click on the Clear button - to the right of the filter field. - - -
- -
- Building display filter expressions - - 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. - - - Tip! - - You will find a lot of Display Filter examples at the Ethereal - Wiki Display Filter page at &EtherealWikiDisplayFiltersPage;. - - -
- Display filter fields - - 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: tcp will show all packets containing the - tcp protocol. - - - 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. - - - XXX - add some more info here and a link to the statusbar info. - -
-
- Comparing values - - You can build display filters that compare values using a number - of different comparison operators. They are shown in - . - - Tip! - - You can use English and C-like terms in the same way, they can even be - mixed in a filter string! - - - - Display Filter comparison operators - - - - - - English - C-like - Description and example - - - - - eq - == - - Equal - ip.addr==10.0.0.5 - - - - ne - != - - Not equal - ip.addr!=10.0.0.5 - - - - gt - > - - Greater than - frame.pkt_len > 10 - - - - lt - < - Less than - frame.pkt_len < 128 - - - - ge - >= - - Greater than or equal to - frame.pkt_len ge 0x100 - - - - le - <= - - Less than or equal to - frame.pkt_len <= 0x20 - - - - -
- - In addition, all protocol fields are typed. - provides a list of the types and - example of how to express them. - - Display Filter Field Types - - - - Type - Example - - - - - - Unsigned integer (8-bit, 16-bit, 24-bit, 32-bit) - - - You can express integers in decimal, octal, or - hexadecimal. The following display filters are - equivalent: - -ip.len le 1500 -ip.len le 02734 -ip.len le 0x436 - - - - - - Signed integer (8-bit, 16-bit, 24-bit, 32-bit) - - - - - Boolean - - A boolean field is present in the protocol decode - only if its value is true. For example, - tcp.flags.syn is present, and - thus true, only if the SYN flag is present in a - TCP segment header. - Thus the filter expression - tcp.flags.syn 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 - tr.sr. - - - - Ethernet address (6 bytes) - eth.addr == ff:ff:ff:ff:ff:ff - - - IPv4 address - ip.addr == 192.168.0.1 - - - IPv6 address - - - - IPX network number - - - - String (text) - - - - - Double-precision floating point number - - - - - -
- -
-
- Combining expressions - - You can combine filter expressions in Wireshark using the - logical operators shown in - - - Display Filter Logical Operations - - - - - - English - C-like - Description and example - - - - - and - && - - Logical AND - ip.addr==10.0.0.5 and tcp.flags.fin - - - - or - || - - Logical OR - ip.addr==10.0.0.5 or ip.addr==192.1.1.1 - - - - xor - ^^ - - Logical XOR - tr.dst[0:3] == 0.6.29 xor tr.src[0:3] == 0.6.29 - - - - not - ! - - Logical NOT - not llc - - - - [...] - - - Substring Operator - 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. - eth.src[0:3] == 00:00:83 - 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. - -eth.src[1-2] == 00:83 - - 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. - eth.src[:4] == 00:00:83:00 - 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 - eth.src[4:] == 20:20 - The example above uses the n: format, which takes - everything from offset n to the end of the - sequence. - eth.src[2] == 83 - 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. - eth.src[0:3,1-2,:4,4:,2] == -00:00:83:00:83:00:00:83:00:20:20:83 - Ethereal allows you to string together single ranges - in a comma separated list to form compound ranges as - shown above. - - - - -
-
-
A common mistake - Warning! - - Using the != operator on combined expressions like: eth.addr, ip.addr, - tcp.port, udp.port and alike will probably not work as expected! - - - - Often people use a filter string to display something like - ip.addr == 1.2.3.4 which will display all packets - containing the IP address 1.2.3.4. - - - Then they use ip.addr != 1.2.3.4 to see all packets - not containing the IP address 1.2.3.4 in it. Unfortunately, this does - not do the expected. - - - 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 ip.addr != 1.2.3.4 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. - - - 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 !(ip.addr == 1.2.3.4) 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". - -
-
- -
- The "Filter Expression" dialog box - - 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. - - Tip! - - The "Filter Expression" dialog box is an excellent way to learn how to - write Ethereal display filter strings. - - -
- The "Filter Expression" dialog box - -
- - 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. - - - Field Name - - - 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. - - - - Relation - - - Select a relation from the list of available relation. - The is present 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 Value to match) to complete. - - - - - - 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. - - - Value - - - You may enter an appropriate value in the - Value text box. The Value - will also indicate the type of value for the - field name you have selected (like - character string). - - - - Predefined values - - - 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. - - - - Range - - - XXX - add an explanation here! - - - - OK - - - When you have built a satisfactory expression click - OK and a filter string will be - built for you. - - - - Cancel - - - You can leave the Add Expression... dialog - box without any effect by clicking the Cancel - - - - -
- -
Defining and saving filters - - 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. - - - To define a new filter or edit an existing one, select the - Capture Filters... menu item from the Capture menu - or the Display Filters... menu item from the Analyze - menu. Ethereal will then pop up the Filters dialog as shown in - . - - - Note! - - 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. - - - Warning! - - You must use Save to save your filters permanently. - Ok or Apply will not save the filters, - so they will be lost when you close Ethereal. - - -
- The "Capture Filters" and "Display Filters" dialog boxes - -
- - - New - - - 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". - - - - Delete - - - This button deletes the selected filter. It will be greyed out, if no - filter is selected. - - - - Filter - - - 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). - - - - Filter name: - - - You can change the name of the currently selected filter here. - - Note! - - 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. - - - - - Filter string: - - - 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. - - - - Add Expression... - - - 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 - - - - - OK - - - Display Filter only: This button applies the selected filter to the - current display and closes the dialog. - - - - Apply - - - Display Filter only: This button applies the selected filter to the - current display, and keeps the dialog open. - - - - Save - - - Save the current settings in this dialog. The file location and - format is explained in . - - - - Close - - - Close this dialog. This will discard unsaved settings. - - - - - -
- -
Finding packets - - You can easily find packets once you have captured some packets or - have read in a previously saved capture file. Simply select the - Find Packet... menu item from the - Edit menu. Ethereal will pop up the dialog box - shown in . - -
The "Find Packet" dialog box -
- The "Find Packet" dialog box - -
- - You might first select the kind of thing to search for: - - - - Display filter - - - Simply enter a display filter string into the - Filter: field, select a direction, and click on OK. - - - For example, to find the three way handshake for a connection from - host 192.168.0.1, use the following filter string: - ip.addr==192.168.0.1 and tcp.flags.syn - For more details on display filters, see - - - - - Hex Value - - - Search for a specific byte sequence in the packet data. - - - For example, use "00:00" to find the next packet including two - null bytes in the packet data. - - - - - String - - - Find a string in the packet data, with various options. - - - - - - 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. - - - You can choose the direction to be searched for: - - - Up - Search upwards in the packet list (decreasing packet numbers). - - - - - Down - Search downwards in the packet list (increasing packet numbers). - - - -
-
The "Find Next" command - - "Find Next" will continue searching with the same options like in the last - "Find Packet" run. - -
-
The "Find Previous" command - - "Find Previous" will do the same thing as "Find Next", but with reverse - search direction. - -
-
- -
Go to a specific packet - - You can easily jump to specific packets with one of the menu items in the - Go menu. - -
The "Go Back" command - - Go back in the packet history, works much like the page history in current - web browsers. - -
-
The "Go Forward" command - - Go forward in the packet history, works much like the page history in - current web browsers. - -
-
The "Go to Packet" dialog box -
- The "Go To Packet" dialog box - -
- - This dialog box will let you enter a packet number. When you press - OK, Ethereal will jump to that packet. - -
-
The "Go to Corresponding Packet" command - - If a protocol field is selected which points to another packet in the - capture file, this command will jump to that packet. - - Note! - - 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. - - -
-
The "Go to First Packet" command - - This command will simply jump to the first packet displayed. - -
-
The "Go to Last Packet" command - - This command will simply jump to the last packet displayed. - -
-
- -
Marking packets - - 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. - - Warning! - - 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. - - - - 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 . - - - There are three functions to manipulate the marked state of a packet: - - - - Mark packet (toggle) toggles the marked state - of a single packet. - - - - - Mark all packets set the mark state of all - packets. - - - - - Unmark all packets reset the mark state of all - packets. - - - - 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. - -
- -
Time display formats and time - references - - 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. - - - A detailed description of timestamps, timezones and alike can be found at: . - - - The timestamp presentation format and the precision in the packet list can - be chosen using the View menu, see . - - - The available presentation formats are: - - Date and Time of Day: 1970-01-01 01:02:03.123456 - The absolute date and time of the day when the packet was captured. - - Time of Day: 01:02:03.123456 - The absolute time of the day when the packet was captured. - - Seconds Since Beginning of Capture: 123.123456 - The time relative to the start of the capture file or the first - "Time Reference" before this packet (see ). - - Seconds Since Previous Packet: 1.123456 - The time relative to the previous packet. - - - - - The available precisions (aka. the number of displayed decimal places) are: - - Automatic - The timestamp precision of - the loaded capture file format will be used (the default). - - Seconds, Deciseconds, Centiseconds, Milliseconds, - Microseconds or Nanoseconds - 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. - - - - - 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. - -
- Packet time referencing - - 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. - - Warning! - - The time references will not be saved permanently and will be lost when - you close the capture file. - - - Note! - - 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). - - - - To work with time references, choose one of the "Time Reference" items - in the "Edit" menu , see , or from - the pop-up menu of the "Packet List" pane. - - - Set Time Reference (toggle) - Toggles the time reference state of the currently selected - packet to on or off. - - Find Next - Find the next time referenced packet in the "Packet List" pane. - - - Find Previous - Find the previous time referenced packet in the "Packet List" - pane. - - - - -
- Ethereal showing a time referenced packet - -
- - - 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. - -
-
- - - - diff --git a/docbook/eug_src/EUG_meta_info.xml b/docbook/eug_src/EUG_meta_info.xml deleted file mode 100644 index 62005e27d6..0000000000 --- a/docbook/eug_src/EUG_meta_info.xml +++ /dev/null @@ -1,38 +0,0 @@ - - - - <inlinegraphic entityref="EtherealLogo" valign="middle" format="PNG"/> &DocumentTitle; - &DocumentSubTitle; - - - &AuthorFirstName; - &AuthorSurname; - &AuthorOrgName; - - - &AuthorFirstName2; - &AuthorSurname2; - &AuthorOrgName2; - - - &AuthorFirstName3; - &AuthorSurname3; - &AuthorOrgName3; - - - - - &DocumentCopyrightYear; - &DocumentCopyrightHolder1; - &DocumentCopyrightHolder2; - &DocumentCopyrightHolder3; - - - - - - &DocumentLegalNotice; - - - diff --git a/docbook/eug_src/EUG_preface.xml b/docbook/eug_src/EUG_preface.xml deleted file mode 100644 index 665fc98423..0000000000 --- a/docbook/eug_src/EUG_preface.xml +++ /dev/null @@ -1,171 +0,0 @@ - - - - Preface -
- Foreword - - 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. - - - This document is part of an effort by the Wireshark team to improve the - usability of Ethereal. - - - We hope that you find it useful, and look forward to your comments. - -
- -
- Who should read this document? - - The intended audience of this book is anyone using Ethereal. - - - 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. - - - 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 - &EtherealWikiPage; - - - 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. - -
- -
- Acknowledgements - - The authors would like to thank the whole Ethereal team for their - assistance. In particular, the authors would like to thank: - - - - Gerald Combs, for initiating the Wireshark project and funding to - do this documentation. - - - - - Guy Harris, for many helpful hints and a great deal of patience - in reviewing this document. - - - - - Gilbert Ramirez, for general encouragement and helpful hints along - the way. - - - - - - The authors would also like to thank the following people for their - helpful feedback on this document: - - - - Pat Eyler, for his suggestions on improving the example on - generating a backtrace. - - - - - Martin Regner, for his various suggestions and corrections. - - - - - Graeme Hewson, for a lot of grammatical corrections. - - - - - - The authors would like to acknowledge those man page and README authors - for the ethereal project from who sections of this document borrow heavily: - - - - Scott Renfro from whose mergecap man page - is derived. - - - - - Ashok Narayanan from whose text2pcap man page - is derived. - - - - - Frank Singleton from whose README.idl2eth - is derived. - - - - -
- -
- About this document - - This book was originally developed by - Richard Sharpe with - funds provided from the Wireshark Fund. It was updated by - Ed Warnicke and more recently - redesigned and updated by Ulf - Lamping. - - - It is written in DocBook/XML. - - - You will find some specially marked parts in this book: - - This is a warning! - - You should pay attention to a warning, as otherwise data loss might occur. - - - This is a note! - - A note will point you to common mistakes and things that might not be - obvious. - - - This is a tip! - - Tips will be helpful for your everyday work using Ethereal. - - -
- -
- Where to get the latest copy of this document? - - The latest copy of this documentation can always be found at: - . - -
- -
- Providing feedback about this document - - Should you have any feedback about this document, please send them - to the authors through &EtherealDevMailList;. - -
- diff --git a/docbook/user-guide.xml b/docbook/user-guide.xml index d870c5835f..03341bea36 100644 --- a/docbook/user-guide.xml +++ b/docbook/user-guide.xml @@ -250,23 +250,23 @@ FILE SECTION - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + ]> diff --git a/docbook/ws.css b/docbook/ws.css new file mode 100644 index 0000000000..78fc2250a4 --- /dev/null +++ b/docbook/ws.css @@ -0,0 +1,6 @@ +div.sidebar { + background-color: #DDDDDD; + border: 1px solid black; + margin: 6px; + padding: 0px 6px 0px 6px; +} 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 @@ + + + + + Configuration (and other) Files and Folders + + 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. + + Tip + A list of the folders Ethereal actually uses can be found under the + Folders tab in the dialog box coming up, when you select + About Ethereal from the Help menu. + + + + 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. + + + Configuration files and folders overview + + + + + + + File/Folder + Description + Unix/Linux folders + Windows folders + + + + + preferences + Settings from the Preferences dialog box. + /etc/ethereal.conf, $HOME/.ethereal/preferences + %ETHEREAL%\ethereal.conf, %APPDATA%\Ethereal\preferences + + + recent + Recent GUI settings (e.g. recent files lists). + $HOME/.ethereal/recent + %APPDATA%\Ethereal\recent + + + cfilters + Capture filters. + $HOME/.ethereal/cfilters + %ETHEREAL%\cfilters, %APPDATA%\Ethereal\cfilters + + + dfilters + Display filters. + $HOME/.ethereal/dfilters + %ETHEREAL%\dfilters, %APPDATA%\Ethereal\dfilters + + + colorfilters + Coloring rules. + $HOME/.ethereal/colorfilters + %ETHEREAL%\colorfilters, %APPDATA%\Ethereal\colorfilters + + + disabled_protos + Disabled protocols. + $HOME/.ethereal/disabled_protos + %ETHEREAL%\disabled_protos, %APPDATA%\Ethereal\disabled_protos + + + ethers + Ethernet name resolution. + /etc/ethers, $HOME/.ethereal/ethers + %ETHEREAL%\ethers, %APPDATA%\Ethereal\ethers + + + manuf + Ethernet name resolution. + /etc/manuf + %ETHEREAL%\manuf + + + hosts + IPv4 and IPv6 name resolution. + $HOME/.ethereal/hosts + %APPDATA%\hosts + + + ipxnets + IPX name resolution. + $HOME/.ethereal/ipxnets + %ETHEREAL%\ipxnets + + + plugins + Plugin directories. + /usr/share/ethereal/plugins, + /usr/local/share/ethereal/plugins, + $HOME/.ethereal/plugins + + %ETHEREAL%\plugins\<version>, + %APPDATA%\Ethereal\plugins + + + temp + Temporary files. + Environment: TMPDIR + Environment: TMPDIR or TEMP + + + +
+ Windows folders + + %APPDATA% points to the personal configuration folder, typically + C:\Documents and Settings\<username>\Application Data + (for further details, have a look at ), + %ETHEREAL% points to the Wireshark program folder, typically + C:\Program Files\Ethereal + + + Unix/Linux folders + + The /etc folder is the global Ethereal configuration + folder. The folder actually used on your system + may vary, maybe something like: /usr/local/etc. + + + + + + preferences/ethereal.conf + + + This file contains your Ethereal preferences, + including defaults for capturing and displaying packets. + It is a simple text file containing statements of the form: + +variable: value + + 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. + + + + + recent + + + 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: + +variable: value + + It is read at program start and written at program exit. + + + + cfilters + + + 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: + +"<filter name>" <filter string> + + 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. + + + + dfilters + + + 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: + +"<filter name>" <filter string> + + 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. + + + + + colorfilters + + + 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: + +@<filter name>@<filter string> +@[<bg RGB(16-bit)>][<fg RGB(16-bit)>] + + + + 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. + + + + + disabled_protos + + + Each line in this file specifies a disabled protocol name. The + following are some examples: + +tcp +udp + + + + 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. + + + + + + ethers + + + + When Wireshark is trying to translate Ethernet hardware + addresses to names, it consults the files listed in + . + If an address is not found in /etc/ethers, + Ethereal looks in $HOME/.ethereal/ethers + + + 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: + +ff-ff-ff-ff-ff-ff Broadcast +c0-00-ff-ff-ff-ff TR_broadcast +00.2b.08.93.4b.a1 Freds_machine + + The settings from this file are read in at program start and never + written by Wireshark. + + + + + manuf + + + Ethereal uses the files listed in + 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. + + + An example is: + +00:00:01 Xerox # XEROX CORPORATION + + + + The settings from this file are read in at program start and never + written by Wireshark. + + + + + hosts + + + Ethereal uses the files listed in + to translate IPv4 and IPv6 addresses into names. + + + This file has the same format as the usual /etc/hosts file in unix systems. + + + An example is: + +# Comments must be prepended by the # sign! +192.168.0.1 homeserver + + + + The settings from this file are read in at program start and never + written by Wireshark. + + + + + ipxnets + + + Ethereal uses the files listed in + to translate IPX network numbers into names. + + + An example is: + +C0.A8.2C.00 HR +c0-a8-1c-00 CEO +00:00:BE:EF IT_Server1 +110f FileServer3 + + + + The settings from this file are read in at program start and never + written by Wireshark. + + + + + plugins folder + + + Ethereal searches for plugins in the directories listed in + . + They are searched in the order listed. + + + + + temp folder + + + If you start a new capture and don't specify a filename for it, + Ethereal uses this directory to place that file in, see + . + + + + + + +
Windows folders + + Here you will find some details about the folders used in Wireshark + on different Windows versions. + + + As already mentioned, you can find the currently used folders in the + About Ethereal dialog. + + +
Windows profiles + + 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. + + Note! + + 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. + + + + The following will try to guide + you to the right place where to look for Wiresharks profile data. + + + + + 95/98/ME + + + The default in Windows 95/98/ME is: all users work with the same profile, + which is located at: + C:\windows\Application Data\Ethereal + + + + + 98/ME (with enabled user profiles) + + + In Windows 98 and ME you can enable separate user profiles. In that case, + something like: + C:\windows\Profiles\<username>\Application Data\Ethereal + is used. + + + + + NT 4 + + + C:\WINNT\Profiles\<username>\Application Data\Ethereal + + + + + 2000/XP + + + C:\Documents and Settings\<username>\Application Data, + "Documents and Settings" and "Application Data" might be internationalized. + + + + + +
+ +
+ Windows NT/2000/XP roaming profiles + + 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. + + + 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. + + + There is an exception to this: The "Local Settings" folder in your profile + data (typically something like: + C:\Documents and Settings\<username>\Local Settings) + will not be transferred to the domain server. This is the default for + temporary capture files. + +
+ +
+ Windows temporary folder + + Ethereal uses the folder which is set by the TMPDIR or TEMP environment + variable. This variable will be set by the windows installer. + + + The default location for temporary files on NT 4 is just + C:\TEMP, and in 2000 the default location + is some directory under your profile directory but it might have + "Temporary Files" in the path name. + +
+ +
+ + + 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 @@ + + + + + How Ethereal Works + + 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. + + +
Program start + + When Etheral starts, a lot of things are done: + + + initialize the dissectors (register the protocol tree), including plugins + + + load and set values from the preferences file + + + load the capture filters from the cfilters file + + + load the display filters from the dfilters file + + + load and set the disabled protocols from the disabled_protos file + + + init libpcap/winpcap (the capturing engine) + + + process command line parameters + + + load and set the recently used GUI settings from the recent file + + + init and show the main screen + + + if specified by command line, load a capture file or start capturing + + + + + + +
+ +
Protocol dissectors + + 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. + + + So Ethereal will dissect a packet from the lowest to the highest protocol + layers. + + + But how does Ethereal know, which dissector to choose? + + + 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: + + + static 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). + + + heuristic 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. + + + + + 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. + + + You can control the way how Ethereal calls it's dissectors, see for details. + +
+ + + 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 @@ + + + + + Ethereal Messages + + 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. + +
Packet List Messages + + These messages might appear in the packet list. + +
[Malformed Packet] + + Malformed packet means that the protocol dissector can't work out the + contents of the packet any further. This can have various reasons: + + + + Wrong dissector + 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. + + + + + Packet not reassembled + The packet is longer than a single frame and it is not reassembled, + see for further details. + + + + + Packet is malformed + The packet is actually wrong (malformed), meaning that a part of the + packet is just not as expected (not following the protocol + specifications). + + + + + Dissector is buggy + The corresponding protocol dissector is simply buggy or still + incomplete. + + + + + + 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. + +
+
[Packet size limited during capture] + + The packet size was limited during capture, see "Limit each packet to n + bytes" at the . + 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. + +
+
+ +
Packet Details Messages + + These messages might appear in the packet details. + +
[Response in frame: 123] + + 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. + +
+
[Request in frame: 123] + + Same as "Response in frame: 123" above, but the other way round. + +
+
[Time from request: 0.123 seconds] + + The time between the request and the response packets. + +
+
+ + + 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 @@ + + + + + Protocols and Protocol Fields + + Ethereal distinguishes between protocols (e.g. tcp) and protocol fields + (e.g. tcp.port). + + + A comprehensive list of all protocols and protocol fields can be found + at: &EtherealProtocolsPage; + + + 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 @@ + + + + + + Related command line tools + +
+ Introduction + + 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. + +
+ +
+ <command>tcpdump</command>: Capturing with tcpdump for viewing + with Ethereal + + There are occasions when you want to capture packets using + tcpdump rather than ethereal, + 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). + + + However, the default tcpdump parameters result in a + capture file where each packet is truncated, because + tcpdump, by default, does only capture the first 68 + bytes of each packet. + + + To ensure that you capture complete packets, use the following command: + +tcpdump -i <interface> -s 1500 -w <some-file> + + You will have to specify the correct interface and + the name of a file to save into. In addition, + you will have to terminate the capture with ^C when you believe you + have captured enough packets. + + Note! + + tcpdump is not part of the Wireshark distribution. You can get it from: + http://www.tcpdump.org for various + platforms. + + +
+ +
+ <command>tethereal</command>: Terminal-based Ethereal + + Tethereal 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 ethereal. For more + information on tethereal, see the manual pages + (man tethereal). + +
+ +
+ <command>capinfos</command>: Print information about capture files + + + Included with Wireshark is a small utility called + capinfos, which is a command-line utility to + print information about binary capture files. + + + + Help information available from capinfos + +$ 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 + + + +
+ +
+ <command>editcap</command>: Edit capture files + + Included with Wireshark is a small utility called + editcap, 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. + + + + + Help information available from editcap + +$ 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 + + + + Where each option has the following meaning: + + -r + + + This option specifies that the frames listed should be kept, + not deleted. The default is to delete the listed frames. + + + + -h + This option provides help. + + -v + + + This option specifies verbose operation. The default is + silent operation. + + + + -T {encap type} + + + This option specifies the frame encapsulation type to use. + + + It is mainly for converting funny captures to something + that Ethereal can deal with. + + + The default frame + encapsulation type is the same as the input encapsulation. + + + + + -F {capture type} + + + This option specifies the capture file format to write + the output file in. + + + The default is libpcap format. + + + + -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. + + + + {infile} + + + This parameter specifies the input file to use. It must be + present. + + + + {outfile} + + + This parameter specifies the output file to use. It must + be present. + + + + + [record#[-][record# ...]] + + + This optional parameter specifies the records to include + or exclude (depending on the -r option. + You can specify individual records or a range of records. + + + + + +
+ +
+ <command>mergecap</command>: + Merging multiple capture files into one + + + 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. + + + 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. + + + 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. + + + 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). + + + + 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). + + + Help information available from mergecap + +$ 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 + + + + -h + + Prints the version and options and exits. + + + -v + + + Causes mergecap to print a number of messages + while it's working. + + + + -a + + + 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 -a 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. + + + + -s + + Sets the snapshot length to use when writing the data. + + + -w + + Sets the output filename. + + + -T + + + Sets the packet encapsulation type of the output capture file. + + + + -F + + Sets the file format of the output capture file. + + + + + A simple example merging dhcp-capture.libpcap + and imap-1.libpcap into + outfile.libpcap is shown below. + + + Simple example of using mergecap + $ mergecap -w outfile.libpcap dhcp-capture.libpcap imap-1.libpcap + + +
+ +
+ <command>text2pcap</command>: Converting ASCII hexdumps to network + captures + + + There may be some occasions when you wish to convert a hex dump of some + network traffic into a libpcap file. + + Text2pcap 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. + + + 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: + + +000000 00 e0 1e a7 05 6f 00 10 ........ +000008 5a a0 b9 12 08 00 46 00 ........ +000010 03 68 00 00 00 00 0a 2e ........ +000018 ee 33 0f 19 08 7f 0f 19 ........ +000020 03 80 94 04 00 00 10 01 ........ +000028 16 a2 0a 00 03 50 00 0c ........ +000030 01 01 0f 19 03 80 11 01 ........ + + + There is no limit on the width or number of bytes per line. Also the + text dump at the end of the line is ignored. 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.) + + + 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. + + + 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. + + + Help information available for text2pcap + +$ 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. + + + + -w <filename> + + + Write the capture file generated by text2pcap + to <filename>. The default is to write to standard + output. + + + + -h + + Display the help message + + + -d + + + Displays debugging information during the process. Can be + used multiple times to generate more debugging information. + + + + -q + + Be completely quiet during the process. + + + -o hex|oct + + Specify the radix for the offsets (hex or octal). Defaults to + hex. This corresponds to the -A option for od. + + + + -l + + + 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. + + + + -e l3pid + + + 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. + + + 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. + + + + -u srcport destport + + + 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. + + + + +
+ +
+ <command>idl2eth</command>: + Creating dissectors from Corba IDL files + + + 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. + +
+ What is it? + + As you have probably guessed from the name, + idl2eth 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. + + + idl2eth 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. + + It consists of 4 main files. + + README.idl2eth + + This document + + + ethereal_be.py + + The main compiler backend + + + ethereal_gen.py + + A helper class, that generates the C code. + + + idl2eth + + A simple shell script wrapper that the end user should + use to generate the dissector from the IDL file(s). + + + +
+
+ Why do this? + + 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. + + + 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". + + + It is also COOL to work on a great Open Source project such as + the case with "Ethereal" ( + http://www.ethereal.com + ) + +
+
How to use idl2eth + + To use the idl2eth to generate ethereal dissectors, you + need the following: + + + Prerequisites to using idl2eth + + + Python must be installed. See + + + + + + omniidl from the the omniORB package must be available. See + + + + + + Of course you need ethereal installed to compile the + code and tweak it if required. idl2eth is part of the + standard Ethereal distribution + + + + + To use idl2eth to generate an ethereal dissector from an idl file + use the following procedure: + + + + Procedure for converting a Corba idl file into an ethereal + dissector + + + + To write the C code to stdout. + idl2eth <your file.idl> + eg: idl2eth echo.idl + + + + + To write to a file, just redirect the output. + idl2eth echo.idl > packet-test-idl.c + You may wish to comment out the register_giop_user_module() code + and that will leave you with heuristic dissection. + + + + + If you don't want to use the shell script wrapper, then try + steps 3 or 4 instead. + + + To write the C code to stdout. + Usage: omniidl -p ./ -b ethereal_be <your file.idl> + eg: + omniidl -p ./ -b ethereal_be echo.idl + + + + + To write to a file, just redirect the output. + omniidl -p ./ -b ethereal_be echo.idl > packet-test-idl.c + You may wish to comment out the register_giop_user_module() code + and that will leave you with heuristic dissection. + + + + + Copy the resulting C code to your ethereal src directory, + edit the 2 make files to include the packet-test-idl.c + +cp packet-test-idl.c /dir/where/ethereal/lives/ +edit Makefile.am +edit Makefile.nmake + + + + + Run configure + ./configure (or ./autogen.sh) + + + + Compile the code + make + + + + Good Luck !! + + +
+
TODO + + + + Exception code not generated (yet), but can be added manually. + + + + + Enums not converted to symbolic values (yet), but can be added + manually. + + + + Add command line options etc + + + More I am sure :-) + + +
+
Limitations + + See the TODO list inside packet-giop.c + +
+
Notes + + + + 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. + + + + + 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/ + + + +
+
+ + + + 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 @@ + + + + + + Advanced Topics + +
Introduction + + In this chapter some of the advanced features of Ethereal will be described. + +
+ +
Following TCP streams + + 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. + + + 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 . + + + Note! + + It is worthwhile noting that Follow TCP Stream installs a display filter + to select all the packets in the TCP stream you have selected. + + +
The "Follow TCP Stream" dialog box +
+ The "Follow TCP Stream" dialog box + +
+ + 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. + + + None printable characters will be replaced by dots. + XXX - What about line wrapping (maximum line length) and CRNL conversions? + + + The stream content won't be updated while doing a live capture. + To get the latest content you'll have to reopen the dialog. + + + You can choose from the following actions: + + + + Save As Save the stream data in the currently + selected format. + + + + + Print Print the stream data in the currently + selected format. + + + + + Direction Choose the stream direction to be + displayed ("Entire conversation", "data from A to B only" or "data + from B to A only"). + + + + + Filter out this stream Apply a display filter + removing the current TCP stream data from the display. + + + + + Close Close this dialog box, leaving the current + display filter in effect. + + + + + + You can choose to view the data in one of the following formats: + + + + ASCII. In this view you see the data from + each direction in ASCII. Obviously best for ASCII based protocols, + e.g. HTTP. + + + + + EBCDIC. For the big-iron freaks out there. + + + + + HEX Dump. This allows you to see all the + data. + This will require a lot of screen space and is best used with + binary protocols. + + + + + C Arrays. This allows you to import the stream data + into your own C program. + + + + + Raw. 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. + + + + +
+
+ +
Time Stamps + + 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. + + + 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. + + + 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. + +
Ethereal internals + + 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 + for details. + + + While reading or writing capture files, Ethereal converts the time stamp + data between the capture file format and the internal format as required. + + + 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. + +
+
Capture file formats + + 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). + + + 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. + + + Note! + + 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. + + +
+
Accuracy + + 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! + + 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. + + + 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?) + + + +
+
+ +
Time Zones + + 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 ;-) + + + First of all, there are two reasons why you may not need to think about + time zones at all: + + + + 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). + + + + + 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. + + + + + What are time zones? + + 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. + + + For that reason, the earth is split into several different time zones, + each zone with a local time that corresponds to the local sunset. + + + 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! + + + 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". + + + 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)! + + + Further information can be found at: + &WikipediaTimezone; and + &WikipediaUTC;. + + + + What is daylight saving time (DST)? + + 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". + + + 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). + + + Keep in mind: UTC remains the same all year around, regardless of DST! + + + Further information can be found at: + &WikipediaDaylightSaving;. + + + + Further time zone and DST information can be found at: + &TimezoneGMTSite; and + &TimezoneWorldClockSite;. + +
Set your computer's time correct! + + If you work with people around the world, it's very helpful to set your + computer's time and time zone right. + + + You should set your computers time and time zone in the correct sequence: + + + + Set your time zone to your current location + + + + + Set your computer's clock to the local time + + + + This way you will tell your computer both the local time and also the time + offset to UTC. + Tip! + + 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! + + + Tip! + + 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: + &NTPSite;. + + + +
+
Ethereal and Time Zones + + So what's the relationship between Ethereal and time zones anyway? + + + 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. + + + 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. + + + 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. + + + 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. + + + + Time zone examples for UTC arrival times (without DST) + + + + + + Los Angeles + New York + Madrid + London + Berlin + Tokyo + + + + + Capture File (UTC) + 10:00 + 10:00 + 10:00 + 10:00 + 10:00 + 10:00 + + + Local Offset to UTC + -8 + -5 + -1 + 0 + +1 + +9 + + + Displayed Time (Local Time) + 02:00 + 05:00 + 09:00 + 10:00 + 11:00 + 19:00 + + + +
+ + + 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. + + + 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. + + + Conclusion: 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. + +
+
+ +
Packet Reassembling +
What is it? + + 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. + + + 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. + + Tip! + + Ethereal calls this mechanism reassembling, although a specific protocol + specification might use a different term for this (e.g. desegmentation, + defragmentation, ...). + + +
+
How Ethereal handles it + + 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 ). + + +
+ The "Packet Bytes" pane with a reassembled tab + +
+ + + Note! + + Reassembling might take place at several protocol layers, so it's possible + that multiple tabs in the "Packet Bytes" pane appear. + + + Note! + + You will find the reassembled data in the last packet of the chunk. + + + + An example: + In a HTTP 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. + + + 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. + + + The enabling or disabling of the reassemble settings of a protocol typically + requires two things: + + + + the lower level protocol (e.g., TCP) must support + reassembly. Often this reassembly can be enabled or disabled + via the protocol preferences. + + + + + 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. + + + + + + The tooltip of the higher level protocol setting will note you if and + which lower level protocol setting has to be considered too. + +
+
+ +
Name Resolution + + 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 . + + + The name resolution feature can be en-/disabled separately for the + protocol layers of the following sections. + + +
Name Resolution drawbacks + + Name resolution can be invaluable while working with Ethereal and may + save you even hours of work. Unfortunately, it also has it's drawbacks. + + + + + Name resolution will often fail. 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. + + + + + The resolved names are not stored in the capture file or + somewhere else. + So the resolved names might not be available if you open the capture file + later or on 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). + + + + + DNS may add additional packets to your capture file. + 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? + + + + + Resolved DNS names are cached by Wireshark. + 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? + + + + Tip! + + 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. + + +
+ +
Ethernet name resolution (MAC layer) + + Try to resolve an Ethernet MAC address (e.g. 00:09:5b:01:02:03) to + something more "human readable". + + ARP name resolution (system service) + 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). + + Ethernet codes (ethers file) + 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). + + Ethernet manufacturer codes (manuf file) + 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). + +
+ +
IP name resolution (network layer) + + Try to resolve an IP address (e.g. 65.208.228.223) to + something more "human readable". + + DNS/ADNS name resolution (system/library service) + 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). + + + Warning! + + 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. + + + + DNS vs. ADNS + 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. + + + 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. + + hosts name resolution (hosts file) + 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). + +
+ +
IPX name resolution (network layer) + ipxnet name resolution (ipxnets file) + XXX - add ipxnets name resolution explanation. + +
+ +
TCP/UDP port name resolution (transport layer) + + Try to resolve a TCP/UDP port (e.g. 80) to + something more "human readable". + + TCP/UDP port conversion (system service) + Ethereal will ask the operating system to convert a TCP or UDP port to + its well known name (e.g. 80 -> http). + + + XXX - mention the role of the /etc/services file + (but don't forget the files and folders section)! + +
+
+ +
Checksums + + Several network protocols use checksums to ensure data integrity. + + Tip! + + Applying checksums as described here is also known as + redundancy check. + + + What are checksums for? + + 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. + + + 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. + + + 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. + + + Some checksum algorithms are able to recover (simple) errors by + calculating where the expected error must be and repairing it. + + + 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). + + + 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. + + + 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. + + + Further information about checksums can be found at: + . + + +
Ethereal checksum validation + + Ethereal will validate the checksums of several potocols, e.g.: IP, TCP, ... + + + 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. + + + Checksum validation can be switched off for various protocols in the + Ethereal protocol preferences, e.g. to (very slightly) increase + performance. + + + 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. + +
+ +
Checksum offloading + + The checksum calculation might be done by the network driver, protocol + driver or even in hardware. + + + 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. + + + Higher level checksums are "traditionally" calculated by the protocol + implementation and the completed packet is then handed over to the + hardware. + + + 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. + + Note! + + 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. + + + + 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. + + + You can do two things to avoid this checksum offloading problem: + + + + Turn off the checksum offloading in the network driver, if this option is + available. + + + + + Turn off checksum validation of the specific protocol in the Wireshark + preferences. + + + + +
+
+ + + + 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 @@ + + + + + Building and Installing Ethereal +
+ Introduction + + As with all things, there must be a beginning, and so it is with + Ethereal. To use Ethereal, you must: + + + + Obtain a binary package for your operating system, or + + + + + Obtain the source and build Ethereal for your operating system. + + + + + + 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. + + + This chapter shows you how to obtain source and binary packages, + and how to build Ethereal from source, should you choose to do so. + + + The following are the general steps you would use: + + + + Download the relevant package for your needs, e.g. source or + binary distribution. + + + + + Build the source into a binary, if you have downloaded the + source. + + + This may involve building and/or installing other necessary packages. + + + + + Install the binaries into their final destinations. + + + + +
+ +
+ Obtaining the source and binary distributions + + You can obtain both source and binary distributions from the Wireshark + web site: &EtherealWebSite;. + 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. + + + Download all required files! + + 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. + + + + Once you have downloaded the relevant files, you can go on to the + next step. + + + Note! + + 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. + + + For this reason, you might want to pull down the source distribution + and build it, as the process is relatively simple. + + +
+ +
+ Before you build <application>Ethereal</application> under UNIX + + Before you build Ethereal from sources, or install a binary package, + you must ensure that you have the following other packages installed: + + + GTK+, The GIMP Tool Kit. + + You will also need Glib. Both can be obtained from + www.gtk.org + + + + + libpcap, the packet capture software that Ethereal uses. + + + You can obtain libpcap from + www.tcpdump.org + + + + 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. + + + If you have downloaded the source for GTK+, the instructions shown + in may provide some help in building it: + + Building GTK+ from source + +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> + + + + Note! + + You may need to change the version number of gtk+ in + 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, + tar xvf - will show you the name of the + directory you should change to. + + + + Note! + + If you use Linux, or have GNU tar installed, + you can use tar zxvf gtk+-1.2.10.tar.gz. It + is also possible to use gunzip -c or + gzcat rather than gzip -dc + on many UNIX systems. + + + + Note! + + If you downloaded gtk+ or any other tar file using Windows, + you may find your file called gtk+-1_2_8_tar.gz. + + + + + You should consult the GTK+ web site if any errors occur in carrying + out the instructions in . + + + If you have downloaded the source to libpcap, the general instructions + shown in will assist in building it. Also, + if your operating system does not support tcpdump, + you might also want to download it from the + tcpdump web site and + install it. + + Building and installing libpcap + +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> + + + + + Note! + + The directory you should change to will depend on the version of + libpcap you have downloaded. In all cases, + tar xvf - will show you the name of the + directory that has been unpacked. + + + + When installing the include files, you might get the error shown + in when you submit the command + make install-incl. + + Errors while installing the libpcap include files + +/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 + + + If you do, simply create the missing directory with the following + command: + +mkdir /usr/local/include/net + + and rerun the command make install-incl. + + + 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 + will install all the needed RPMs if they are not already installed. + + + Installing required RPMs under RedHat Linux 6.2 and beyond + + +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 + + + + + + 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. + + + + Under Debian you can install Ethereal using apt-get. apt-get will + handle any dependency issues for you. shows + how to do this. + + Installing debs under Debian + +apt-get install ethereal + + + +
+ +
+ Building Ethereal from source under UNIX + + Use the following general steps if you are building Ethereal from + source under a UNIX operating system: + + + + Unpack the source from its gzip'd + tar file. If you are using Linux, or your + version of UNIX uses GNU tar, you can use the + following command: + +tar zxvf ethereal-&EtherealCurrentVersion;-tar.gz + + + + For other versions of UNIX, You will want to use the following + commands: + +gzip -d ethereal-&EtherealCurrentVersion;-tar.gz +tar xvf ethereal-&EtherealCurrentVersion;-tar + + + Note! + + The pipeline + + gzip -dc ethereal-&EtherealCurrentVersion;-tar.gz | tar xvf - + will work here as well. + + + + Note! + + 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. + + + + + + + Change directory to the Wireshark source directory. + + + + + Configure your source so it will build correctly for your + version of UNIX. You can do this with the following command: + +./configure + + + + If this step fails, you will have to rectify the problems and + rerun configure. Troubleshooting hints are + provided in . + + + + + Build the sources into a binary, with the make + command. For example: + +make + + + + + + Install the software in its final destination, using the command: + +make install + + + + + + + Once you have installed Ethereal with make install + above, you should be able to run it by entering + ethereal. + +
+ +
+ Installing the binaries under UNIX + + 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 smit to + install the Wireshark binary package, while under Tru64 UNIX + (formerly Digital UNIX) you would use setld. + + +
+ Installing from rpm's under RedHat and alike + + Use the following command to install the Wireshark RPM that you have + downloaded from the Wireshark web site: + +rpm -ivh ethereal-0.10.5-0.2.2.i386.rpm + + If the above step fails because of missing dependencies, install the + dependencies first, and then retry the step above. See + for information on what RPMs you will need + to have installed. + +
+ +
+ Installing from deb's under Debian + + Use the following command to install Ethereal under Debian: + +apt-get install ethereal + + apt-get should take care of all of the dependency issues for you. + +
+
+ +
+ Troubleshooting during the install on Unix + + A number of errors can occur during the installation process. + Some hints on solving these are provided here. + + + If the configure stage fails, you will need to find + out why. You can check the file config.log in the + source directory to find out what failed. The last few lines of this + file should help in determining the problem. + + + 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 + configure will also fail if you do not have libpcap + (at least the required include files) on your system. + + + Another common problem is for the final compile and link stage to + terminate with a complaint of: Output too long. + This is likely to be caused by an antiquated sed + (such as the one shipped with Solaris). Since sed is + used by the libtool script to construct the final + link command, this leads to mysterious problems. This can be + resolved by downloading a recent version of sed from + . + + + If you cannot determine what the problems are, send mail to the + ethereal-dev mailing list explaining your problem, + and including the output from config.log and + anything else you think is relevant, like a trace of the + make stage. + +
+ +
+ Building from source under Windows + + It is recommended to use the binary installer for Windows, + until you want to start developing Ethereal on the Windows platform. + + + For further information how to build Ethereal for Windows from the + sources, have a look at the Development Wiki: + http://wiki.ethereal.com/Development + for the latest available development documentation. + +
+ +
+ Installing Ethereal under Windows + + In this section we explore installing Ethereal under Windows from the + binary packages. + +
+ Install Ethereal + + You may acquire a binary installer of Ethereal named something like: + ethereal-setup-x.y.z.exe. + + + Simply download the Wireshark installer from: + &EtherealBinariesPage; + and execute it. + + Note! + + 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 line options + + You can simply start the Wireshark installer without any command line + parameters, it will show you the usual interactive installer. + + + There are some command line parameters available: + + + + + /NCRC disables the CRC check + + + + + /S runs the installer or uninstaller silently with + default values. Please note: The silent installer won't install WinPCap! + + + + + /desktopicon installation of the desktop icon, + =yes - force installation, =no - + don't install, otherwise use defaults / user settings. + This option is available since 0.10.13 an can be useful for a silent + installer. + + + + + /quicklaunchicon installation of the quick launch icon, + =yes - force installation, =no - + don't install, otherwise use defaults / user settings. + This option is available since 0.10.13 an can be useful for a silent + installer. + + + + + /D 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. + + + + Example: + +ethereal-setup-0.10.13.exe /NCRC /S /desktopicon=yes /quicklaunchicon=no /D=C:\Program Files\Foo + + +
+
+ Components + + Beside the usual installer options like where to install the program, + there are several optional components. + + Tip! + + If you are unsure which settings to select, just keep the default settings. + + + + The Components + (both Ethereal GTK1 and 2 cannot be installed at the same time): + + + Etheral GTK1 - Wireshark is a GUI network protocol + analyzer. + + + Etheral GTK2 - Wireshark is a GUI network protocol + analyzer (using the modern GTK2 GUI toolkit, recommended). + + + GTK-Wimp - GTKWimp is the GTK2 windows impersonator + (native Win32 look and feel, recommended). + + + Tethereal - Tethereal is a command-line based network + protocol analyzer. + + + The dissection extensions for Wireshark and Tethereal: + + + Dissector Plugins - Plugins with some extended dissections. + + + Tree Statistics Plugins - Plugins with some extended statistics. + + + Mate - Meta Analysis and Tracing Engine - user + configurable extension(s) of the display filter engine, see + http://wiki.ethereal.com/Mate + for details. + + + SNMP MIBs - SNMP MIBs for a more detailed SNMP + dissection. + + + The Tools: + + + Editcap - Editcap is a program that reads a capture + file and writes some or all of the packets into another capture file. + + + Text2Pcap - Text2pcap is a program that reads in an + ASCII hex dump and writes the data into a libpcap-style capture file. + + + Mergecap - Mergecap is a program that combines multiple + saved capture files into a single output file. + + + Capinfos - Capinfos is a program that provides + information on capture files. + + + The Additional Tasks: + + + Start Menu Shortcuts - add some start menu shortcuts. + + + Desktop Icon - add an Ethereal icon to the desktop. + + + Quick Launch Icon - add an Ethereal icon to the + Explorer quick launch toolbar. + + + Associate file extensions to Ethereal - Associate + standard network trace files to Ethereal. + + + +
+
+
+ Install WinPcap + Note! + + 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! + + + + 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. + + + While running, the Wireshark installer detects which WinPcap version is + currently installed and will install WinPcap, if none or an older version is + detected. + + + More WinPcap info: + + + Ethereal related: + http://wiki.ethereal.com/WinPcap + + + General WinPcap info: + &WinPcapWebsite; + + + +
+ Manual WinPcap Installation + + 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. + + + Additional WinPcap versions (including newer alpha or beta releases) + can be downloaded from the following locations: + + + The main WinPcap site: + &WinPcapWebsite; + + + The ethereal.com mirror: + + http://winpcap.mirror.ethereal.com + + + The Wiretapped.net mirror: + + http://www.mirrors.wiretapped.net/security/packet-capture/winpcap + + + + + 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. + +
+
+ +
+ Update Ethereal + + 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 for details how to subscribe to this list. + + + 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. + +
+ +
+ Update WinPcap + + 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. + + Warning! + + 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. + + +
+ +
+ Uninstall Ethereal + + 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. + + + 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. + + + WinPcap won't be uninstalled by default, as other programs than Ethereal + may use it as well. + +
+ +
+ Uninstall WinPcap + + You can uninstall WinPcap independantly of Ethereal, using the "WinPcap" + entry in the "Add or Remove Programs" of the Control Panel. + + Note! + + After uninstallation of WinPcap you can't capture anything with Ethereal. + + + + It might be a good idea to reboot Windows afterwards. + +
+
+ + + 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 @@ + + + + + Capturing Live Network Data + +
+ Introduction + + Capturing live network data is one of the major features of Ethereal. + + + The Wireshark capture engine provides the following features: + + + + + Capture from different kinds of network hardware (Ethernet, Token Ring, + ATM, ...). + + + Stop the capture on different triggers like: amount of captured data, + captured time, captured number of packets. + + + Simultaneously show decoded packets while keep on capturing. + + + Filter packets, reducing the amount of data to be captured, see . + + + 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 . + + + The capture engine still lacks the following features: + + + Simultaneous capturing from multiple network interfaces (however, you + can start multiple instances of Ethereal and merge capture files later). + + + Stop capturing (or doing some other action), depending on the captured + data. + + + +
+ +
Prerequisites + + Setting up Ethereal to capture packets for the first time can be tricky. + + Tip! + A comprehensive guide "How To setup a Capture" is available at: + http://wiki.ethereal.com/CaptureSetup. + + + Here are some common pitfalls: + + + + You need to have root / Administrator privileges to start a live + capture. + + + + + You need to choose the right network interface to capture packet data + from. + + + + + You need to capture at the right place in the network to see the + traffic you want to see. + + + + + ... and a lot more!. + + + + + + If you have any problems setting up your capture environment, you should + have a look at the guide mentioned above. + +
+ +
Start Capturing + + One of the following methods can be used to start capturing packets with + Ethereal: + + + + You can get an overview of the available local interfaces using the + " + Capture Interfaces" dialog box, see + . You can start a + capture from this dialog box, using (one of) the "Capture" button(s). + + + + + You can start capturing using the + " + Capture Options" dialog box, see + . + + + + + If you have selected the right capture options before, you can + immediately start a capture using the + " + Capture Start" menu / toolbar item. The capture + process will start immediately. + + + + + If you already know the name of the capture interface, you can start + Ethereal from the command line and use the following: + +ethereal -i eth0 -k + + This will start Ethereal capturing on interface eth0, more details + can be found at: . + + + + +
+ +
+ The "Capture Interfaces" dialog box + + When you select "Interfaces..." from the Capture menu, Ethereal pops + up the "Capture Interfaces" dialog box as shown in + . + Warning! + + 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. + + + Note! + + 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. + + +
+ The "Capture Interfaces" dialog box + +
+ + Description + + + The interface description provided by the operating system. + + + + IP + + + 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). + + + + Packets + + + 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. + + + + Packets/s + + + Number of packets captured in the last second. Will be greyed out, + if no packet was captured in the last second. + + + + Stop + + + Stop a currently running capture. + + + + Capture + + + Start a capture on this interface immediately, using the settings + from the last capture. + + + + Prepare + + + Open the Capture Options dialog with this interface selected, see + . + + + + Close + + + Close this dialog box. + + + + + +
+ +
+ The "Capture Options" dialog box + + 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 + . + +
+ The "Capture Options" dialog box + +
+ Tip! + + 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. + + + + You can set the following fields in this dialog box: + +
Capture frame + + Interface + + + 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). + + + This field performs the same function as the + -i <interface> command line option. + + + + IP address + + + The IP address(es) of the selected interface. If no address could + be resolved from the system, "unknown" will be shown. + + + + Link-layer header type + + + Unless you are in the rare situation that you need this, just keep + the default. For a detailed description, see + + + + + Buffer size: n megabyte(s) + + + 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. + + + Note + This option is only available on Windows platforms. + + + + + + Capture packets in promiscuous mode + + + + 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). + + + Note + + 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 + + + + Note + + Even in promiscuous mode you still won't necessarily see all packets + on your LAN segment, see for + some more explanations. + + + + + Limit each packet to n bytes + + + 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 snaplen. If disabled, + the default is 65535, which will be sufficient for most + protocols. Some rules of thumb: + + + + + If you are unsure, just keep the default value. + + + + + 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. + + + + + 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. + + + + + + Capture Filter + + + This field allows you to specify a capture filter. + Capture filters are discussed in more details in + . It defaults to empty, or + no filter. + + + 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 + + + + + +
+
Capture File(s) frame + + An explanation about capture file usage can be found in . + + + File + + + 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 for + details. + + + You can also click on the button to the right of this field to + browse through the filesystem. + + + + Use multiple files + + + Instead of using a single file, Ethereal will automatically switch + to a new one, if a specific trigger condition is reached. + + + + Next file every n megabyte(s) + + + Multiple files only: Switch to the next file after the given + number of byte(s)/kilobyte(s)/megabyte(s)/gigabyte(s) have been + captured. + + + + Next file every n minute(s) + + + Multiple files only: Switch to the next file after the given + number of second(s)/minutes(s)/hours(s)/days(s) have elapsed. + + + + Ring buffer with n files + + + Multiple files only: Form a ring buffer of the capture files, with + the given number of files. + + + + Stop capture after n file(s) + + + Multiple files only: Stop capturing after switching to the next + file the given number of times. + + + + +
+
Stop Capture... frame + + ... after n packet(s) + + + Stop capturing after the given number of packets have been + captured. + + + + ... after n megabytes(s) + + + 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. + + + + ... after n minute(s) + + + Stop capturing after the given number of + second(s)/minutes(s)/hours(s)/days(s) have elapsed. + + + + +
+
Display Options frame + + + + Update list of packets in real time + + + + 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. + + + + + + Automatic scrolling in live capture + + + + 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. + + + + + + Hide capture info dialog + + + + If this option is checked, the following capture info dialog will be + hidden. + + + + +
+
Name Resolution frame + + + Enable MAC name resolution + + + This option allows you to control whether or not + Ethereal translates MAC addresses into names, see + . + + + + + Enable network name resolution + + + This option allows you to control whether or not + Ethereal translates network addresses into names, see + . + + + + + Enable transport name resolution + + + This option allows you to control whether or not + Ethereal translates transport addresses into protocols, see + . + + + + +
+
Buttons + + Once you have set the values you desire and have selected the + options you need, simply click on OK to commence the + capture, or Cancel to cancel the capture. + + + If you start a capture, Ethereal allows you to stop capturing when + you have enough packets captured, for details see + . + +
+
+ +
Capture files and file modes + + 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. + + + + Different modes of operation are available when saving this packet data to + the capture file(s). + + + Tip! + + 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. + + + Note! + + 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. + + + Tip! + + Information about the folders used for the capture file(s), can be found + in . + + + + Capture file mode selected by capture options + + + + + + + + "File" option + "Use multiple files" option + "Ring buffer with n files" option + Mode + Resulting filename(s) used + + + + + - + - + - + Single temporary file + etherXXXXXX (where XXXXXX is a unique number) + + + foo.cap + - + - + Single named file + foo.cap + + + foo.cap + x + - + Multiple files, continuous + foo_00001_20040205110102.cap, foo_00002_20040205110102.cap, ... + + + foo.cap + x + x + Multiple files, ring buffer + foo_00001_20040205110102.cap, foo_00002_20040205110102.cap, ... + + + +
+ + + Single temporary file + + + 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. + + + + + Single named file + + + A single capture file will be used. If you want to place the new capture + file to a specific folder, choose this mode. + + + + + Multiple files, continuous + + + 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). + + + + + Multiple files, ring buffer + + + 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"). + + + This mode will limit the maximum disk usage, even for an unlimited amount of + capture input data, keeping the latest captured data. + + + + +
+ +
Link-layer header type + + 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: + + + 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". + + + 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". + + + 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". + + + 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". + +
+ +
Filtering while capturing + + 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. + + + Tip! + + You will find a lot of Capture Filter examples at &EtherealWikiCaptureFiltersPage;. + + + + You enter the capture filter into the Filter field of the Wireshark + Capture Options dialog box, as shown in + . The following is an outline + of the syntax of the tcpdump capture filter language. + See the expression option at the tcpdump manual page for details: + . + + + A capture filter takes the form of a series of primitive expressions + connected by conjunctions (and/or) and optionally + preceded by not: + +[not] primitive [and|or [not] primitive ...] + + An example is shown in . + + + + A capture filter for telnet than captures traffic to and from a + particular host + + +tcp port 23 and host 10.0.0.5 + + + This example captures telnet traffic to and from the host + 10.0.0.5, and shows how to use two primitives and the + and conjunction. Another example is shown in + , and shows how to capture all + telnet traffic except that from 10.0.0.5. + + + Capturing all telnet traffic not from 10.0.0.5 + +tcp port 23 and not host 10.0.0.5 + + + + + + XXX - add examples to the following list. + + + A primitive is simply one of the following: + + + [src|dst] host <host> + + + This primitive allows you to filter on a host IP + address or name. You can optionally precede the + primitive with the keyword src|dst + 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. + + + + + + ether [src|dst] host <ehost> + + + + This primitive allows you to filter on Ethernet host + addresses. You can optionally include the keyword + src|dst between the keywords + ether and host + 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. + + + + + gateway host <host> + + + This primitive allows you to filter on packets that + used host as a gateway. That is, where + the Ethernet source or destination was + host but neither the source nor + destination IP address was host. + + + + + + + [src|dst] net <net> [{mask <mask>}|{len <len>}] + + + + + This primitive allows you to filter on network numbers. + You can optionally precede this primitive with the + keyword src|dst 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. + + + + + + [tcp|udp] [src|dst] port <port> + + + + This primitive allows you to filter on TCP and UDP port + numbers. You can optionally precede this primitive with + the keywords src|dst and + tcp|udp which allow you to specify + that you are only interested in source or destination + ports and TCP or UDP packets respectively. The + keywords tcp|udp must appear before + src|dst. + + + 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. + + + + + less|greater <length> + + + 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. + + + + + ip|ether proto <protocol> + + + This primitive allows you to filter on the specified + protocol at either the Ethernet layer or the IP layer. + + + + + ether|ip broadcast|multicast + + + This primitive allows you to filter on either + Ethernet or IP broadcasts or multicasts. + + + + + <expr> relop <expr> + + + 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 + for more details. + + + + + +
+ +
While a Capture is running ... + + While a capture is running, the following dialog box is shown: +
+ The "Capture Info" dialog box + +
+ 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. + + Tip! + + This Capture Info dialog box can be hidden, using the "Hide capture info + dialog" option in the Capture Options dialog box. + + +
Stop the running capture + + A running capture session will be stopped in one of the following ways: + + + Using the + " + Stop" button from the Capture Info dialog box + . + + Note! + + The Capture Info dialog box might be hidden, if the option "Hide capture + info dialog" is used. + + + + + Using the menu item + "Capture/ + Stop". + + + + Using the toolbar item + " + Stop". + + + + Pressing the accelerator keys: Ctrl+E. + + + + The capture will be automatically stopped, if one of the + Stop Conditions is exceeded, e.g. the maximum amount + of data was captured. + + + + +
+
Restart a running capture + + 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. + + + 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: + + + Using the menu item + "Capture/ + Restart". + + + + Using the toolbar item + " + Restart". + + + + +
+
+ + + + 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 @@ + + + + + Customizing Ethereal + +
Introduction + + 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: + + + + How to start Ethereal with command line parameters + + + + + How to colorize the packet list + + + + + How to control protocol dissection + + + + + How to use the various preference settings + + + + +
+ +
Start Ethereal from the command line + + You can start Ethereal 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. + + + Ethereal supports a large number of + command line parameters. To see what they are, simply enter the + command ethereal -h and the help information + shown in (or something similar) should be + printed. + + Help information available from Ethereal + +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> ] + + + We will examine each of the command line options in turn. + + + The first thing to notice is that issuing the command + ethereal by itself will bring up + Ethereal. + 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? + + -a <capture autostop condition> + + + 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: + + duration:value + + Stop writing to a capture file after value of seconds have elapsed. + + + filesize:value + + 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. + + + files:value + + Stop writing to capture files after value number of files were + written. + + + + + + + -b <capture ring buffer option> + + + 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. + + + 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. + + + 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. + + + + duration:value + + Switch to the next file after value seconds have elapsed, even + if the current file is not completely filled up. + + + filesize:value + + Switch to the next file after it reaches a size of value kilobytes + (where a kilobyte is 1000 bytes, not 1024 bytes). + + + files:value + + Begin again with the first file after value number of files were + written (form a ring buffer). + + + + + + + -B <capture buffer size (Win32 only)> + + + 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. + + + + -c <capture packet count> + + + This option specifies the maximum number of packets to capture + when capturing live data. It would be used in conjunction + with the -k option. + + + + -D + + +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 -i flag to specify an interface on which to capture. + + +This can be useful on systems that don't have a command to list them +(e.g., Windows systems, or UNIX systems lacking ifconfig -a); +the number can be useful on Windows 2000 and later systems, where the +interface name is a somewhat complex string. + + +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 -D flag and +is not run from such an account, it will not list any interfaces. + + + + -f <capture filter> + + + This option sets the initial capture filter expression to + be used when capturing packets. + + + + -g <packet number> + + + After reading in a capture file using the -r flag, go to the given + packet number. + + + + -h + + + The -h option requests Ethereal to print + its version and usage instructions (as shown above) and exit. + + + + -i <capture interface> + + +Set the name of the network interface or pipe to use for live packet +capture. + + +Network interface names should match one of the names listed in +ethereal -D (described above); a number, as reported by +ethereal -D, can also be used. If you're using UNIX, netstat +-i or ifconfig -a might also work to list interface names, +although not all versions of UNIX support the -a flag to ifconfig. + + +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. + + +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. + + + + -k + + + The -k option specifies that Ethereal + should start capturing packets immediately. This option + requires the use of the -i parameter to + specify the interface that packet capture will occur from. + + + + -l + + + 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 -S + flag). + + + + -L + + + List the data link types supported by the interface and exit. + + + + -m <font> + + + This option sets the name of the font used for most text + displayed by Wireshark. XXX - add an example! + + + + -n + + + Disable network object name resolution (such as hostname, TCP and UDP + port names). + + + + -N <name resolving flags> + + + Turns on name resolving for particular types of addresses + and port numbers; the argument is a string that may contain + the letters m to enable MAC address + resolution, n to enable network address + resolution, and t to enable transport-layer + port number resolution. This overrides -n + if both -N and -n are + present. The letter C enables concurrent (asynchronous) DNS lookups. + + + + + -o <preference/recent settings> + + + 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 + -o <preference settings> can be + given on a single command line. + + An example of setting a single preference would be: + + + ethereal -o mgcp.display_dissect_tree:TRUE + + + + An example of setting multiple preferences would be: + + + + ethereal -o mgcp.display_dissect_tree:TRUE -o mgcp.udp.callagent_port:2627 + + + Tip! + + You can get a list of all available preference strings from the + preferences file, see . + + + + + -p + + + 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. + + + + -Q + + + This option forces Ethereal to exit when capturing is + complete. It can be used with the -c option. + It must be used in conjunction with the + -i and -w options. + + + + -r <infile> + + + 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. + + + + -R <read (display) filter> + + + 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 + . Packets not + matching the filter are discarded. + + + + -s <capture snaplen> + + + This option specifies the snapshot length to use when + capturing packets. Ethereal will only capture + <snaplen> bytes of data for each packet. + + + + -S + + + 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. + + + + + -t <time stamp format> + + + This option sets the format of packet timestamps that are + displayed in the packet list window. The format can be one of: + + + + r relative, which specifies timestamps are + displayed relative to the first packet captured. + + + + + a absolute, which specifies that actual times + be displayed for all packets. + + + + + ad absolute with date, which specifies that + actual dates and times be displayed for all packets. + + + + + d delta, which specifies that timestamps + are relative to the previous packet. + + + + + + + -v + + + The -v option requests + Ethereal to print out its version information and exit. + + + + -w <savefile> + + + This option sets the name of the savefile + to be used when saving a capture file. + + + + -y <capture link type> + + + 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. + + + + -X <eXtension option> + + + 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: + + + lua_script:lua_script_filename Tell Ethereal to load the given script in addition to the default Lua scripts. + + + + -z <statistics-string> + + + 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! + + + + + +
+ +
Packet colorization + + 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. + + + Tip! + + You will find a lot of Coloring Rule examples at the Ethereal + Wiki Coloring Rules page at &EtherealWikiColoringRulesPage;. + + + + 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 . + +
+ The "Coloring Rules" dialog box + +
+ + 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. + + Note! + + 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). + + + + 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 + . + +
+ The "Edit Color Filter" dialog box + +
+ + In the Edit Color dialog box, simply enter a name for the color filter, + and enter a filter string in the Filter text field. + shows the values + arp and arp which means that + the name of the color filter is arp and the filter + will select protocols of type arp. Once you have + entered these values, you can choose a foreground and background + color for packets that match the filter expression. Click on + Foreground color... or + Background color... to achieve this and + Ethereal will pop up the Choose foreground/background color for + protocol dialog box as shown in + . + +
+ The "Choose color" dialog box + +
+ + Select the color you desire for the selected packets and click on OK. + + + Note! + + 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. + + + + 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. + +
+ Using color filters with Ethereal + +
+
+ +
+ Control Protocol dissection + + The user can control how protocols are dissected. + + + 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. + + + 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. + +
The "Enabled Protocols" dialog + box + + 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. + + Note! + + 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. + + +
+ The "Enabled Protocols" dialog box + +
+ + To disable or enable a protocol, simply click on it using the + mouse or press the space bar when the protocol is highlighted. + + Warning! + + 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. + + + + You can choose from the following actions: + + + + Enable All Enable all protocols in the list. + + + + + Disable All Disable all protocols in the list. + + + + + Invert Toggle the state of all protocols in the + list. + + + + + OK Apply the changes and close the dialog box. + + + + + Apply Apply the changes and keep the dialog box + open. + + + + + Save Save the settings to the disabled_protos, see + for details. + + + + + Cancel Cancel the changes and close the dialog box. + + + + +
+ +
User Specified Decodes + + 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. + + +
+ The "Decode As" dialog box + +
+ The content of this dialog box depends on the selected packet when it + was opened. + Warning! + + The user specified decodes can not be saved. If you quit Ethereal, + these settings will be lost. + + + + + + Decode Decode packets the selected way. + + + + + Do not decode Do not decode packets the selected + way. + + + + + Link/Network/Transport 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. + + + + + Show Current Open a dialog box showing the + current list of user specified decodes. + + + + + OK Apply the currently selected decode and close + the dialog box. + + + + + Apply Apply the currently selected decode and keep + the dialog box open. + + + + + Cancel Cancel the changes and close the dialog box. + + + + +
+ +
Show User Specified Decodes + + This dialog box shows the currently active user specified decodes. +
+ The "Decode As: Show" dialog box + +
+ + + + OK Close this dialog box. + + + + + Clear Removes all user specified decodes. + + + + +
+
+ +
Preferences + + 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 + , with the "User Interface" page as + default. On the left side is a tree where you can select the page to be + shown. + Note! + + Preference settings are added frequently. For a recent explanation of + the preference pages and their settings have a look at the + Ethereal Wiki Preferences page at &EtherealWikiPreferencesPage;. + + + + Warning! + + The OK or Apply button will not save the preference settings, + you'll have to save the settings by clicking the Save button. + + + + + + The OK button will apply the preferences + settings and close the dialog. + + + + + The Apply button will apply the preferences + settings and keep the dialog open. + + + + + The Save button will apply the preferences + settings, save the settings on the harddisk and keep the dialog open. + + + + + The Cancel button will restore all preferences + settings to the last saved state. + + + + +
+ The preferences dialog box + +
+
+ + + + 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 @@ + + + + + Introduction + +
+ What is <application>Ethereal?</application> + + 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. + + + 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). + + + In the past, such tools were either very expensive, proprietary, or both. + However, with the advent of Ethereal, all that has changed. + + + Ethereal is perhaps one of the best open + source packet analyzers available today. + + +
Some intended purposes + + Here are some examples people use Ethereal for: + + + network administrators use it to troubleshoot network + problems + + + network security engineers use it to examine security + problems + + + developers use it to debug protocol implementations + + + people use it to learn network protocol + internals + + + Beside these examples, Ethereal can be helpful in many other situations + too. + +
+ +
Features + + The following are some of the many features Ethereal provides: + + + Available for UNIX and Windows. + + + + Capture live packet data from a network interface. + + + + + Display packets with very detailed protocol information. + + + + + Open and Save packet data captured. + + + + + Import and Export packet data from and to a lot of + other capture programs. + + + + Filter packets on many criteria. + + + Search for packets on many criteria. + + + Colorize packet display based on filters. + + + Create various statistics. + + + ... and a lot more! + + + However, to really appreciate its power, you have to start using it. + + + shows Ethereal + having captured some packets and waiting for you to examine + them. +
+ + <application>Ethereal</application> captures packets and allows + you to examine their content. + + +
+ +
+ +
+ Live capture from many different network media + + 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: + . + +
+ +
Import files from many other capture programs + + Ethereal can open packets captured from a large number of + other capture programs. For a list of input formats see + . + +
+
Export files for many other capture programs + + Ethereal can save packets captured in a large number of formats of + other capture programs. For a list of output formats see + . + +
+ +
+ Many protocol decoders + + There are protocol decoders (or dissectors, as they are + known in Wireshark) for a great many protocols: + see . + +
+ +
Open Source Software + + Wireshark is an open source software project, and is released under + the GNU General Public Licence (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! + +
+ +
What Wireshark is not + + Here are some things Ethereal does not provide: + + + 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. + + + 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). + + + +
+
+ +
+ Platforms Ethereal runs on + + Ethereal currently runs on most UNIX platforms and various Windows + platforms. It requires GTK+, GLib, libpcap and some other libraries in + order to run. + + + 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 &EtherealDevMailList;. + + + Binary packages are available for at least the following platforms: + + +
Unix + + + Apple Mac OS X + BeOS + FreeBSD + HP-UX + IBM AIX + NetBSD + OpenBSD + SCO UnixWare/OpenUnix + SGI Irix + Sun Solaris/Intel + Sun Solaris/Sparc + Tru64 UNIX (formerly Digital UNIX) + + +
+ +
Linux + + + Debian GNU/Linux + Gentoo Linux + IBM S/390 Linux (Red Hat) + Mandrake Linux + PLD Linux + Red Hat Linux + Rock Linux + Slackware Linux + Suse Linux + + +
+ +
Microsoft Windows + + Maintained: + + Windows Server 2003 / XP / 2000 / NT 4.0 + Windows Me / 98 + + + + Unsupported/Unmaintained (because lack of required libraries): + + Windows CE + Windows NT / XP Embedded + Windows 95 is no longer actively maintained by WinPcap, + but still may work perfectly + + + + No experiences (fresh versions): + + Windows XP 64-bit Edition + Windows Vista (aka Longhorn) + + Please provide your experiences about these fresh versions to: + &EtherealDevMailList;. + +
+ +
+ +
+ Where to get Ethereal? + + You can get the latest copy of the program from the Wireshark website: + &EtherealDownloadPage;. The + website allows you to choose from among several mirrors for + downloading. + + + A new Ethereal version will typically become available every 4-8 weeks. + + + 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 . + +
+ +
+ A rose by any other name + + William Shakespeare wrote: + + "A rose by any other name would smell as sweet." + + And so it is with Ethereal, as there appears to be two different + ways that people pronounce the name. + + + Some people pronounce it ether-real, while others pronounce it + e-the-real, as in ghostly, insubstantial, etc. + + + 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". + +
+ +
+ A brief history of Ethereal + + 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. + + + 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. + + + Not long after that Gilbert Ramirez saw its potential and contributed + a low-level dissector to it. + + + 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. + + + 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. + + + 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. + +
+ +
+ + Development and maintenance of <application>Ethereal</application> + + + 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. + + + 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 authors page on the + Ethereal web site. + + + Wireshark is an open source software project, and is released under + the GNU General Public Licence (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. + + + You gain three benefits by contributing your improvements back to the + community: + + + + 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. + + + + + 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. + + + + + 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. + + + + + + The Wireshark source code and binary kits for some platforms are all + available on the download page of the Wireshark website: + &EtherealDownloadPage;. + +
+ +
+ Reporting problems and getting help + + 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). + + +
Website + + You will find lot's of useful information on the Wireshark homepage at + &EtherealWebSite;. + +
+ +
Wiki + + The Wireshark Wiki at &EtherealWikiPage; 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. + + + 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. + +
+ +
FAQ + + The "Frequently Asked Questions" will list often asked questions and + the corresponding answers. + Read the FAQ! + + 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). + + + You will find the FAQ inside Ethereal by clicking the menu item + Help/Contents and selecting the FAQ page in the upcoming dialog. + + + An online version is available at the ethereal website: + &EtherealFAQPage;. You might + prefer this online version, as it's typically more up to date and the HTML + format is easier to use. + +
+ +
Mailing Lists + + There are several mailing lists of specific Ethereal topics available: + + ethereal-announce + + + This mailing list will inform you about new program + releases, which usually appear about every 4-8 weeks. + + + + ethereal-users + + + This list is for users of Ethereal. People post + questions about building and using Ethereal, others (hopefully) + provide answers. + + + + ethereal-dev + + + This list is for Wireshark developers. If you want to start + developing a protocol dissector, join this list. + + + + + You can subscribe to each of these lists from the Wireshark web site: + &EtherealWebSite;. Simply + select the mailing lists link on the left hand + side of the site. The lists are archived at the Wireshark web site + as well. + Tip! + + 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. + + + +
+ +
Reporting Problems + Note! + + Before reporting any problems, please make sure you have installed the + latest version of Ethereal. + + + + When reporting problems with Ethereal, it is helpful if you supply the + following information: + + + + The version number of Ethereal and the dependent libraries linked with + it, eg GTK+, etc. You can obtain this with the command + ethereal -v. + + + + + Information about the platform you run Ethereal on. + + + + + A detailed description of your problem. + + + + + 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. + + + + + Don't send large files! + + 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. + + + Don't send confidential information! + + If you send captured data to the mailing lists, be sure they don't contain + any sensitive or confidential information like passwords or such. + + +
+ +
Reporting Crashes on UNIX/Linux platforms + + When reporting crashes with Ethereal, it is helpful if you supply the + traceback information (besides the information mentioned in "Reporting + Problems"). + + + You can obtain this traceback information with the following commands: + +& bt.txt +backtrace +^D +$ +]]> + + + + Type the characters in the first line verbatim! Those are + back-tics there! + + + + + backtrace is a gdb 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 gdb to exit. This will + leave you with a file called + bt.txt in the current directory. + Include the file with your bug report. + + + + + If you do not have gdb available, you + will have to check out your operating system's debugger. + + + + + You should mail the traceback to the + &EtherealDevMailList; + mailing list. + +
+ +
Reporting Crashes on Windows platforms + + 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. + +
+
+ + + 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 @@ + + + + + File Input / Output and Printing + +
Introduction + + This chapter will describe input and output of capture data. + + + + Open/Import capture files in various capture file formats + + + + + Save/Export capture files in various capture file formats + + + + + Merge capture files together + + + + + Print packets + + + + +
+ +
Open capture files + + Ethereal can read in previously saved capture files. + To read them, simply select the menu or toolbar item: "File/ + + Open". + Ethereal will then pop up the File + Open dialog box, which is discussed in more detail in + . + + Note! + + You can also use drag-and-drop 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. + + + + 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). + + + 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 for the list of + capture formats Ethereal understands. + + +
The "Open Capture File" dialog box + + The "Open Capture File" dialog box allows you to search for a + capture file containing previously captured packets for display in + Ethereal. shows an example + of the Wireshark Open File Dialog box. + + + Note + + 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. + + +
+ The "Open Capture File" Dialog box + +
+ + With this dialog box, you can perform the following actions: + + + + The "+ Add" button allows you to add a directory, selected in the + right-hand pane, to the favorites (bookmarks?) list. Those changes + are persistent. + + + + + The "- Remove" button allows you to remove a selected directory from + that list again (the items like: "Home", "Desktop", and "Filesystem" + cannot be removed). + + + + + Select files and directories with the list boxes. + + + + + View file preview information (like the filesize, the number of + packets, ...), while browsing the filesystem. + + + + + 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 + ). + + + + + 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 + . + + + + + 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. + + + + + Click the Cancel button to go back to Ethereal and not load a capture + file. + + + + 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. + +
+ +
+ Input File Formats + + The following file formats from other capture tools can be opened by + Ethereal: + + libpcap, tcpdump and various other tools using tcpdump's capture format + Sun snoop and atmsnoop + Shomiti/Finisar Surveyor captures + Novell LANalyzer captures + Microsoft Network Monitor captures + AIX's iptrace captures + Cinco Networks NetXray captures + Network Associates Windows-based Sniffer and Sniffer Pro captures + Network General/Network Associates DOS-based Sniffer (compressed or uncompressed) captures + AG Group/WildPackets EtherPeek/TokenPeek/AiroPeek/EtherHelp/PacketGrabber captures + RADCOM's WAN/LAN Analyzer captures + Network Instruments Observer version 9 captures + Lucent/Ascend router debug output + HP-UX's nettl + Toshiba's ISDN routers dump output + ISDN4BSD i4btrace utility + traces from the EyeSDN USB S0 + IPLog format from the Cisco Secure Intrusion Detection System + pppd logs (pppdump format) + the output from VMS's TCPIPtrace/TCPtrace/UCX$TRACE utilities + the text output from the DBS Etherwatch VMS utility + Visual Networks' Visual UpTime traffic capture + the output from CoSine L2 debug + the output from Accellent's 5Views LAN agents + Endace Measurement Systems' ERF format captures + Linux Bluez Bluetooth stack hcidump -w traces + Catapult DCT2000 .out files + + + Note! + + 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. + + + +
+ +
+ +
Saving captured packets + + 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. + +
+ The "Save Capture File As" dialog box + + The "Save Capture File As" dialog box allows you to save + the current capture to a file. + shows an example of this + dialog box. + + + Note + + 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. + + +
+ The "Save Capture File As" dialog box + +
+ + With this dialog box, you can perform the following actions: + + + + Type in the name of the file you wish to save the captured + packets in, as a standard file name in your file system. + + + + + Select the directory to save the file into. + + + + + Select the range of the packets to be saved, see + + + + + + 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 . + + + Note! + + Some capture formats may not be available, depending on the + packet types captured. + + + + Tip! + + You can convert capture files from one format to another + by reading in a capture file and writing it out using a + different format. + + + + + + Use "Browse for other folders" to browse files and folders in your + file system. + + + + + 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. + + + + + Click on the Cancel button to go back to Ethereal and not save the + captured packets. + + + + +
+
+ Output File Formats + + The following file formats can be saved by Ethereal, + so other capture tools can read the capture data from: + + libpcap (tcpdump) + Novell LANalyzer + Network Associates Sniffer + Sun snoop + Microsoft Network Monitor + Visual Networks Visual UpTime traffic + Accellent 5Views + Networks Instruments Observer version 9 + HP-UX's nettl + + + + + Other protocol analyzers may require that the file has a certain suffix + in order to read the files you generate with Ethereal, e.g.: + + + ".DMP" for Tcpdump/libpcap + + + ".CAP" for Network Associates Sniffer Windows + + +
+
+ +
Merging capture files + + Sometimes you need to merge several capture files into one. For example + this can be useful, if you have captured simultaneously from multiple + interfaces at once (e.g. using multiple instances of Ethereal). + + + Merging capture files can be done in three ways: + + + Use the menu item "Merge" from the "File" menu, + to open the merge dialog, see . + This menu item will be disabled, until you have loaded a capture file. + + + Use drag-and-drop 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. + + + Use the mergecap tool, which is a command + line tool to merge capture files. This tool provides the most options + to merge capture files, see . + + + +
The "Merge with Capture File" dialog box + + This dialog box let you select a file to be merged into the currently + loaded file. + + Note! + If your current data wasn't saved before, you will be asked to save + it first, before this dialog box is shown. + +
+ The "Merge with Capture File" dialog box + +
+ + + Prepend packets to existing file + + + Prepend the packets from the selected file before the currently loaded + packets. + + + + + Merge packets chronologically + + + Merge both the packets from the selected and currently loaded file in + chronological order. + + + + + Append packets to existing file + + + Append the packets from the selected file after the currently loaded + packets. + + + + + + All other controls will work the same way as in the "Open Capture File" + dialog box, see . + +
+
+ +
File Sets + + When using the "Multiple Files" option while doing a capture + (see: ), + the capture data is spreaded over several capture files, called a file + set. + + + 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. + + How does Ethereal detect the files of a file set? + + 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. + + + 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. + + + 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. + + + + The following features in the "File Set" submenu of the "File" menu are + available to work with file sets in a convenient way: + + + + The List Files dialog box will list the files + Ethereal has recognized as being part of the current file set. + + + Next File closes the current and opens the next + file in the file set. + + + Previous File closes the current and opens the + previous file in the file set. + + +
+ The "List Files" dialog box +
+ The "List Files" dialog box + +
+ + Each line contains information about a file of the file set: + + + Filename the name of the file. If you click on + the filename (or the radio button left to it), the current file will + be closed and the corresponding capture file will be opened. + + + Created the creation time of the file + + + Last Modified the last time the file was modified + + + Size the size of the file + + + The last line will contain info about the currently used directory where + all of the files in the file set can be found. + + + The content of this dialog box is updated each time a capture file is + opened/closed. + + + The Close button will, well, close the dialog box. + +
+
+
Exporting data + + Ethereal provides several ways and formats to export packet data. This + section describes general ways to export data from Ethereal. + + Note! + + There are more specialized functions to export specific data, + which will be described at the appropriate places. + + + + XXX - add detailed descriptions of the output formats and some sample + output, too. + +
+ The "Export as Plain Text File" dialog box + + Export packet data into a plain ASCII text file, much like the format + used to print packets. +
+ The "Export as Plain Text File" dialog box + +
+ + + Export to file: frame chooses the file to export + the packet data to. + + + The Packet Range frame is described in . + + + The Packet Details frame is described in . + + + +
+
+ The "Export as PostScript File" dialog box + + Export packet data into PostScript, much like the format used + to print packets. + Tip! + + You can easily convert PostScript files to PDF files using ghostscript. + For example: export to a file named foo.ps and then call: + ps2pdf foo.ps + + +
+ The "Export as PostScript File" dialog box + +
+ + + Export to file: frame chooses the file to export + the packet data to. + + + The Packet Range frame is described in . + + + The Packet Details frame is described in . + + + +
+
+ The "Export as CSV (Comma Seperated Values) File" dialog box + XXX - add screenshot + + Export packet summary into CSV, used e.g. by spreadsheet programs to + im-/export data. + + + + Export to file: frame chooses the file to export + the packet data to. + + + The Packet Range frame is described in . + + + +
+
+ The "Export as PSML File" dialog box + + Export packet data into PSML. This is an XML based format including + only the packet summary. +
+ The "Export as PSML File" dialog box + +
+ + + Export to file: frame chooses the file to export + the packet data to. + + + The Packet Range frame is described in . + + + There's no such thing as a packet details frame for PSML export, as the + packet format is defined by the PSML specification. + +
+
+ The "Export as PDML File" dialog box + + Export packet data into PDML. This is an XML based format including + the packet details. The PDML file specification is available at: + + PDML specification. + + + 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. + + +
+ The "Export as PDML File" dialog box + +
+ + + Export to file: frame chooses the file to export + the packet data to. + + + The Packet Range frame is described in . + + + There's no such thing as a packet details frame for PDML export, as the + packet format is defined by the PDML specification. + +
+
+ The "Export selected packet bytes" dialog box + + Export the bytes selected in the "Packet Bytes" pane into a raw + binary file. +
+ The "Export Selected Packet Bytes" dialog box + +
+ + + Name: the filename to export the packet data to. + + + The Save in folder: field lets you select the + folder to save to (from some predefined folders). + + + Browse for other folders provides a flexible + way to choose a folder. + + + +
+
+ +
Printing packets + + 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 + . + +
The "Print" dialog box +
+ The "Print" dialog box + +
+ + The following fields are available in the Print dialog box: + + Printer + + + This field contains a pair of mutually exclusive radio buttons: + + + + Plain Text specifies that + the packet print should be in plain text. + + + + + PostScript specifies that + the packet print process should use PostScript to + generate a better print output on PostScript aware printers. + + + + + Output to file: specifies that printing + be done to a file, which name is entered in the field or selected + using the browse button. + + + This field is where you enter the file to + print to if you have selected Print to a file, or you can click the + button to browse the filesystem. It is greyed out if Print to a file + is not selected. + + + + + Print command specifies that a + command be used for printing. + + Note! + + These Print command fields are not available on + windows platforms. + + + + This field specifies the command to use for printing. It + is typically lpr. You would change it + to specify a particular queue if you need to print to a + queue other than the default. An example might be: + +lpr -Pmypostscript + + This field is greyed out if Output to file: is + checked above. + + + + + + + + Packet Range + + + Select the packets to be printed, see + + + + + Packet Format + + + Select the output format of the packets to be printed. You can + choose, how each packet is printed, see + + + + + + +
+
+ +
The Packet Range frame + + The packet range frame is a part of various output related dialog boxes. + It provides options to select which packets should be processed by the + output function. +
+ The "Packet Range" frame + +
+ + + If the Captured button is set (default), all packets + from the selected rule will be processed. If the Displayed + button is set, only the currently displayed packets are taken + into account to the selected rule. + + + + + + All packets will process all packets. + + + + + Selected packet only process only the selected + packet. + + + + + Marked packets only process only the marked + packets. + + + + + From first to last marked packet process the + packets from the first to the last marked one. + + + + + Specify a packet range process a user specified + range of packets, e.g. specifying 5,10-15,20- will + process the packet number five, the packets from packet number ten + to fifteen (inclusive) and every packet from number twenty to the + end of the capture. + + + + +
+ +
The Packet Format frame + + The packet format frame is a part of various output related dialog boxes. + It provides options to select which parts of a packet should be used for + the output function. +
+ The "Packet Format" frame + +
+ + + + Packet summary line enable the output of the + summary line, just as in the "Packet List" pane. + + + + + Packet details enable the output of the packet + details tree. + + + + + All collapsed the info from the "Packet Details" + pane in "all collapsed" state. + + + + + As displayed the info from the "Packet Details" + pane in the current state. + + + + + All expanded the info from the "Packet Details" + pane in "all expanded" state. + + + + + + + Packet bytes enable the output of the packet + bytes, just as in the "Packet Bytes" pane. + + + + + Each packet on a new page put each packet on a + separate page (e.g. when saving/printing to a text file, this will + put a form feed character between the packets). + + + + +
+ + + + 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 @@ + + + + + Statistics +
+ Introduction + + Ethereal provides a wide range of network statistics. + + + 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). + + + + General statistics: + + + + Summary about the capture file. + + + Protocol Hierarchy of the captured packets. + + + Endpoints e.g. traffic to and from an IP + addresses. + + + Conversations e.g. traffic between specific IP + addresses. + + + IO Graphs visualizing the number of packets (or + similar) in time. + + + + + + Protocol specific statistics: + + + + Service Response Time between request and response + of some protocols. + + + Various other protocol specific statistics. + + + + + Note! + + 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. + + + +
+ +
+ The "Summary" window + + General statistics about the current capture file. + +
The "Summary" window + +
+ + + File general information about the capture file. + + + + Time the timestamps when the first and the + last packet were capturing (and the time between them). + + + Capture 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). + + + Display some display related information. + + + + Traffic some statistics of the network traffic seen. + If a display filter is set, you will see values in both columns. The + values in the Captured column will remain the same as + before, while the values in the Displayed column will + reflect the values corresponding to the packets shown in the display. + + + +
+ +
+ The "Protocol Hierarchy" window + + The protocol hierarchy of the captured packets. +
The "Protocol Hierarchy" window + +
+ 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. + + + Each row contains the statistical values of one protocol. + + + The following columns containing the statistical values are available: + + + Protocol this protocol's name + + + % Packets the percentage of protocol packets, + relative to all packets in the capture + + + Packets the absolute number of packets of this + protocol + + + Bytes the absolute number of bytes of this + protocol + + + MBit/s the bandwidth of this protocol, relative + to the capture time + + + + End Packets the absolute number of packets of this + protocol (where this protocol were the highest protocol to decode) + + + + + End Bytes the absolute number of bytes of this protocol + (where this protocol were the highest protocol to decode) + + + + + End MBit/s the bandwidth of this protocol, relative to + the capture time (where this protocol were the highest protocol to decode) + + + + + Note! + + 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%). + + + Note! + + 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. + + +
+ +
+ Endpoints + + Statistics of the endpoints captured. + Tip! + + If you are looking for a feature other network tools call a + hostlist, here is the right place to look. The list of + Ethernet or IP endpoints is usually what you're looking for. + + + +
What is an Endpoint? + + 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: + + + + + Ethernet an Ethernet endpoint is identical to the + Ethernet's MAC address. + + + + + Fibre Channel XXX - insert info here. + + + + + FDDI a FDDI endpoint is identical to the FDDI MAC + address. + + + + + IPv4 an IP endpoint is identical to its IP address. + + + + + IPX XXX - insert info here. + + + + + TCP 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. + + + + + Token Ring a Token Ring endpoint is identical to the + Token Ring MAC address. + + + + + UDP 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. + + + + Broadcast / multicast endpoints + + 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. + + +
+
+ The "Endpoints" window + + This window shows statistics about the endpoints captured. + +
The "Endpoints" window + +
+ + 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). + + + Each row in the list shows the statistical values for exactly one endpoint. + + + Name resolution 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. + + Tip! + + 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. + + +
+
+ The protocol specific "Endpoint List" windows + + 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. + +
+
+ +
+ Conversations + + Statistics of the captured conversations. + +
What is a Conversation? + + 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 + . + +
+
The "Conversations" window + + Beside the list content, the conversations window work the same way as the + endpoint ones, see for a + description how it works. +
The "Conversations" window + +
+ +
+
+ The protocol specific "Conversation List" windows + + 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. + +
+
+ +
+ The "IO Graphs" window + + User configurable graph of the captured network packets. + + + You can define up to five differently colored graphs. + + +
The "IO Graphs" window + +
+ + + The user can configure the following things: + + + Graphs + + + + Graph 1-5 enable the graph 1-5 (only graph 1 is enabled + by default) + + + + + Color the color of the graph (cannot be changed) + + + + + Filter: a display filter for this graph (only the + packets that pass this filter will be taken into account for that graph) + + + + + Style: the style of the graph (Line/Impulse/FBar) + + + + + + + + X Axis + + + + Tick interval an interval in x direction lasts + (10/1/0.1/0.01/0.001 seconds) + + + + + Pixels per tick use 10/5/2/1 pixels per tick interval + + + + + + + + Y Axis + + + + Unit the unit for the y direction (Packets/Tick, + Bytes/Tick, Advanced...) + + + + + Scale the scale for the y unit + (10,20,50,100,200,500,...) + + + + + + + + XXX - describe the Advanced feature. + +
+ +
+ Service Response Time + + The service response time is the time between a request and the + corresponding response. This information is available for many protocols. + + + Service response time statistics are currently available for the following + protocols: + + + DCE-RPC + + + Fibre Channel + + + H.225 RAS + + + LDAP + + + MGCP + + + ONC-RPC + + + SMB + + + As an example, the DCE-RPC service response time is described in more + detail. + Note! + + The other Service Response Time windows will work the same way (or only + slightly different) compared to the following description. + + + +
+ The "Service Response Time DCE-RPC" window + + The service response time of DCE-RPC is the time between the request and + the corresponding response. + + + First of all, you have to select the DCE-RPC interface: + +
The "Compute DCE-RPC statistics" window + +
+ + You can optionally set a display filter, to reduce the amount of packets. + +
The "DCE-RPC Statistic for ..." window + +
+ + 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. + +
+
+ +
+ The protocol specific statistics windows + + The protocol specific statistics windows display detailed information + of specific protocols and might be described in a later + version of this document. + + + Some of these statistics are described at the + pages. + +
+ + + + 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 @@ + + + + + Troubleshooting with <application>Ethereal</application> +
+ An approach to troubleshooting with Ethereal + + 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: + + + + It allows you to focus in on specific packets and protocols, + as you can see a large amount of detail associated with + various protocols. + + + + + It supports a large number of protocols, and the list of + protocols supported is growing as more people contribute + dissectors + + + + + 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. + + + + + + The following general approach is suggested: + + + + Determine that the problem looks like a networking problem. + There is no point in capturing packets if the problem is not + networking related. + + + + + 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 for more details. + + + Because Ethereal can read many capture file formats, you can + capture using any conventient tool. One useful approach is + to use tcpdump to capture on remote + systems and then copy the capture file to your system for + later analysis. For more details on capturing with + tcpdump, see . + + + + + 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. + + + + + Examine the appropriate fields within the packets where + the problem appears to be. These can often help to reveal + the problem. + + + + +
+
+ Capturing in the presence of switches and routers + + 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. + + + 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. + + + 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. + + + There are some ways to circumvent this. + + + 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 + + Configuring the Catalyst Switched Port Analyzer (SPAN) Feature + + +
+
+ Examples of troubleshooting + + 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. + +
+ + + 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 @@ + + + + + User Interface +
Introduction + + By now you have installed Ethereal and + are most likely keen to get started capturing your first packets. In + the next chapters we will explore: + + + + How the Wireshark user interface works + + + + + How to capture packets in Ethereal + + + + + How to view packets in Ethereal + + + + + How to filter packets in Ethereal + + + + + ... and many other things! + + + + +
+ +
Start Ethereal + + You can start Ethereal from your shell or window manager. + Tip! + + When starting Ethereal it's possible to specify optional settings using + the command line. See for details. + + + Note! + + 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. + + + +
+ +
The Main window + + Lets look at Ethereal's user interface. shows + Ethereal as you would usually see it after some packets captured or loaded + (how to do this will be described later). +
+ The Main window + +
+ + + Ethereal's main window consist of parts that are commonly known from many + other GUI programs. + + + + The menu (see ) + is used to start actions. + + + + + The main toolbar (see ) + provides quick access to frequently used items from the menu. + + + + + The filter toolbar (see ) + provides a way to directly manipulate the currently used display filter + (see ). + + + + + The packet list pane (see ) + displays a summary of each packet captured. By clicking on packets + in this pane you control what is displayed in the other two panes. + + + + + The packet details pane (see ) + displays the packet selected in the packet list pane in more detail. + + + + + The packet bytes pane (see ) + displays the data from the packet selected in the packet list pane, and + highlights the field selected in the packet details pane. + + + + + The statusbar (see ) + shows some detailed information about the current program state and + the captured data. + + + + Tip! + + The layout of the main window can be customized by changing preference settings. + See for details! + + + +
+ +
The Menu + + The Wireshark menu sits on top of the Wireshark window. + An example is shown in . + + Note! + + 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. + + + +
The Menu + +
+ + + It contains the following items: + + File + + + 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 . + + + + Edit + + + 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 . + + + + View + + 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 . + + + + Go + + This menu contains items to go to a specific packet. + See . + + + + Capture + + This menu allows you to start and stop captures and to edit capture filters. + See . + + + + Analyze + + + 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 . + + + + Statistics + + + 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 . + + + + Help + + + 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 . + + + + + Each of these menu items is described in more detail in the sections + that follow. + + Tip! + + 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. + + +
+ +
The "File" menu + + The Wireshark file menu contains the fields shown in + . + +
+ The "File" Menu + +
+ File menu items + + + + + + Menu Item + Accelerator + Description + + + + + Open... + Ctrl+O + + 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 . + + + + Open Recent + + + 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. + + + + Merge... + + + 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 . + + + + Close + Ctrl+W + + 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). + + + + ------ + + + + + Save + Ctrl+S + + 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 ). + + Note! + + If you have already saved the current capture, this + menu item will be greyed out. + + + Note! + + You cannot save a live capture while it is in + progress. You must stop the capture in order to + save. + + + + + Save As... + Shift+Ctrl+S + + 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 ). + + + + ------ + + + + + File Set > List Files + + + 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 ). + + + + File Set > Next File + + + 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. + + + + File Set > Previous File + + + 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. + + + + ------ + + + + + Export > as "Plain Text" file... + + + 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 + ). + + + + Export > as "PostScript" file... + + + 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 + ). + + + + Export > as "CSV" (Comma Separated Values packet summary) file... + + + 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 + ). + + + + Export > as "PSML" file... + + + 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 + ). + + + + Export > as "PDML" file... + + + 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 + ). + + + + Export > Selected Packet Bytes... + Ctrl+H + + 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 + ) + + + + ------ + + + + + Print... + Ctrl+P + + 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 + ). + + + + ------ + + + + + Quit + Ctrl+Q + + 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). + + + + +
+
+ +
The "Edit" menu + + The Wireshark Edit menu contains the fields shown in + . + +
+ The "Edit" Menu + +
+ + Edit menu items + + + + + + Menu Item + Accelerator + Description + + + + + Find Packet... + Ctrl+F + + 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 + . + + + + Find Next + Ctrl+N + + This menu item tries to find the next packet matching the + settings from "Find Packet...". + + + + Find Previous + Ctrl+B + + This menu item tries to find the previous packet matching the + settings from "Find Packet...". + + + + ------ + + + + + Time Reference > Set Time Reference (toggle) + Ctrl+T + + This menu item set a time reference on the currently selected + packet. See for more information + about the time referenced packets. + + + + Time Reference > Find Next + + + This menu item tries to find the next time referenced packet. + + + + Time Reference > Find Previous + + + This menu item tries to find the previous time referenced packet. + + + + Mark Packet (toggle) + Ctrl+M + + This menu item "marks" the currently selected packet. See + for details. + + + + Mark All Packets + + + This menu item "marks" all packets. + + + + Unmark All Packets + + This menu item "unmarks" all marked packets. + + + + ------ + + + + + Preferences... + Shift+Ctrl+P + + 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 . + + + + +
+
+ +
The "View" menu + + The Wireshark View menu contains the fields shown in + . + +
+ The "View" Menu + +
+ + View menu items + + + + + + Menu Item + Accelerator + Description + + + + + Main Toolbar + + + This menu item hides or shows the main toolbar, see + . + + + + Filter Toolbar + + + This menu item hides or shows the filter toolbar, see + . + + + + Statusbar + + + This menu item hides or shows the statusbar, see + . + + + + ------ + + + + + Packet List + + + This menu item hides or shows the packet list pane, see + . + + + + Packet Details + + + This menu item hides or shows the packet details pane, see + . + + + + Packet Bytes + + + This menu item hides or shows the packet bytes pane, see + . + + + + ------ + + + + + Time Display Format > Date and Time of Day: 1970-01-01 01:02:03.123456 + + + Selecting this tells Ethereal to display the + time stamps in date and time of day format, see + . + Note! + + The fields "Time of Day", "Date and Time of + Day", "Seconds Since Beginning of Capture" and "Seconds Since + Previous Packet" are mutually exclusive. + + + + + + Time Display Format > Time of Day: 01:02:03.123456 + + + Selecting this tells Ethereal to display time + stamps in time of day format, see + . + + + + Time Display Format > Seconds Since Beginning of Capture: 123.123456 + + + Selecting this tells Ethereal to display time + stamps in seconds since beginning of capture format, see + . + + + + Time Display Format > Seconds Since Previous Packet: 1.123456 + + + Selecting this tells Ethereal to display time stamps in + seconds since previous packet format, see + . + + + + Time Display Format > ------ + + + + + Time Display Format > Automatic (File Format Precision) + + + Selecting this tells Ethereal to display time stamps with the + precision given by the capture file format used, see + . + Note! + + The fields "Automatic", "Seconds" and "...seconds" are mutually exclusive. + + + + + + Time Display Format > Seconds: 0 + + + Selecting this tells Ethereal to display time stamps with a precision of one second, see + . + + + + Time Display Format > ...seconds: 0.... + + + Selecting this tells Ethereal to display time stamps with a precision of one second, decisecond, centisecond, millisecond, microsecond or nanosecond, see + . + + + + Name Resolution > Resolve Name + + + This item allows you to trigger a name resolve of the current packet + only, see . + + + + Name Resolution > Enable for MAC Layer + + + This item allows you to control whether or not + Ethereal translates MAC addresses into names, see + . + + + + Name Resolution > Enable for Network Layer + + + This item allows you to control whether or not + Ethereal translates network addresses into names, see + . + + + + Name Resolution > Enable for Transport Layer + + + This item allows you to control whether or not + Ethereal translates transport addresses into names, see + . + + + + Colorize Packet List + + + This item allows you to control wether or not Ethereal should colorize + the packet list. + Note! + Enabling colorization will slow down the display + of new packets while capturing / loading capture files. + + + + Auto Scroll in Live Capture + + + 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. + + + + ------ + + + + + Zoom In + Ctrl++ + + Zoom into the packet data (increase the font size). + + + + Zoom Out + Ctrl+- + + Zoom out of the packet data (decrease the font size). + + + + Normal Size + Ctrl+= + + Set zoom level back to 100% (set font size back to normal). + + + + Resize All Columns + + + Resize all column widths so the content will fit into it. + + Note! + Resizing may take a significant amount of time, especially if a + large capture file is loaded. + + + + + ------ + + + + + Expand Subtrees + + + This menu item expands the currently selected subtree in the + packet details tree. + + + + Expand All + + + 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. + + + + Collapse All + + + This menu item collapses the tree view of all packets + in the capture list. + + + + ------ + + + + + Coloring Rules... + + + 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 + . + + + + ------ + + + + + Show Packet in New Window + + + This menu item brings up the selected packet in a + separate window. The separate window shows only the + tree view and byte view panes. + + + + Reload + Ctrl-R + + This menu item allows you to reload the current + capture file. + + + + +
+
+ +
The "Go" menu + + The Wireshark Go menu contains the fields shown in + . + +
+ The "Go" Menu + +
+ + Go menu items + + + + + + Menu Item + Accelerator + Description + + + + + Back + Alt+Left + + Jump to the recently visited packet in the packet + history, much like the page history in a web browser. + + + + Forward + Alt+Right + + Jump to the next visited packet in the packet + history, much like the page history in a web browser. + + + + Go to Packet... + Ctrl-G + + Bring up a dialog box that allows you + to specify a packet number, and then goes to that packet. See + for details. + + + + Go to Corresponding Packet + + + 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. + + + + ------ + + + + + First Packet + + + Jump to the first packet of the capture file. + + + + Last Packet + + + Jump to the last packet of the capture file. + + + + +
+
+ +
The "Capture" menu + + The Wireshark Capture menu contains the fields shown in + . + +
+ The "Capture" Menu + +
+ + Capture menu items + + + + + + Menu Item + Accelerator + Description + + + + + Interfaces... + + + This menu item brings up a dialog box that shows what's going on + at the network interfaces Ethereal knows of, see + ) . + + + + Options... + Ctrl+K + + This menu item brings up the Capture Options + dialog box (discussed further in + ) and allows you to + start capturing packets. + + + + Start + + + Immediately start capturing packets with the same settings than + the last time. + + + + Stop + Ctrl+E + + This menu item stops the currently running capture, see + ) . + + + + Restart + + + This menu item stops the currently running capture and starts + again with the same options, this is just for convenience. + + + + Capture Filters... + + + 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 + + + + + +
+
+ +
The "Analyze" menu + + The Wireshark Analyze menu contains the fields shown in + . + +
+ The "Analyze" Menu + +
+ Analyze menu items + + + + + + Menu Item + Accelerator + Description + + + + + Display Filters... + + + 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 + + + + + Apply as Filter > ... + + + 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. + + + + Prepare a Filter > ... + + + 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. + + + + ------ + + + + + Enabled Protocols... + Shift+Ctrl+R + + This menu item allows the user to enable/disable protocol + dissectors, see + + + + Decode As... + + + This menu item allows the user to force Ethereal to + decode certain packets as a particular protocol, see + + + + + User Specified Decodes... + + + This menu item allows the user to force Ethereal to + decode certain packets as a particular protocol, see + + + + + ------ + + + + + Follow TCP Stream + + + 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 + + + + + +
+
+ +
The "Statistics" menu + + The Wireshark Statistics menu contains the fields shown in + . + +
+ The "Statistics" Menu + +
+ + All menu items will bring up a new window showing specific statistical + information. + + + Statistics menu items + + + + + + Menu Item + Accelerator + Description + + + + + Summary + + + Show information about the data captured, see . + + + + Protocol Hierarchy + + + Display a hierarchical tree of protocol statistics, see . + + + + Conversations + + + Display a list of conversations (traffic between two endpoints), + see . + + + + Endpoints + + + Display a list of endpoints (traffic to/from an address), see + . + + + + IO Graphs + + + Display user specified graphs (e.g. the number of packets in the + course of time), see . + + + + ------ + + + + + Conversation List + + + Display a list of conversations, obsoleted by the combined window + of Conversations above, see + . + + + + Endpoint List + + + Display a list of endpoints, obsoleted by the combined window + of Endpoints above, see + . + + + + Service Response Time + + + Display the time between a request and the corresponding response, see + . + + + + ------ + + + + + ANSI + + See + + + GSM + + See + + + H.225... + + See + + + ISUP Message Types + + See + + + MTP3 + + See + + + RTP + + See + + + SCTP + + See + + + SIP + + See + + + VoIP Calls... + + See + + + WAP-WSP... + + See + + + ------ + + + + + BOOTP-DHCP + + See + + + HTTP + + HTTP request/response statistics, see + + + ISUP Messages + + See + + + ONC-RPC Programs + + See + + + TCP Stream Graph + + See + + + +
+
+ +
The "Help" menu + + The Wireshark Help menu contains the fields shown in + . + +
+ The "Help" Menu + +
+ + Help menu items + + + + + + Menu Item + Accelerator + Description + + + + + Contents + F1 + + This menu item brings up a basic help system. + + + + Supported Protocols + + + This menu item brings up a dialog box showing the supported + protocols and protocol fields. + + + + Manual Pages > ... + + + This menu item starts a Web browser showing one of the locally + installed html manual pages. + + + + Ethereal Online > ... + + + This menu item starts a Web browser showing the chosen + webpage from: + &EtherealWebSite;. + + + + ------ + + + + + About Ethereal + + + This menu item brings up an information window that + provides some information on Ethereal, such as the plugins, the + used folders, ... + + + + +
+ Note! + + Calling a Web browser might be unsupported in your version of Ethereal. + If this is the case, the corresponding menu items will be hidden. + + + Note! + + 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. + + +
+ +
The "Main" toolbar + + 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. + + + 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). +
+ The "Main" toolbar + +
+ + + Main toolbar items + + + + + + + Toolbar Icon + Toolbar Item + Corresponding Menu Item + Description + + + + + + Interfaces... + Capture/Interfaces... + + This item brings up the Capture Interfaces List + dialog box (discussed further in + ). + + + + + + Options... + Capture/Options... + + This item brings up the Capture Options + dialog box (discussed further in + ) and allows you to + start capturing packets. + + + + + + Start + Capture/Start + + This item starts capturing packets with the options form + the last time. + + + + + + Stop + Capture/Stop + + This item stops the currently running live capture process + ). + + + + + + Restart + Capture/Restart + + This item stops the currently running live capture process + and restarts it again, for convenience. + + + + + ------ + + + + + + Open... + File/Open... + + 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 . + + + + + Save As... + File/Save As... + + 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 ). + + Note! + + If you currently have a temporary capture file, the Save icon + will be + shown instead. + + + + + + Close + File/Close + + This item closes the current capture. If you + have not saved the capture, you will be asked to save it first. + + + + + Reload + View/Reload + + This item allows you to reload the current capture file. + + + + + Print... + File/Print... + + 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 + ). + + + + ------ + + + + + + Find Packet... + Edit/Find Packet... + + This item brings up a dialog box that allows you + to find a packet. There is further information on finding packets + in . + + + + + Go Back + Go/Go Back + + This item jumps back in the packet history. + + + + + Go Forward + Go/Go Forward + + This item jumps forward in the packet history. + + + + + Go to Packet... + Go/Go to Packet... + + This item brings up a dialog box that allows you + to specify a packet number to go to that packet. + + + + + Go To First Packet + Go/First Packet + + This item jumps to the first packet of the capture file. + + + + + Go To Last Packet + Go/Last Packet + + This item jumps to the last packet of the capture file. + + + + ------ + + + + + + Colorize + View/Colorize + + Colorize the packet list (or not). + + + + + Auto Scroll in Live Capture + View/Auto Scroll in Live Capture + + Auto scroll packet list while doing a live capture (or not). + + + + ------ + + + + + + Zoom In + View/Zoom In + + Zoom into the packet data (increase the font size). + + + + + Zoom Out + View/Zoom Out + + Zoom out of the packet data (decrease the font size). + + + + + Normal Size + View/Normal Size + + Set zoom level back to 100%. + + + + + Resize Columns + View/Resize Columns + + Resize columns, so the content fits into them. + + + + ------ + + + + + + Capture Filters... + Capture/Capture Filters... + + 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 + . + + + + + Display Filters... + Analyze/Display Filters... + + 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 + . + + + + + Coloring Rules... + View/Coloring Rules... + + 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 + . + + + + + Preferences... + Edit/Preferences + + 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 + + + + ------ + + + + + + Help + Help/Contents + + This item brings up help dialog box. + + + + +
+
+ +
The "Filter" toolbar + + The filter toolbar lets you quickly edit and apply display filters. More information on + display filters is available in . +
+ The "Filter" toolbar + +
+ + + + The leftmost button labeled "Filter:" can be clicked to + bring up the filter construction dialog, described in . + + + + + The left middle text box provides an area to enter or edit display + filter strings, see + . 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. + + Note! + + 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. + + + Note! + + This field is also where the current filter in effect is displayed. + + + + + + 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 + + + + + + The right middle button labeled "Clear" resets the current + display filter and clears the edit area. + + + + + The rightmost button labeled "Apply" applies the current + value in the edit area as the new display filter. + + + + + Note! + + Applying a display filter on large capture files might take quite a long time! + + +
+ +
The "Packet List" pane + + The packet list pane displays all the packets in the current capture + file. +
+ The "Packet List" pane + +
+ 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. + + + 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. + + + 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. + + + There are a lot of different columns available. Which columns are + displayed can be selected by preference settings, see + . + + + The default columns will show: + + + No. + The number of the packet in the capture file. This number won't change, + even if a display filter is used. + + + + Time + The timestamp of the packet. The presentation format of this timestamp + can be changed, see . + + + + Source + The address where this packet is coming from. + + + + Destination + The address where this packet is going to. + + + + Protocol + The protocol name in a short (perhaps abbreviated) version. + + + + Info + Additional information about the packet content. + + + + + + There is a context menu (right mouse click) available, see details in + . + +
+ +
The "Packet Details" pane + + The packet details pane shows the current packet (selected in the "Packet List" + pane) in a more detailed form. +
+ The "Packet Details" pane + +
+ + + 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. + + + There is a context menu (right mouse click) available, see details in + . + + + Some protocol fields are specially displayed. + + + + + Generated fields + 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. + + + + + Links + 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. + + + +
+ +
The "Packet Bytes" pane + + The packet bytes pane shows the data of the current packet (selected in the "Packet List" + pane) in a hexdump style. +
+ The "Packet Bytes" pane + +
+ + + 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. + + + There is a context menu (right mouse click) available, see details in + . + + + 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 . 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. +
+ The "Packet Bytes" pane with tabs + +
+ + Note! + + The additional pages might contain data picked from multiple packets. + + + + 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. + +
+ +
The Statusbar + + The statusbar displays informational messages. + + + In general, the left side will show context related information, while the + right side will show the current number of packets. + + +
+ The initial Statusbar + +
+ This statusbar is shown while no capture file is loaded, e.g. when + Wireshark is started. + + +
+ The Statusbar with a loaded capture file + +
+ The left side shows information about the capture file, its + name, its size and the elapsed time while it was being captured. + + + The right side shows the current number of packets in the + capture file. The following values are displayed: + + + P: the number of captured packets + + + D: the number of packets currently being + displayed + + + M: the number of marked packets + + + + +
+ The Statusbar with a selected protocol field + +
+ This is displayed if you have selected a protocol field from the + "Packet Details" pane. + + Tip! + + The value between the brackets (in this example + arp.opcode) can be used as a display filter string, + representing the selected protocol field. + + +
+ + + 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 @@ + + + + + Working with captured packets + +
Viewing packets you have captured + + 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. + + + You can then expand any part of the tree view by clicking on the + plus 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 + . It also has the Acknowledgment number + in the TCP header selected, which shows up in the byte view as the + selected bytes. +
+ Ethereal with a TCP packet selected for viewing + +
+ + + 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. + + + In addition, you can view individual packets in a separate window as + shown in . 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. +
+ Viewing a packet in a separate window + +
+ + + 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. + + + 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. + + + Function overview of the pop-up menus + + + + + + + + + Item + List + Details + Bytes + Menu + Description + + + + + Mark Packet (toggle) + X + - + - + Edit + + Mark a packet. + + + + Time Reference + X + - + - + Edit + + Set/reset and find time references. + + + + Expand Subtrees + - + X + - + View + + Expand the currently selected subtree. + + + + + Expand All + - + X + - + View + + Expand all subtrees in all packets in the capture. + + + + + Collapse All + - + X + - + View + + + 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. + + + + + Apply as Filter + X + X + - + Analyze + + . + + + + Prepare a Filter + X + X + - + Analyze + + . + + + + Follow TCP stream + X + X + - + Analyze + + View all the data on a TCP stream between a pair of nodes. + + + + Wiki Protocol Page + - + X + - + - + + Show the wiki page corresponding to the currently selected protocol in your web browser. + + + + + Filter Field Reference + - + X + - + - + + Show the filter field reference web page corresponding to the currently selected protocol in your web browser. + + + + + Protocol Preferences... + - + X + - + - + + 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 . + + + + + Decode As... + X + X + - + Analyze + + . + + + + + + + Print... + X + - + - + File + + Print (the selected) packet(s). + + + + Show Packet in New Window + X + - + - + View + + Display the selected packet in another window. + + + + Resolve name + - + X + - + View/Name Resolution + + Cause a name resolution to be performed for the selected packet, + but NOT for every packet in the capture. + + + + Go to Corresponding Packet + - + X + - + Go + + 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. + + + + + Copy + - + - + X + - + + Copy the selected packet data to the clipboard (XXX - in which format). + + + + + Export Selected Packet Bytes... + - + - + X + File->Export + + Export raw packet bytes to a binary file. + + + + +
+ +
+ Pop-up menu of "Packet List" pane + +
+ + Mark Packet (toggle) + + + This menu item is the same as the Edit menu item of the same + name. It allows you to mark a packet. + + + + Time Reference + + + 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. + + + + Apply as Filter + + + This menu item is the same as the Analyze menu items of the same + name. + + + + Prepare a Filter + + + This menu item is the same as the Analyze menu items of the same + name. + + + + Follow TCP Stream + + + 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. + + + + Decode As... + + + This menu item is the same as the Analyze menu item of the + same name. + + + + Print... + + + This menu item is the same as the File menu item of the same + name. It allows you to print packets. + + + + + Show Packet in New Window + + + 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. + + + + + + +
+ Pop-up menu of "Packet Details" pane + +
+ + Expand Subtrees + + + This menu item expands the currently selected subtree. + + + + Expand All + + + This menu item expands all subtrees in all packets in the + capture. + + + + Collapse All + + + 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. + + + + Apply as Filter + + + This menu item is the same as the Analyze menu items of the same + name. + + + + Prepare a Filter + + + This menu item is the same as the Analyze menu items of the same + name. + + + + Follow TCP Stream + + + 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. + + + + Wiki Protocol Page + + + Show the wiki page corresponding to the currently selected protocol + in your web browser. + + + + Filter Field Reference + + + Show the filter field reference web page corresponding to the + currently selected protocol in your web browser. + + + + Protocol Properties... + + + 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 + . + + + + Decode As... + + + This menu item is the same as the Analyze menu item of the + same name. + + + + Resolve Name + + + This menu item causes name resolution to be performed for + the selected packet, but NOT every packet in the capture. + + + + Go to Corresponding Packet + + + If the selected field has a corresponding packet, go to it. + Corresponding packets will usually be a request/response packet pair + or such. + + + + + + +
+ Pop-up menu of "Packet Bytes" pane + +
+ + Copy + + + Copy the selected packet data to the clipboard (XXX - in which format). + + + + Export Selected Packet Bytes... + + + 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. + + + + + +
+ +
Filtering packets while viewing + + 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 . + + + 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: + + Protocol + The presence of a field + The values of fields + A comparison between fields + ... and a lot more! + + + + To select packets based on protocol type, simply type the protocol you + are interested in in the Filter: field in the filter + toolbar of the Wireshark window and press enter to initiate + the filter. shows an example of what + happens when you type tcp in the filter field. + + + Note! + + All protocol and field names are entered in lowercase. Also, don't + forget to press enter after entering the filter expression. + + +
Filtering on the TCP protocol + +
+ + 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. + + + Note! + + 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! + + + + 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 + Add Expression... dialog box. You can find more + information on the Add Expression... dialog box + in . + + + For example, to narrow the packet list pane down to only those + packets to or from the IP address 192.168.0.1, use + ip.addr==192.168.0.1. + + + Note! + + To remove the filter, click on the Clear button + to the right of the filter field. + + +
+ +
+ Building display filter expressions + + 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. + + + Tip! + + You will find a lot of Display Filter examples at the Ethereal + Wiki Display Filter page at &EtherealWikiDisplayFiltersPage;. + + +
+ Display filter fields + + 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: tcp will show all packets containing the + tcp protocol. + + + 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. + + + XXX - add some more info here and a link to the statusbar info. + +
+
+ Comparing values + + You can build display filters that compare values using a number + of different comparison operators. They are shown in + . + + Tip! + + You can use English and C-like terms in the same way, they can even be + mixed in a filter string! + + + + Display Filter comparison operators + + + + + + English + C-like + Description and example + + + + + eq + == + + Equal + ip.addr==10.0.0.5 + + + + ne + != + + Not equal + ip.addr!=10.0.0.5 + + + + gt + > + + Greater than + frame.pkt_len > 10 + + + + lt + < + Less than + frame.pkt_len < 128 + + + + ge + >= + + Greater than or equal to + frame.pkt_len ge 0x100 + + + + le + <= + + Less than or equal to + frame.pkt_len <= 0x20 + + + + +
+ + In addition, all protocol fields are typed. + provides a list of the types and + example of how to express them. + + Display Filter Field Types + + + + Type + Example + + + + + + Unsigned integer (8-bit, 16-bit, 24-bit, 32-bit) + + + You can express integers in decimal, octal, or + hexadecimal. The following display filters are + equivalent: + +ip.len le 1500 +ip.len le 02734 +ip.len le 0x436 + + + + + + Signed integer (8-bit, 16-bit, 24-bit, 32-bit) + + + + + Boolean + + A boolean field is present in the protocol decode + only if its value is true. For example, + tcp.flags.syn is present, and + thus true, only if the SYN flag is present in a + TCP segment header. + Thus the filter expression + tcp.flags.syn 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 + tr.sr. + + + + Ethernet address (6 bytes) + eth.addr == ff:ff:ff:ff:ff:ff + + + IPv4 address + ip.addr == 192.168.0.1 + + + IPv6 address + + + + IPX network number + + + + String (text) + + + + + Double-precision floating point number + + + + + +
+ +
+
+ Combining expressions + + You can combine filter expressions in Wireshark using the + logical operators shown in + + + Display Filter Logical Operations + + + + + + English + C-like + Description and example + + + + + and + && + + Logical AND + ip.addr==10.0.0.5 and tcp.flags.fin + + + + or + || + + Logical OR + ip.addr==10.0.0.5 or ip.addr==192.1.1.1 + + + + xor + ^^ + + Logical XOR + tr.dst[0:3] == 0.6.29 xor tr.src[0:3] == 0.6.29 + + + + not + ! + + Logical NOT + not llc + + + + [...] + + + Substring Operator + 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. + eth.src[0:3] == 00:00:83 + 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. + +eth.src[1-2] == 00:83 + + 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. + eth.src[:4] == 00:00:83:00 + 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 + eth.src[4:] == 20:20 + The example above uses the n: format, which takes + everything from offset n to the end of the + sequence. + eth.src[2] == 83 + 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. + eth.src[0:3,1-2,:4,4:,2] == +00:00:83:00:83:00:00:83:00:20:20:83 + Ethereal allows you to string together single ranges + in a comma separated list to form compound ranges as + shown above. + + + + +
+
+
A common mistake + Warning! + + Using the != operator on combined expressions like: eth.addr, ip.addr, + tcp.port, udp.port and alike will probably not work as expected! + + + + Often people use a filter string to display something like + ip.addr == 1.2.3.4 which will display all packets + containing the IP address 1.2.3.4. + + + Then they use ip.addr != 1.2.3.4 to see all packets + not containing the IP address 1.2.3.4 in it. Unfortunately, this does + not do the expected. + + + 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 ip.addr != 1.2.3.4 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. + + + 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 !(ip.addr == 1.2.3.4) 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". + +
+
+ +
+ The "Filter Expression" dialog box + + 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. + + Tip! + + The "Filter Expression" dialog box is an excellent way to learn how to + write Ethereal display filter strings. + + +
+ The "Filter Expression" dialog box + +
+ + 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. + + + Field Name + + + 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. + + + + Relation + + + Select a relation from the list of available relation. + The is present 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 Value to match) to complete. + + + + + + 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. + + + Value + + + You may enter an appropriate value in the + Value text box. The Value + will also indicate the type of value for the + field name you have selected (like + character string). + + + + Predefined values + + + 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. + + + + Range + + + XXX - add an explanation here! + + + + OK + + + When you have built a satisfactory expression click + OK and a filter string will be + built for you. + + + + Cancel + + + You can leave the Add Expression... dialog + box without any effect by clicking the Cancel + + + + +
+ +
Defining and saving filters + + 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. + + + To define a new filter or edit an existing one, select the + Capture Filters... menu item from the Capture menu + or the Display Filters... menu item from the Analyze + menu. Ethereal will then pop up the Filters dialog as shown in + . + + + Note! + + 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. + + + Warning! + + You must use Save to save your filters permanently. + Ok or Apply will not save the filters, + so they will be lost when you close Ethereal. + + +
+ The "Capture Filters" and "Display Filters" dialog boxes + +
+ + + New + + + 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". + + + + Delete + + + This button deletes the selected filter. It will be greyed out, if no + filter is selected. + + + + Filter + + + 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). + + + + Filter name: + + + You can change the name of the currently selected filter here. + + Note! + + 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. + + + + + Filter string: + + + 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. + + + + Add Expression... + + + 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 + + + + + OK + + + Display Filter only: This button applies the selected filter to the + current display and closes the dialog. + + + + Apply + + + Display Filter only: This button applies the selected filter to the + current display, and keeps the dialog open. + + + + Save + + + Save the current settings in this dialog. The file location and + format is explained in . + + + + Close + + + Close this dialog. This will discard unsaved settings. + + + + + +
+ +
Finding packets + + You can easily find packets once you have captured some packets or + have read in a previously saved capture file. Simply select the + Find Packet... menu item from the + Edit menu. Ethereal will pop up the dialog box + shown in . + +
The "Find Packet" dialog box +
+ The "Find Packet" dialog box + +
+ + You might first select the kind of thing to search for: + + + + Display filter + + + Simply enter a display filter string into the + Filter: field, select a direction, and click on OK. + + + For example, to find the three way handshake for a connection from + host 192.168.0.1, use the following filter string: + ip.addr==192.168.0.1 and tcp.flags.syn + For more details on display filters, see + + + + + Hex Value + + + Search for a specific byte sequence in the packet data. + + + For example, use "00:00" to find the next packet including two + null bytes in the packet data. + + + + + String + + + Find a string in the packet data, with various options. + + + + + + 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. + + + You can choose the direction to be searched for: + + + Up + Search upwards in the packet list (decreasing packet numbers). + + + + + Down + Search downwards in the packet list (increasing packet numbers). + + + +
+
The "Find Next" command + + "Find Next" will continue searching with the same options like in the last + "Find Packet" run. + +
+
The "Find Previous" command + + "Find Previous" will do the same thing as "Find Next", but with reverse + search direction. + +
+
+ +
Go to a specific packet + + You can easily jump to specific packets with one of the menu items in the + Go menu. + +
The "Go Back" command + + Go back in the packet history, works much like the page history in current + web browsers. + +
+
The "Go Forward" command + + Go forward in the packet history, works much like the page history in + current web browsers. + +
+
The "Go to Packet" dialog box +
+ The "Go To Packet" dialog box + +
+ + This dialog box will let you enter a packet number. When you press + OK, Ethereal will jump to that packet. + +
+
The "Go to Corresponding Packet" command + + If a protocol field is selected which points to another packet in the + capture file, this command will jump to that packet. + + Note! + + 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. + + +
+
The "Go to First Packet" command + + This command will simply jump to the first packet displayed. + +
+
The "Go to Last Packet" command + + This command will simply jump to the last packet displayed. + +
+
+ +
Marking packets + + 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. + + Warning! + + 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. + + + + 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 . + + + There are three functions to manipulate the marked state of a packet: + + + + Mark packet (toggle) toggles the marked state + of a single packet. + + + + + Mark all packets set the mark state of all + packets. + + + + + Unmark all packets reset the mark state of all + packets. + + + + 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. + +
+ +
Time display formats and time + references + + 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. + + + A detailed description of timestamps, timezones and alike can be found at: . + + + The timestamp presentation format and the precision in the packet list can + be chosen using the View menu, see . + + + The available presentation formats are: + + Date and Time of Day: 1970-01-01 01:02:03.123456 + The absolute date and time of the day when the packet was captured. + + Time of Day: 01:02:03.123456 + The absolute time of the day when the packet was captured. + + Seconds Since Beginning of Capture: 123.123456 + The time relative to the start of the capture file or the first + "Time Reference" before this packet (see ). + + Seconds Since Previous Packet: 1.123456 + The time relative to the previous packet. + + + + + The available precisions (aka. the number of displayed decimal places) are: + + Automatic + The timestamp precision of + the loaded capture file format will be used (the default). + + Seconds, Deciseconds, Centiseconds, Milliseconds, + Microseconds or Nanoseconds + 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. + + + + + 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. + +
+ Packet time referencing + + 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. + + Warning! + + The time references will not be saved permanently and will be lost when + you close the capture file. + + + Note! + + 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). + + + + To work with time references, choose one of the "Time Reference" items + in the "Edit" menu , see , or from + the pop-up menu of the "Packet List" pane. + + + Set Time Reference (toggle) + Toggles the time reference state of the currently selected + packet to on or off. + + Find Next + Find the next time referenced packet in the "Packet List" pane. + + + Find Previous + Find the previous time referenced packet in the "Packet List" + pane. + + + + +
+ Ethereal showing a time referenced packet + +
+ + + 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. + +
+
+ + + + 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 @@ + + + + <inlinegraphic entityref="EtherealLogo" valign="middle" format="PNG"/> &DocumentTitle; + &DocumentSubTitle; + + + &AuthorFirstName; + &AuthorSurname; + &AuthorOrgName; + + + &AuthorFirstName2; + &AuthorSurname2; + &AuthorOrgName2; + + + &AuthorFirstName3; + &AuthorSurname3; + &AuthorOrgName3; + + + + + &DocumentCopyrightYear; + &DocumentCopyrightHolder1; + &DocumentCopyrightHolder2; + &DocumentCopyrightHolder3; + + + + + + &DocumentLegalNotice; + + + 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 @@ + + + + Preface +
+ Foreword + + 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. + + + This document is part of an effort by the Wireshark team to improve the + usability of Ethereal. + + + We hope that you find it useful, and look forward to your comments. + +
+ +
+ Who should read this document? + + The intended audience of this book is anyone using Ethereal. + + + 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. + + + 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 + &EtherealWikiPage; + + + 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. + +
+ +
+ Acknowledgements + + The authors would like to thank the whole Ethereal team for their + assistance. In particular, the authors would like to thank: + + + + Gerald Combs, for initiating the Wireshark project and funding to + do this documentation. + + + + + Guy Harris, for many helpful hints and a great deal of patience + in reviewing this document. + + + + + Gilbert Ramirez, for general encouragement and helpful hints along + the way. + + + + + + The authors would also like to thank the following people for their + helpful feedback on this document: + + + + Pat Eyler, for his suggestions on improving the example on + generating a backtrace. + + + + + Martin Regner, for his various suggestions and corrections. + + + + + Graeme Hewson, for a lot of grammatical corrections. + + + + + + The authors would like to acknowledge those man page and README authors + for the ethereal project from who sections of this document borrow heavily: + + + + Scott Renfro from whose mergecap man page + is derived. + + + + + Ashok Narayanan from whose text2pcap man page + is derived. + + + + + Frank Singleton from whose README.idl2eth + is derived. + + + + +
+ +
+ About this document + + This book was originally developed by + Richard Sharpe with + funds provided from the Wireshark Fund. It was updated by + Ed Warnicke and more recently + redesigned and updated by Ulf + Lamping. + + + It is written in DocBook/XML. + + + You will find some specially marked parts in this book: + + This is a warning! + + You should pay attention to a warning, as otherwise data loss might occur. + + + This is a note! + + A note will point you to common mistakes and things that might not be + obvious. + + + This is a tip! + + Tips will be helpful for your everyday work using Ethereal. + + +
+ +
+ Where to get the latest copy of this document? + + The latest copy of this documentation can always be found at: + . + +
+ +
+ Providing feedback about this document + + Should you have any feedback about this document, please send them + to the authors through &EtherealDevMailList;. + +
+ -- cgit v1.2.3