Wireshark User's Guide 24295 for Wireshark 0.99.7 Ulf Lamping, Richard Sharpe, NS Computer Software and Services P/L Ed Warnicke,
Wireshark Users Guide
24295 for Wireshark 0997
Ulf LampingRichard Sharpe NS Computer Software and Services PL
Ed Warnicke
Wireshark Users Guide 24295
for Wireshark 0997by Ulf Lamping Richard Sharpe and Ed WarnickeCopyright copy 2004-2007 Ulf Lamping Richard Sharpe Ed Warnicke
Permission is granted to copy distribute andor modify this document under the terms of the GNU General Public LicenseVersion 2 or any later version published by the Free Software Foundation
All logos and trademarks in this document are property of their respective owner
Table of ContentsPreface ix
1 Foreword ix2 Who should read this document x3 Acknowledgements xi4 About this document xii5 Where to get the latest copy of this document xiii6 Providing feedback about this document xiv
1 Introduction 111 What is Wireshark 1
111 Some intended purposes 1112 Features 1113 Live capture from many different network media 2114 Import files from many other capture programs 2115 Export files for many other capture programs 2116 Many protocol decoders 2117 Open Source Software 2118 What Wireshark is not 3
12 System Requirements 4121 General Remarks 4122 Microsoft Windows 4123 Unix Linux 5
13 Where to get Wireshark 614 A brief history of Wireshark 715 Development and maintenance of Wireshark 816 Reporting problems and getting help 9
161 Website 9162 Wiki 9163 FAQ 9164 Mailing Lists 9165 Reporting Problems 10166 Reporting Crashes on UNIXLinux platforms 10167 Reporting Crashes on Windows platforms 11
2 Building and Installing Wireshark 1321 Introduction 1322 Obtaining the source and binary distributions 1423 Before you build Wireshark under UNIX 1524 Building Wireshark from source under UNIX 1725 Installing the binaries under UNIX 18
251 Installing from rpms under Red Hat and alike 18252 Installing from debs under Debian 18253 Installing from portage under Gentoo Linux 18254 Installing from packages under FreeBSD 18
26 Troubleshooting during the install on Unix 1927 Building from source under Windows 2028 Installing Wireshark under Windows 21
281 Install Wireshark 21282 Manual WinPcap Installation 23283 Update Wireshark 23284 Update WinPcap 23285 Uninstall Wireshark 23286 Uninstall WinPcap 24
3 User Interface 2631 Introduction 2632 Start Wireshark 2733 The Main window 28
331 Main Window Navigation 2934 The Menu 30
iv
35 The File menu 3136 The Edit menu 3437 The View menu 3638 The Go menu 4039 The Capture menu 42310 The Analyze menu 44311 The Statistics menu 46312 The Help menu 48313 The Main toolbar 50314 The Filter toolbar 53315 The Packet List pane 54316 The Packet Details pane 55317 The Packet Bytes pane 56318 The Statusbar 57
4 Capturing Live Network Data 5941 Introduction 5942 Prerequisites 6043 Start Capturing 6144 The Capture Interfaces dialog box 6245 The Capture Options dialog box 64
451 Capture frame 64452 Capture File(s) frame 66453 Stop Capture frame 66454 Display Options frame 67455 Name Resolution frame 67456 Buttons 67
46 Capture files and file modes 6847 Link-layer header type 7048 Filtering while capturing 71
481 Automatic Remote Traffic Filtering 7249 While a Capture is running 74
491 Stop the running capture 74492 Restart a running capture 75
5 File Input Output and Printing 7751 Introduction 7752 Open capture files 78
521 The Open Capture File dialog box 78522 Input File Formats 80
53 Saving captured packets 82531 The Save Capture File As dialog box 82532 Output File Formats 84
54 Merging capture files 86541 The Merge with Capture File dialog box 86
55 File Sets 88551 The List Files dialog box 88
56 Exporting data 90561 The Export as Plain Text File dialog box 90562 The Export as PostScript File dialog box 90563 The Export as CSV (Comma Separated Values) File dialog box 91564 The Export as PSML File dialog box 91565 The Export as PDML File dialog box 92566 The Export selected packet bytes dialog box 93567 The Export Objects dialog box 94
57 Printing packets 96571 The Print dialog box 96
58 The Packet Range frame 9859 The Packet Format frame 99
6 Working with captured packets 10161 Viewing packets you have captured 10162 Pop-up menus 103
621 Pop-up menu of the Packet List pane 103622 Pop-up menu of the Packet Details pane 105
63 Filtering packets while viewing 108
Wireshark Users Guide
v
64 Building display filter expressions 110641 Display filter fields 110642 Comparing values 110643 Combining expressions 112644 A common mistake 113
65 The Filter Expression dialog box 11466 Defining and saving filters 11667 Finding packets 118
671 The Find Packet dialog box 118672 The Find Next command 119673 The Find Previous command 119
68 Go to a specific packet 120681 The Go Back command 120682 The Go Forward command 120683 The Go to Packet dialog box 120684 The Go to Corresponding Packet command 120685 The Go to First Packet command 120686 The Go to Last Packet command 120
69 Marking packets 121610 Time display formats and time references 122
6101 Packet time referencing 1227 Advanced Topics 125
71 Introduction 12572 Following TCP streams 126
721 The Follow TCP Stream dialog box 12673 Expert Infos 128
731 Expert Info Entries 128732 Expert Info Composite dialog 129733 Colorized Protocol Details Tree 130734 Expert Packet List Column (optional) 130
74 Time Stamps 131741 Wireshark internals 131742 Capture file formats 131743 Accuracy 131
75 Time Zones 133751 Set your computers time correctly 134752 Wireshark and Time Zones 134
76 Packet Reassembling 136761 What is it 136762 How Wireshark handles it 136
77 Name Resolution 138771 Name Resolution drawbacks 138772 Ethernet name resolution (MAC layer) 138773 IP name resolution (network layer) 139774 IPX name resolution (network layer) 139775 TCPUDP port name resolution (transport layer) 139
78 Checksums 140781 Wireshark checksum validation 140782 Checksum offloading 141
8 Statistics 14381 Introduction 14382 The Summary window 14483 The Protocol Hierarchy window 14684 Conversations 148
841 What is a Conversation 148842 The Conversations window 148843 The protocol specific Conversation List windows 148
85 Endpoints 149851 What is an Endpoint 149852 The Endpoints window 149853 The protocol specific Endpoint List windows 150
86 The IO Graphs window 15187 Service Response Time 153
Wireshark Users Guide
vi
871 The Service Response Time DCE-RPC window 15388 The protocol specific statistics windows 155
9 Customizing Wireshark 15791 Introduction 15792 Start Wireshark from the command line 15893 Packet colorization 16394 Control Protocol dissection 166
941 The Enabled Protocols dialog box 166942 User Specified Decodes 168943 Show User Specified Decodes 169
95 Preferences 17096 Configuration Profiles 17197 User Table 17498 Display Filter Macros 17599 Tektronix K12xx15 RF5 protocols Table 176910 User DLTs protocol table 177911 SNMP users Table 178912 SCCP users Table 179
10 Lua Support in Wireshark 181101 Introduction 181102 Example of Dissector written in Lua 182103 Example of Listener written in Lua 183104 Wiresharks Lua API Reference Manual 184
1041 saving capture files 1841042 obtaining dissection data 1861043 GUI support 1881044 post-dissection packet analysis 1921045 obtaining packet information 1931046 functions for writing dissectors 1961047 adding information to the dissection tree 2081048 functions for handling packet data 2101049 Utility Functions 215
A Files and Folders 220A1 Capture Files 220
A11 Libpcap File Contents 220A12 Not Saved in the Capture File 220
A2 Configuration Files and Folders 222A3 Windows folders 227
A31 Windows profiles 227A32 Windows VistaXP2000NT roaming profiles 227A33 Windows temporary folder 227
B Protocols and Protocol Fields 230C Wireshark Messages 231
C1 Packet List Messages 231C11 [Malformed Packet] 231C12 [Packet size limited during capture] 231
C2 Packet Details Messages 232C21 [Response in frame 123] 232C22 [Request in frame 123] 232C23 [Time from request 0123 seconds] 232C24 [Stream setup by PROTOCOL (frame 123)] 232
D Related command line tools 234D1 Introduction 234D2 tshark Terminal-based Wireshark 235D3 tcpdump Capturing with tcpdump for viewing with Wireshark 236D4 dumpcap Capturing with dumpcap for viewing with Wireshark 237D5 capinfos Print information about capture files 238D6 editcap Edit capture files 239D7 mergecap Merging multiple capture files into one 242D8 text2pcap Converting ASCII hexdumps to network captures 245D9 idl2wrs Creating dissectors from CORBA IDL files 248
D91 What is it 248D92 Why do this 248
Wireshark Users Guide
vii
D93 How to use idl2wrs 248D94 TODO 249D95 Limitations 250D96 Notes 250
E This Documents License (GPL) 252
Wireshark Users Guide
viii
Preface1 Foreword
Wireshark is one of those programs that many network managers would love to be able to use butthey are often prevented from getting what they would like from Wireshark because of the lack ofdocumentation
This document is part of an effort by the Wireshark team to improve the usability of Wireshark
We hope that you find it useful and look forward to your comments
ix
2 Who should read this documentThe intended audience of this book is anyone using Wireshark
This book will explain all the basics and also some of the advanced features that Wiresharkprovides As Wireshark has become a very complex program since the early days not every featureof Wireshark may be explained in this book
This book is not intended to explain network sniffing in general and it will not provide details aboutspecific network protocols A lot of useful information regarding these topics can be found at theWireshark Wiki at httpwikiwiresharkorg
By reading this book you will learn how to install Wireshark how to use the basic elements of thegraphical user interface (such as the menu) and whats behind some of the advanced features that arenot always obvious at first sight It will hopefully guide you around some common problems thatfrequently appear for new (and sometimes even advanced) users of Wireshark
Preface
x
3 AcknowledgementsThe authors would like to thank the whole Wireshark team for their assistance In particular the au-thors would like to thank
bull Gerald Combs for initiating the Wireshark project and funding to do this documentation
bull Guy Harris for many helpful hints and a great deal of patience in reviewing this document
bull 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 docu-ment
bull Pat Eyler for his suggestions on improving the example on generating a backtrace
bull Martin Regner for his various suggestions and corrections
bull Graeme Hewson for a lot of grammatical corrections
The authors would like to acknowledge those man page and README authors for the Wiresharkproject from who sections of this document borrow heavily
bull Scott Renfro from whose mergecap man page Section D7 ldquomergecap Merging multiple cap-ture files into one rdquo is derived
bull Ashok Narayanan from whose text2pcap man page Section D8 ldquotext2pcap Converting ASCIIhexdumps to network captures rdquo is derived
bull Frank Singleton from whose READMEidl2wrs Section D9 ldquoidl2wrs Creating dissectorsfrom CORBA IDL files rdquo is derived
Preface
xi
4 About this documentThis book was originally developed by Richard Sharpe with funds provided from the WiresharkFund It was updated by Ed Warnicke and more recently redesigned and updated by Ulf Lamping
It is written in DocBookXML
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 Wireshark
Preface
xii
5 Where to get the latest copy of thisdocument
The latest copy of this documentation can always be found at http wwwwiresharkorg docsusersguide
Preface
xiii
6 Providing feedback about this documentShould you have any feedback about this document please send it to the authors through wireshark-dev[AT]wiresharkorg
Preface
xiv
Preface
xv
Chapter 1 Introduction11 What is Wireshark
Wireshark is a network packet analyzer A network packet analyzer will try to capture networkpackets 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 whats goingon inside a network cable just like a voltmeter is used by an electrician to examine whats going oninside 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 ofWireshark all that has changed
Wireshark is perhaps one of the best open source packet analyzers available today
111 Some intended purposesHere are some examples people use Wireshark for
bull network administrators use it to troubleshoot network problems
bull network security engineers use it to examine security problems
bull developers use it to debug protocol implementations
bull people use it to learn network protocol internals
Beside these examples Wireshark can be helpful in many other situations too
112 FeaturesThe following are some of the many features Wireshark provides
bull Available for UNIX and Windows
bull Capture live packet data from a network interface
bull Display packets with very detailed protocol information
bull Open and Save packet data captured
bull Import and Export packet data from and to a lot of other capture programs
bull Filter packets on many criteria
bull Search for packets on many criteria
bull Colorize packet display based on filters
bull Create various statistics
bull and a lot more
However to really appreciate its power you have to start using it
Figure 11 ldquo Wireshark captures packets and allows you to examine their content rdquo shows Wire-shark having captured some packets and waiting for you to examine them
1
Figure 11 Wireshark captures packets and allows you to examine theircontent
113 Live capture from many different network mediaWireshark can capture traffic from many different network media types - and despite its name - in-cluding wireless LAN as well Which media types are supported depends on many things like theoperating system you are using An overview of the supported media types can be found at httpwikiwiresharkorgCaptureSetupNetworkMedia
114 Import files from many other capture programsWireshark can open packets captured from a large number of other capture programs For a list ofinput formats see Section 522 ldquoInput File Formatsrdquo
115 Export files for many other capture programsWireshark can save packets captured in a large number of formats of other capture programs For alist of output formats see Section 532 ldquoOutput File Formatsrdquo
116 Many protocol decodersThere are protocol decoders (or dissectors as they are known in Wireshark) for a great many proto-cols see Appendix B Protocols and Protocol Fields
117 Open Source Software
Introduction
2
Wireshark is an open source software project and is released under the GNU General Public Li-cence (GPL) You can freely use Wireshark on any number of computers you like without worryingabout license keys or fees or such In addition all source code is freely available under the GPL Be-cause of that it is very easy for people to add new protocols to Wireshark either as plugins or builtinto the source and they often do
118 What Wireshark is notHere are some things Wireshark does not provide
bull Wireshark isnt an intrusion detection system It will not warn you when someone does strangethings on your network that heshe isnt allowed to do However if strange things happen Wire-shark might help you figure out what is really going on
bull Wireshark will not manipulate things on the network it will only measure things from itWireshark doesnt send packets on the network or do other active things (except for name resolu-tions but even that can be disabled)
Introduction
3
12 System RequirementsWhat youll need to get Wireshark up and running
121 General Remarks
bull The values below are the minimum requirements and only rules of thumb for use on a moder-ately used network
bull Working with a busy network can easily produce huge memory and disk space usage For ex-ample Capturing on a fully saturated 100MBits Ethernet will produce ~ 750MBytesmin Hav-ing a fast processor lots of memory and disk space is a good idea in that case
bull If Wireshark is running out of memory it crashes see http wikiwiresharkorgKnownBugsOutOfMemory for details and workarounds
bull Wireshark wont benefit much from MultiprocessorHyperthread systems as time consumingtasks like filtering packets are single threaded No rule is without exception during an Updatelist of packets in real time capture capturing traffic runs in one process and dissecting and dis-playing packets runs in another process - which should benefit from two processors
122 Microsoft Windows
bull Windows 2000 XP Home XP Pro XP Tablet PC XP Media Center Server 2003 or Vista (XPPro recommended)
bull 32-bit Pentium or alike (recommended 400MHz or greater) 64-bit processors in WoW64 emu-lation - see remarks below
bull 128MB RAM system memory (recommended 256MBytes or more)
bull 75MB available disk space (plus size of users capture files eg 100MB extra)
bull 800600 (12801024 or higher recommended) resolution with at least 65536 (16bit) colors (256colors should work if Wireshark is installed with the legacy GTK1 selection)
bull A supported network card for capturing
bull Ethernet any card supported by Windows should do
bull WLAN see the MicroLogix support list no capturing of 80211 headers and non-dataframes
bull Other media See httpwikiwiresharkorgCaptureSetupNetworkMedia
Remarks
bull Older Windows versions are no longer supported because of three reasons None of the de-velopers actively use those systems any longer which makes support difficult The librariesWireshark depends on (GTK WinPCap ) are also dropping support for these systems Mi-crosoft also dropped support for these systems
bull Windows 95 98 and ME will no longer work with Wireshark The last known version to workwas Ethereal 0990 (which includes WinPcap 31) You can get it from http etherealcomdownloadhtml According to this bug report you may need to install Ethereal 0100 on somesystems BTW Microsoft no longer supports 98ME since July 11 2006
Introduction
4
bull Windows NT 40 will no longer work with Wireshark The last known version to work wasWireshark 0994 (which includes WinPcap 31) you still can get it from http prdown-loadssourceforgenetwiresharkwireshark-setup-0994exe BTW Microsoft no longer supportsNT 40 since December 31 2005
bull Windows CE and the embedded (NTXP) versions are not supported
bull 64-bit processors run Wireshark in 32 bit emulation (called WoW64) at least WinPcap 40 is re-quired for that
bull Multi monitor setups are supported but may behave a bit strangely
123 Unix LinuxWireshark currently runs on most UNIX platforms The system requirements should be comparableto the Windows values listed above
Binary packages are available for at least the following platforms
bull Apple Mac OS X
bull Debian GNULinux
bull FreeBSD
bull Gentoo Linux
bull HP-UX
bull Mandriva Linux
bull NetBSD
bull OpenPKG
bull Red Hat FedoraEnterprise Linux
bull rPath Linux
bull Sun Solarisi386
bull Sun SolarisSparc
If a binary package is not available for your platform you should download the source and try tobuild it Please report your experiences to wireshark-dev[AT]wiresharkorg
Introduction
5
13 Where to get WiresharkYou can get the latest copy of the program from the Wireshark website ht-tpwwwwiresharkorgdownloadhtml The website allows you to choose from among several mir-rors for downloading
A new Wireshark version will typically become available every 4-8 months
If you want to be notified about new Wireshark releases you should subscribe to the wireshark-an-nounce mailing list You will find more details in Section 164 ldquoMailing Listsrdquo
Introduction
6
14 A brief history of WiresharkIn late 1997 Gerald Combs needed a tool for tracking down networking problems and wanted tolearn more about networking so he started writing Ethereal (the former name of the Wiresharkproject) as a way to solve both problems
Ethereal was initially released after several pauses in development in July 1998 as version 020Within days patches bug reports and words of encouragement started arriving so Ethereal was onits 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 tcpviewso he started applying patches and contributing dissectors to Ethereal
In late 1998 Richard Sharpe who was giving TCPIP courses saw its potential on such coursesand started looking at it to see if it supported the protocols he needed While it didnt at that pointnew 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 allof them started with a protocol that they needed that Ethereal did not already handle So they copiedan existing dissector and contributed the code back to the team
In 2006 the project moved house and re-emerged under a new name Wireshark
Introduction
7
15 Development and maintenance ofWireshark
Wireshark was initially developed by Gerald Combs Ongoing development and maintenance ofWireshark is handled by the Wireshark team a loose group of individuals who fix bugs and providenew functionality
There have also been a large number of people who have contributed protocol dissectors to Wire-shark and it is expected that this will continue You can find a list of the people who have contrib-uted code to Wireshark by checking the about dialog box of Wireshark or at the authors page on theWireshark web site
Wireshark is an open source software project and is released under the GNU General Public Li-cence (GPL) All source code is freely available under the GPL You are welcome to modify Wire-shark to suit your own needs and it would be appreciated if you contribute your improvements backto the Wireshark team
You gain three benefits by contributing your improvements back to the community
bull Other people who find your contributions useful will appreciate them and you will know thatyou have helped people in the same way that the developers of Wireshark have helped people
bull The developers of Wireshark might improve your changes even more as theres always room forimprovement Or they may implement some advanced things on top of your code which can beuseful for yourself too
bull The maintainers and developers of Wireshark will maintain your code as well fixing it whenAPI changes or other changes are made and generally keeping it in tune with what is happeningwith Wireshark So if Wireshark is updated (which is done often) you can get a new Wiresharkversion 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 downloadpage of the Wireshark website httpwwwwiresharkorgdownloadhtml
Introduction
8
16 Reporting problems and getting helpIf you have problems or need help with Wireshark there are several places that may be of interestto you (well besides this guide of course)
161 WebsiteYou will find lots of useful information on the Wireshark homepage at httpwwwwiresharkorg
162 WikiThe Wireshark Wiki at httpwikiwiresharkorg provides a wide range of information related toWireshark and packet capturing in general You will find a lot of information not part of this usersguide For example there is an explanation how to capture on a switched network an ongoing effortto 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 net-work protocol you know well) you can edit the wiki pages by simply using your web browser
163 FAQThe 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 willoften answer the question(s) you might have This will save yourself and others a lot oftime (keep in mind that a lot of people are subscribed to the mailing lists)
You will find the FAQ inside Wireshark by clicking the menu item HelpContents and selecting theFAQ page in the dialog shown
An online version is available at the Wireshark website httpwwwwiresharkorgfaqhtml Youmight prefer this online version as its typically more up to date and the HTML format is easier touse
164 Mailing ListsThere are several mailing lists of specific Wireshark topics available
wireshark-announce This mailing list will inform you about new program releases whichusually appear about every 4-8 weeks
wireshark-users This list is for users of Wireshark People post questions about build-ing and using Wireshark others (hopefully) provide answers
wireshark-dev This list is for Wireshark developers If you want to start developing aprotocol dissector join this list
You can subscribe to each of these lists from the Wireshark web site httpwwwwiresharkorgSimply select the mailing lists link on the left hand side of the site The lists are archived at theWireshark web site as well
Tip
You can search in the list archives to see if someone asked the same question sometime before and maybe already got an answer That way you dont have to wait untilsomeone answers your question
Introduction
9
165 Reporting Problems
Note
Before reporting any problems please make sure you have installed the latest versionof Wireshark
When reporting problems with Wireshark it is helpful if you supply the following information
1 The version number of Wireshark and the dependent libraries linked with it eg GTK+ etcYou can obtain this with the command wireshark -v
2 Information about the platform you run Wireshark on
3 A detailed description of your problem
4 If you get an errorwarning message copy the text of that message (and also a few lines beforeand after it if there are some) so others may find the place where things go wrong Please dontgive something like I get a warning while doing x as this wont give a good idea where tolook at
Dont send large files
Do not send large files (gt100KB) to the mailing lists just place a note that further datais available on request Large files will only annoy a lot of people on the list who arenot interested in your specific problem If required you will be asked for further databy the persons who really can help you
Dont send confidential information
If you send captured data to the mailing lists be sure they dont contain any sensitiveor confidential information like passwords or such
166 Reporting Crashes on UNIXLinux platformsWhen reporting crashes with Wireshark 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
$ gdb `whereis wireshark | cut -f2 -d | cut -d -f2` core gtamp bttxtbacktrace^D$
Note
Type the characters in the first line verbatim Those are back-tics there
Note
backtrace is a gdb command You should enter it verbatim after the first line shownabove but it will not be echoed The ^D (Control-D that is press the Control key and
Introduction
10
the D key together) will cause gdb to exit This will leave you with a file calledbttxt in the current directory Include the file with your bug report
Note
If you do not have gdb available you will have to check out your operating systemsdebugger
You should mail the traceback to the wireshark-dev[AT]wiresharkorg mailing list
167 Reporting Crashes on Windows platformsThe Windows distributions dont contain the symbol files (pdb) because they are very large Forthis reason its not possible to create a meaningful backtrace file from it You should report yourcrash just like other problems using the mechanism described above
Introduction
11
Introduction
12
Chapter 2 Building and InstallingWireshark21 Introduction
As with all things there must be a beginning and so it is with Wireshark To use Wireshark youmust
bull Obtain a binary package for your operating system or
bull Obtain the source and build Wireshark for your operating system
Currently only two or three Linux distributions ship Wireshark and they are commonly shipping anout-of-date version No other versions of UNIX ship Wireshark so far and Microsoft does not shipit with any version of Windows For that reason you will need to know where to get the latest ver-sion of Wireshark and how to install it
This chapter shows you how to obtain source and binary packages and how to build Wiresharkfrom source should you choose to do so
The following are the general steps you would use
1 Download the relevant package for your needs eg source or binary distribution
2 Build the source into a binary if you have downloaded the source
This may involve building andor installing other necessary packages
3 Install the binaries into their final destinations
13
22 Obtaining the source and binarydistributions
You can obtain both source and binary distributions from the Wireshark web site ht-tpwwwwiresharkorg Simply select the download link and then select either the source packageor binary package of your choice from the mirror site closest to you
Download all required files
In general unless you have already downloaded Wireshark before you will mostlikely need to download several source packages if you are building Wireshark fromsource 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 Wireshark web siteyou might not find one for your platform and they often tend to be several versionsbehind the current released version as they are contributed by people who have theplatforms they are built for
For this reason you might want to pull down the source distribution and build it as theprocess is relatively simple
Building and Installing Wireshark
14
23 Before you build Wireshark under UNIXBefore you build Wireshark from sources or install a binary package you must ensure that youhave the following other packages installed
bull GTK+ The GIMP Tool Kit
You will also need Glib Both can be obtained from wwwgtkorg
bull libpcap the packet capture software that Wireshark uses
You can obtain libpcap from wwwtcpdumporg
Depending on your system you may be able to install these from binaries eg RPMs or you mayneed to obtain them in source code form and build them
If you have downloaded the source for GTK+ the instructions shown in Example 21 ldquoBuildingGTK+ from sourcerdquo may provide some help in building it
Example 21 Building GTK+ from source
gzip -dc gtk+-1210targz | tar xvf -ltmuch output removedgtcd gtk+-1210configureltmuch output removedgtmakeltmuch output removedgtmake installltmuch output removedgt
Note
You may need to change the version number of gtk+ in Example 21 ldquoBuilding GTK+from sourcerdquo to match the version of GTK+ you have downloaded The directory youchange to will change if the version of GTK+ changes and in all cases tar xvf - willshow 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+-1210targzIt is also possible to use gunzip -c or gzcat rather than gzip -dc on many UNIX sys-tems
Note
If you downloaded gtk+ or any other tar file using Windows you may find your filecalled gtk+-1_2_8_targz
You should consult the GTK+ web site if any errors occur in carrying out the instructions in Ex-ample 21 ldquoBuilding GTK+ from sourcerdquo
If you have downloaded the source to libpcap the general instructions shown in Example 22ldquoBuilding and installing libpcaprdquo will assist in building it Also if your operating system does notsupport tcpdump you might also want to download it from the tcpdump web site and install it
Building and Installing Wireshark
15
Example 22 Building and installing libpcap
gzip -dc libpcap-094tarZ | tar xvf -ltmuch output removedgtcd libpcap-094configureltmuch output removedgtmakeltmuch output removedgtmake installltmuch output removedgt
Note
The directory you should change to will depend on the version of libpcap you havedownloaded In all cases tar xvf - will show you the name of the directory that hasbeen unpacked
Under Red Hat 6x and beyond (and distributions based on it like Mandrake) you can simply installeach 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 Thecommands shown in Example 23 ldquo Installing required RPMs under Red Hat Linux 62 and beyondrdquo will install all the needed RPMs if they are not already installed
Example 23 Installing required RPMs under Red Hat Linux 62 and beyond
cd mntcdromRedHatRPMSrpm -ivh glib-126-3i386rpmrpm -ivh glib-devel-126-3i386rpmrpm -ivh gtk+-126-7i386rpmrpm -ivh gtk+-devel-126-7i386rpmrpm -ivh libpcap-04-19i386rpm
Note
If you are using a version of Red Hat later than 62 the required RPMs have mostlikely changed Simply use the correct RPMs from your distribution
Under Debian you can install Wireshark using aptitude aptitude will handle any dependency issuesfor you Example 24 ldquoInstalling debs under Debianrdquo shows how to do this
Example 24 Installing debs under Debian
aptitude install wireshark-dev
Building and Installing Wireshark
16
24 Building Wireshark from source underUNIX
Use the following general steps if you are building Wireshark from source under a UNIX operatingsystem
1 Unpack the source from its gzipd tar file If you are using Linux or your version of UNIXuses GNU tar you can use the following command
tar zxvf wireshark-0997-targz
For other versions of UNIX you will want to use the following commands
gzip -d wireshark-0997-targztar xvf wireshark-0997-tar
Note
The pipeline gzip -dc wireshark-0997-targz | tar xvf - will work here as well
Note
If you have downloaded the Wireshark tarball under Windows you may find thatyour browser has created a file with underscores rather than periods in its filename
2 Change directory to the Wireshark source directory
3 Configure your source so it will build correctly for your version of UNIX You can do this withthe following command
configure
If this step fails you will have to rectify the problems and rerun configure Troubleshootinghints are provided in Section 26 ldquoTroubleshooting during the install on Unixrdquo
4 Build the sources into a binary with the make command For example
make
5 Install the software in its final destination using the command
make install
Once you have installed Wireshark with make install above you should be able to run it by enter-ing wireshark
Building and Installing Wireshark
17
25 Installing the binaries under UNIXIn general installing the binary under your version of UNIX will be specific to the installation meth-ods used with your version of UNIX For example under AIX you would use smit to install theWireshark binary package while under Tru64 UNIX (formerly Digital UNIX) you would use setld
251 Installing from rpms under Red Hat and alikeUse the following command to install the Wireshark RPM that you have downloaded from theWireshark web site
rpm -ivh wireshark-0997i386rpm
If the above step fails because of missing dependencies install the dependencies first and then retrythe step above See Example 23 ldquo Installing required RPMs under Red Hat Linux 62 and beyond rdquofor information on what RPMs you will need to have installed
252 Installing from debs under DebianUse the following command to install Wireshark under Debian
aptitude install wireshark
aptitude should take care of all of the dependency issues for you
253 Installing from portage under Gentoo LinuxUse the following command to install Wireshark under Gentoo Linux with all of the extra features
USE=adns gtk ipv6 portaudio snmp ssl kerberos threads selinux emerge wireshark
254 Installing from packages under FreeBSDUse the following command to install Wireshark under FreeBSD
pkg_add -r wireshark
pkg_add should take care of all of the dependency issues for you
Building and Installing Wireshark
18
26 Troubleshooting during the install onUnix
A number of errors can occur during the installation process Some hints on solving these areprovided here
If the configure stage fails you will need to find out why You can check the file configlog inthe source directory to find out what failed The last few lines of this file should help in determiningthe problem
The standard problems are that you do not have GTK+ on your system or you do not have a recentenough version of GTK+ The configure will also fail if you do not have libpcap (at least the re-quired include files) on your system
Another common problem is for the final compile and link stage to terminate with a complaint ofOutput too long This is likely to be caused by an antiquated sed (such as the one shipped with Sol-aris) Since sed is used by the libtool script to construct the final link command this leads to mys-terious problems This can be resolved by downloading a recent version of sed from http direct-oryfsforgGNUsedhtml
If you cannot determine what the problems are send mail to the wireshark-dev mailing list explain-ing your problem and including the output from configlog and anything else you think is rel-evant like a trace of the make stage
Building and Installing Wireshark
19
27 Building from source under WindowsIt is recommended to use the binary installer for Windows until you want to start developing Wire-shark on the Windows platform
For further information how to build Wireshark for Windows from the sources have a look at theDevelopment Wiki httpwikiwiresharkorgDevelopment for the latest available developmentdocumentation
Building and Installing Wireshark
20
28 Installing Wireshark under WindowsIn this section we explore installing Wireshark under Windows from the binary packages
281 Install WiresharkYou may acquire a binary installer of Wireshark named something like wireshark-setup-xyzexe The Wireshark installer includes WinPcap so you dont need to downloadand install two separate packages
Simply download the Wireshark installer from httpwwwwiresharkorgdownloadhtmlreleasesand execute it Beside the usual installer options like where to install the program there are severaloptional components
Tip Just keep the defaults
If you are unsure which settings to select just keep the defaults
2811 Choose Components page
Wireshark (both Wireshark GTK1 and 2 user interfaces cannot be installed at the same time)
bull Wireshark GTK1 - Wireshark is a GUI network protocol analyzer
bull Wireshark GTK2 - Wireshark is a GUI network protocol analyzer (using the modern GTK2GUI toolkit recommended)
bull GTK MS Windows Engine - GTK MS Windows Engine (native Win32 look and feel recom-mended)
TShark - TShark is a command-line based network protocol analyzer
You may try the GTK1 selection if you experience any GUI problems with GTK2 eg Windowswith only 256 (8bit) color displays wont work well with GTK2 However the older GTK1 user in-terface doesnt provide some advanced analyze and statistics features
Plugins Extensions (for the Wireshark and TShark dissection engines)
bull Dissector Plugins - Plugins with some extended dissections
bull Tree Statistics Plugins - Plugins with some extended statistics
bull Mate - Meta Analysis and Tracing Engine (experimental) - user configurable extension(s) ofthe display filter engine see httpwikiwiresharkorgMate for details
bull SNMP MIBs - SNMP MIBs for a more detailed SNMP dissection
Tools (additional commnand line tools to work with capture files)
bull Editcap - Editcap is a program that reads a capture file and writes some or all of the packets intoanother capture file
bull Text2Pcap - Text2pcap is a program that reads in an ASCII hex dump and writes the data into alibpcap-style capture file
bull Mergecap - Mergecap is a program that combines multiple saved capture files into a single out-put file
Building and Installing Wireshark
21
bull Capinfos - Capinfos is a program that provides information on capture files
Users Guide - Local installation of the Users Guide The Help buttons on most dialogs will requirean internet connection to show help pages if the Users Guide is not installed locally
2812 Additional Tasks page
bull Start Menu Shortcuts - add some start menu shortcuts
bull Desktop Icon - add a Wireshark icon to the desktop
bull Quick Launch Icon - add a Wireshark icon to the Explorer quick launch toolbar
bull Associate file extensions to Wireshark - Associate standard network trace files to Wireshark
2813 Install WinPcap page
The Wireshark installer contains the latest released WinPcap installer
If you dont have WinPcap installed you wont be able to capture live network traffic but you willstill be able to open saved capture files
bull Currently installed WinPcap version - the Wireshark installer detects the currently installedWinPcap version
bull Install WinPcap xx - if the currently installed version is older than the one which comes withthe Wireshark installer (or WinPcap is not installed at all) this will be selected by default
bull Start WinPcap service NPF at startup - so users without administrative privileges can cap-ture
More WinPcap info
bull Wireshark related httpwikiwiresharkorgWinPcap
bull General WinPcap info httpwwwwinpcaporg
2814 Command line options
You can simply start the Wireshark installer without any command line parameters it will show youthe usual interactive installer
For special cases there are some command line parameters available
bull NCRC disables the CRC check
bull S runs the installer or uninstaller silently with default values Please note The silent installerwont install WinPCap
bull desktopicon installation of the desktop icon =yes - force installation =no - dont install other-wise use defaults user settings This option can be useful for a silent installer
bull quicklaunchicon installation of the quick launch icon =yes - force installation =no - dont in-
Building and Installing Wireshark
22
stall otherwise use defaults user settings
bull D sets the default installation directory ($INSTDIR) overriding InstallDir and InstallDir-RegKey It must be the last parameter used in the command line and must not contain anyquotes even if the path contains spaces
Example
wireshark-setup-0997exe NCRC S desktopicon=yesquicklaunchicon=no D=CProgram FilesFoo
282 Manual WinPcap Installation
Note
As mentioned above the Wireshark installer takes care of the installation of Win-Pcap so usually you dont have to worry about WinPcap at all
The following is only necessary if you want to try a different version than the one included in theWireshark installer eg because a new WinPcap (beta) version was released
Additional WinPcap versions (including newer alpha or beta releases) can be downloaded from thefollowing locations
bull The main WinPcap site httpwwwwinpcaporg
bull The Wiretappednet mirror httpwwwmirrorswiretappednetsecuritypacket-capturewinpcap
At the download page you will find a single installer exe called something like auto-installerwhich can be installed under various Windows systems including NT402000XPVista
283 Update WiresharkFrom time to time you may want to update your installed Wireshark to a more recent version If youjoin Wiresharks announce mailing list you will be informed about new Wireshark versions seeSection 164 ldquoMailing Listsrdquo for details how to subscribe to this list
New versions of Wireshark usually become available every 4 to 8 months Updating Wireshark isdone the same way as installing it you simply download and start the installer exe A reboot is usu-ally not required and all your personal settings remain unchanged
284 Update WinPcapNew versions of WinPcap are less frequently available maybe only once in a year You will findWinPcap update instructions where you can download new WinPcap versions Usually you have toreboot the machine after installing a new WinPcap version
Warning
If you have an older version of WinPcap installed you must uninstall it before in-stalling the current version Recent versions of the WinPcap installer will take care ofthis
285 Uninstall Wireshark
Building and Installing Wireshark
23
You can uninstall Wireshark the usual way using the Add or Remove Programs option inside theControl Panel Select the Wireshark entry to start the uninstallation procedure
The Wireshark uninstaller will provide several options as to which things are to be uninstalled thedefault is to remove the core components but keep the personal settings WinPcap and alike
WinPcap wont be uninstalled by default as other programs than Wireshark may use it as well
286 Uninstall WinPcapYou can uninstall WinPcap independently of Wireshark using the WinPcap entry in the Add orRemove Programs of the Control Panel
Note
After uninstallation of WinPcap you cant capture anything with Wireshark
It might be a good idea to reboot Windows afterwards
Building and Installing Wireshark
24
Building and Installing Wireshark
25
Chapter 3 User Interface31 Introduction
By now you have installed Wireshark and are most likely keen to get started capturing your firstpackets In the next chapters we will explore
bull How the Wireshark user interface works
bull How to capture packets in Wireshark
bull How to view packets in Wireshark
bull How to filter packets in Wireshark
bull and many other things
26
32 Start WiresharkYou can start Wireshark from your shell or window manager
Tip
When starting Wireshark its possible to specify optional settings using the commandline See Section 92 ldquoStart Wireshark from the command linerdquo for details
Note
In the following chapters a lot of screenshots from Wireshark will be shown As Wire-shark runs on many different platforms and there are different versions of the underly-ing GUI toolkit (GTK 1x 2x) used your screen might look different from theprovided screenshots But as there are no real differences in functionality thesescreenshots should still be well understandable
User Interface
27
33 The Main windowLets look at Wiresharks user interface Figure 31 ldquoThe Main windowrdquo shows Wireshark as youwould usually see it after some packets are captured or loaded (how to do this will be describedlater)
Figure 31 The Main window
Wiresharks main window consists of parts that are commonly known from many other GUI pro-grams
1 The menu (see Section 34 ldquoThe Menurdquo) is used to start actions
2 The main toolbar (see Section 313 ldquoThe Main toolbarrdquo) provides quick access to frequentlyused items from the menu
3 The filter toolbar (see Section 314 ldquoThe Filter toolbarrdquo) provides a way to directly manipu-late the currently used display filter (see Section 63 ldquoFiltering packets while viewingrdquo)
4 The packet list pane (see Section 315 ldquoThe Packet List panerdquo) displays a summary of eachpacket captured By clicking on packets in this pane you control what is displayed in the othertwo panes
5 The packet details pane (see Section 316 ldquoThe Packet Details panerdquo) displays the packet se-lected in the packet list pane in more detail
6 The packet bytes pane (see Section 317 ldquoThe Packet Bytes panerdquo) displays the data from thepacket selected in the packet list pane and highlights the field selected in the packet detailspane
User Interface
28
7 The statusbar (see Section 318 ldquoThe Statusbarrdquo) shows some detailed information about thecurrent program state and the captured data
Tip
The layout of the main window can be customized by changing preference settingsSee Section 95 ldquoPreferencesrdquo for details
331 Main Window NavigationPacket list and detail navigation can be done entirely from the keyboard Table 31 ldquoKeyboard Nav-igationrdquo shows a list of keystrokes that will let you quickly move around a capture file See Ta-ble 35 ldquoGo menu itemsrdquo for additional navigation keystrokes
Table 31 Keyboard Navigation
Accelerator Description
Tab Shift+TabMove between screen elements eg from the toolbars to the packet list to thepacket detail
DownMove to the next packet or detail item
UpMove to the previous packet or detail item
Ctrl+Down F8Move to the next packet even if the packet list isnt focused
Ctrl+Up F7Move to the previous packet even if the packet list isnt focused
LeftIn the packet detail closes the selected tree item If its already closed jumps tothe parent node
RightIn the packet detail opens the selected tree item
Shift+RightIn the packet detail opens the selected tree item and all of its subtrees
Ctrl+RightIn the packet detail opens all tree items
Ctrl+LeftIn the packet detail closes all tree items
BackspaceIn the packet detail jumps to the parent node
Return EnterIn the packet detail toggles the selected tree item
Additionally typing anywhere in the main window will start filling in a display filter
User Interface
29
34 The MenuThe Wireshark menu sits on top of the Wireshark window An example is shown in Figure 32 ldquoTheMenurdquo
Note
Menu items will be greyed out if the corresponding feature isnt available For ex-ample you cannot save a capture file if you didnt capture or load any data before
Figure 32 The Menu
It contains the following items
File This menu contains items to open and merge capture files save print exportcapture files in whole or in part and to quit from Wireshark See Section 35 ldquoTheFile menurdquo
Edit This menu contains items to find a packet time reference or mark one or morepackets set your preferences (cut copy and paste are not presently implemented)See Section 36 ldquoThe Edit menurdquo
View This menu controls the display of the captured data including colorization ofpackets zooming the font showing a packet in a separate window expanding andcollapsing trees in packet details See Section 37 ldquoThe View menurdquo
Go This menu contains items to go to a specific packet See Section 38 ldquoThe Gomenurdquo
Capture This menu allows you to start and stop captures and to edit capture filters See Sec-tion 39 ldquoThe Capture menurdquo
Analyze This menu contains items to manipulate display filters enable or disable the dis-section of protocols configure user specified decodes and follow a TCP streamSee Section 310 ldquoThe Analyze menurdquo
Statistics This menu contains items to display various statistic windows including a sum-mary of the packets that have been captured display protocol hierarchy statisticsand much more See Section 311 ldquoThe Statistics menurdquo
Help This menu contains items to help the user like access to some basic help a list ofthe supported protocols manual pages online access to some of the webpages andthe usual about dialog See Section 312 ldquoThe Help menurdquo
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 keyswhich 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
User Interface
30
35 The File menuThe Wireshark file menu contains the fields shown in Table 32 ldquoFile menu itemsrdquo
Figure 33 The File Menu
Table 32 File menu items
Menu Item Accelerator Description
Open Ctrl+OThis menu item brings up the file open dialog box that allowsyou to load a capture file for viewing It is discussed in moredetail in Section 521 ldquoThe Open Capture File dialogboxrdquo
Open RecentThis menu item shows a submenu containing the recentlyopened capture files Clicking on one of the submenu itemswill open the corresponding capture file directly
MergeThis menu item brings up the merge file dialog box that al-lows you to merge a capture file into the currently loadedone It is discussed in more detail in Section 54 ldquoMergingcapture filesrdquo
Close Ctrl+WThis menu item closes the current capture If you haventsaved the capture you will be asked to do so first (this can bedisabled by a preference setting)
User Interface
31
Menu Item Accelerator Description
------
Save Ctrl+SThis menu item saves the current capture If you have not seta default capture file name (perhaps with the -w ltcapfilegtoption) Wireshark pops up the Save Capture File As dialogbox (which is discussed further in Section 531 ldquoThe SaveCapture File As dialog boxrdquo)
Note
If you have already saved the current capturethis menu item will be greyed out
Note
You cannot save a live capture while it is inprogress You must stop the capture in order tosave
Save As Shift+Ctrl+SThis menu item allows you to save the current capture file towhatever file you would like It pops up the Save CaptureFile As dialog box (which is discussed further in Sec-tion 531 ldquoThe Save Capture File As dialog boxrdquo)
------
File Set gt ListFiles 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 isdiscussed further in Section 55 ldquoFile Setsrdquo)
File Set gt NextFile If the currently loaded file is part of a file set jump to the
next file in the set If it isnt part of a file set or just the lastfile in that set this item is greyed out
File Set gt Pre-vious File If the currently loaded file is part of a file set jump to the
previous file in the set If it isnt part of a file set or just thefirst file in that set this item is greyed out
------
Export gt asPlain Textfile
This menu item allows you to export all (or some) of thepackets in the capture file to a plain ASCII text file It popsup the Wireshark Export dialog box (which is discussed fur-ther in Section 561 ldquoThe Export as Plain Text File dialogboxrdquo)
Export gt asPostScriptfile
This menu item allows you to export all (or some) of thepackets in the capture file to a PostScript file It pops up theWireshark Export dialog box (which is discussed further inSection 562 ldquoThe Export as PostScript File dialog boxrdquo)
Export gt asCSV(Comma Sep-arated Valuespacket sum-mary) file
This menu item allows you to export all (or some) of thepacket summaries in the capture file to a csv file (eg usedby spreadsheet programs) It pops up the Wireshark Exportdialog box (which is discussed further in Section 563 ldquoTheExport as CSV (Comma Separated Values) File dialogboxrdquo)
User Interface
32
Menu Item Accelerator Description
Export gt asPSML file This menu item allows you to export all (or some) of the
packets in the capture file to a PSML (packet summarymarkup language) XML file It pops up the Wireshark Exportdialog box (which is discussed further in Section 564 ldquoTheExport as PSML File dialog boxrdquo)
Export gt asPDML file This menu item allows you to export all (or some) of the
packets in the capture file to a PDML (packet details markuplanguage) XML file It pops up the Wireshark Export dialogbox (which is discussed further in Section 565 ldquoThe Ex-port as PDML File dialog boxrdquo)
Export gt Selec-ted PacketBytes
Ctrl+HThis menu item allows you to export the currently selectedbytes in the packet bytes pane to a binary file It pops up theWireshark Export dialog box (which is discussed further inSection 566 ldquoThe Export selected packet bytes dialogboxrdquo)
------
Print Ctrl+PThis menu item allows you to print all (or some) of the pack-ets in the capture file It pops up the Wireshark Print dialogbox (which is discussed further in Section 57 ldquoPrintingpacketsrdquo)
------
Quit Ctrl+QThis menu item allows you to quit from Wireshark Wire-shark will ask to save your capture file if you havent saved itbefore (this can be disabled by a preference setting)
User Interface
33
36 The Edit menuThe Wireshark Edit menu contains the fields shown in Table 33 ldquoEdit menu itemsrdquo
Figure 34 The Edit Menu
Table 33 Edit menu items
Menu Item Accelerator Description
Copy gt As Fil-ter
Shift+Ctrl+CThis menu item will use the selected item in the detail viewto create a display filter This display filter is then copied tothe clipboard
------
Find Packet Ctrl+FThis menu item brings up a dialog box that allows you to finda packet by many criteria There is further information onfinding packets in Section 67 ldquoFinding packetsrdquo
Find Next Ctrl+NThis menu item tries to find the next packet matching the set-tings from Find Packet
Find Previous Ctrl+BThis menu item tries to find the previous packet matching thesettings from Find Packet
------
Mark Packet(toggle)
Ctrl+MThis menu item marks the currently selected packet See
User Interface
34
Menu Item Accelerator Description
Section 69 ldquoMarking packetsrdquo for details
Find NextMark
Shift+Ctrl+NFind the next marked packet
Find PreviousMark
Shift+Ctrl+BFind the previous marked packet
Mark All Pack-ets This menu item marks all packets
Unmark AllPackets This menu item unmarks all marked packets
------
Set Time Refer-ence (toggle)
Ctrl+TThis menu item set a time reference on the currently selectedpacket See Section 6101 ldquoPacket time referencingrdquo formore information about the time referenced packets
Find Next Ref-erence This menu item tries to find the next time referenced packet
Find PreviousReference This menu item tries to find the previous time referenced
packet
------
Preferences Shift+Ctrl+PThis menu item brings up a dialog box that allows you to setpreferences for many parameters that control Wireshark Youcan also save your preferences so Wireshark will use themthe next time you start it More detail is provided in Sec-tion 95 ldquoPreferencesrdquo
User Interface
35
37 The View menuThe Wireshark View menu contains the fields shown in Table 34 ldquoView menu itemsrdquo
Figure 35 The View Menu
Table 34 View menu items
Menu Item Accelerator Description
Main ToolbarThis menu item hides or shows the main toolbar see Sec-tion 313 ldquoThe Main toolbarrdquo
Filter ToolbarThis menu item hides or shows the filter toolbar see Sec-tion 314 ldquoThe Filter toolbarrdquo
StatusbarThis menu item hides or shows the statusbar see Sec-tion 318 ldquoThe Statusbarrdquo
------
Packet ListThis menu item hides or shows the packet list pane see Sec-tion 315 ldquoThe Packet List panerdquo
Packet DetailsThis menu item hides or shows the packet details pane seeSection 316 ldquoThe Packet Details panerdquo
User Interface
36
Menu Item Accelerator Description
Packet BytesThis menu item hides or shows the packet bytes pane seeSection 317 ldquoThe Packet Bytes panerdquo
------
Time DisplayFormat gt Dateand Time ofDay1970-01-01010203123456
Selecting this tells Wireshark to display the time stamps indate and time of day format see Section 610 ldquoTime displayformats and time referencesrdquo
Note
The fields Time of Day Date and Time ofDay Seconds Since Beginning of CaptureSeconds Since Previous Captured Packet andSeconds Since Previous Displayed Packet aremutually exclusive
Time DisplayFormat gt Timeof Day010203123456
Selecting this tells Wireshark to display time stamps in timeof day format see Section 610 ldquoTime display formats andtime referencesrdquo
Time DisplayFormat gtSeconds SinceBeginning ofCapture123123456
Selecting this tells Wireshark to display time stamps inseconds since beginning of capture format see Section 610ldquoTime display formats and time referencesrdquo
Time DisplayFormat gtSeconds SincePrevious Cap-tured Packet1123456
Selecting this tells Wireshark to display time stamps inseconds since previous captured packet format see Sec-tion 610 ldquoTime display formats and time referencesrdquo
Time DisplayFormat gtSeconds SincePrevious Dis-played Packet1123456
Selecting this tells Wireshark to display time stamps inseconds since previous displayed packet format see Sec-tion 610 ldquoTime display formats and time referencesrdquo
Time DisplayFormat gt ------
Time DisplayFormat gt Auto-matic (FileFormat Preci-sion)
Selecting this tells Wireshark to display time stamps with theprecision given by the capture file format used see Sec-tion 610 ldquoTime display formats and time referencesrdquo
Note
The fields Automatic Seconds andseconds are mutually exclusive
Time DisplayFormat gtSeconds 0
Selecting this tells Wireshark to display time stamps with aprecision of one second see Section 610 ldquoTime displayformats and time referencesrdquo
Time DisplayFormat gt Selecting this tells Wireshark to display time stamps with a
User Interface
37
Menu Item Accelerator Description
seconds 0precision of one second decisecond centisecond milli-second microsecond or nanosecond see Section 610 ldquoTimedisplay formats and time referencesrdquo
Name Resolu-tion gt ResolveName
This item allows you to trigger a name resolve of the currentpacket only see Section 77 ldquoName Resolutionrdquo
Name Resolu-tion gt Enablefor MAC Layer
This item allows you to control whether or not Wiresharktranslates MAC addresses into names see Section 77ldquoName Resolutionrdquo
Name Resolu-tion gt Enablefor NetworkLayer
This item allows you to control whether or not Wiresharktranslates network addresses into names see Section 77ldquoName Resolutionrdquo
Name Resolu-tion gt Enablefor TransportLayer
This item allows you to control whether or not Wiresharktranslates transport addresses into names see Section 77ldquoName Resolutionrdquo
Colorize PacketList This item allows you to control whether or not Wireshark
should colorize the packet list
Note
Enabling colorization will slow down the dis-play of new packets while capturing loadingcapture files
Auto Scroll inLive Capture This item allows you to specify that Wireshark should scroll
the packet list pane as new packets come in so you are al-ways looking at the last packet If you do not specify thisWireshark simply adds new packets onto the end of the listbut 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 AllColumns Resize all column widths so the content will fit into it
Note
Resizing may take a significant amount of timeespecially if a large capture file is loaded
------
Expand Sub-trees This menu item expands the currently selected subtree in the
packet details tree
Expand AllWireshark keeps a list of all the protocol subtrees that are ex-panded and uses it to ensure that the correct subtrees are ex-
User Interface
38
Menu Item Accelerator Description
panded when you display a packet This menu item expandsall subtrees in all packets in the capture
Collapse AllThis menu item collapses the tree view of all packets in thecapture list
------
Coloring Con-veration This menu item brings up a submenu that allows you to color
packets in the packet list pane based on the addresses of thecurrently selected packet This makes it easy to distinguishpackets belonging to different conversations Section 93ldquoPacket colorizationrdquo
Coloring Con-veration gt Col-or 1-10
These menu items enable one of the ten temporary color fil-ters based on the currently selected conversation
Coloring Con-veration gt Re-set coloring
This menu item clears all temporary coloring rules
Coloring Con-veration gt NewColoringRule
This menu item opens a dialog window in which a new per-manent coloring rule can be created based on the currentlyselected conversation
ColoringRules This menu item brings up a dialog box that allows you to col-
or packets in the packet list pane according to filter expres-sions you choose It can be very useful for spotting certaintypes of packets see Section 93 ldquoPacket colorizationrdquo
------
Show Packet inNew Window This menu item brings up the selected packet in a separate
window The separate window shows only the tree view andbyte view panes
Reload Ctrl-RThis menu item allows you to reload the current capture file
User Interface
39
38 The Go menuThe Wireshark Go menu contains the fields shown in Table 35 ldquoGo menu itemsrdquo
Figure 36 The Go Menu
Table 35 Go menu items
Menu Item Accelerator Description
Back Alt+LeftJump to the recently visited packet in the packet historymuch like the page history in a web browser
Forward Alt+RightJump to the next visited packet in the packet history muchlike the page history in a web browser
Go to Packet Ctrl-GBring up a dialog box that allows you to specify a packetnumber and then goes to that packet See Section 68 ldquoGo toa specific packetrdquo for details
Go to Corres-ponding Packet Go to the corresponding packet of the currently selected pro-
tocol field If the selected field doesnt correspond to a pack-et this item is greyed out
------
Previous Pack-et
Ctrl+UpMove to the previous packet in the list This can be used to
User Interface
40
Menu Item Accelerator Description
move to the previous packet even if the packet list doesnthave keyboard focus
Next Packet Ctrl+DownMove to the next packet in the list This can be used to moveto the previous packet even if the packet list doesnt havekeyboard focus
First PacketJump to the first packet of the capture file
Last PacketJump to the last packet of the capture file
User Interface
41
39 The Capture menuThe Wireshark Capture menu contains the fields shown in Table 36 ldquoCapture menu itemsrdquo
Figure 37 The Capture Menu
Table 36 Capture menu items
Menu Item Accelerator Description
InterfacesThis menu item brings up a dialog box that shows whats go-ing on at the network interfaces Wireshark knows of seeSection 44 ldquoThe Capture Interfaces dialog boxrdquo)
Options Ctrl+KThis menu item brings up the Capture Options dialog box(discussed further in Section 45 ldquoThe Capture Optionsdialog boxrdquo) and allows you to start capturing packets
StartImmediately start capturing packets with the same settingsthan the last time
Stop Ctrl+EThis menu item stops the currently running capture see Sec-tion 491 ldquoStop the running capturerdquo)
RestartThis menu item stops the currently running capture and startsagain with the same options this is just for convenience
User Interface
42
Menu Item Accelerator Description
Capture Fil-ters This menu item brings up a dialog box that allows you to cre-
ate and edit capture filters You can name filters and you cansave them for future use More detail on this subject isprovided in Section 66 ldquoDefining and saving filtersrdquo
User Interface
43
310 The Analyze menuThe Wireshark Analyze menu contains the fields shown in Table 37 ldquoAnalyze menu itemsrdquo
Figure 38 The Analyze Menu
Table 37 Analyze menu items
Menu Item Accelerator Description
Display Fil-ters This menu item brings up a dialog box that allows you to cre-
ate and edit display filters You can name filters and you cansave them for future use More detail on this subject isprovided in Section 66 ldquoDefining and saving filtersrdquo
Apply as Filtergt These menu items will change the current display filter and
apply the changed filter immediately Depending on thechosen menu item the current display filter string will be re-placed or appended to by the selected protocol field in thepacket details pane
Prepare a Fil-ter gt These menu items will change the current display filter but
wont apply the changed filter Depending on the chosenmenu item the current display filter string will be replaced orappended to by the selected protocol field in the packet de-tails pane
User Interface
44
Menu Item Accelerator Description
Firewall ACLRules This allows you to create command-line ACL rules for many
different firewall products including Cisco IOS Linux Net-filter (iptables) OpenBSD pf and Windows Firewall (via net-sh) Rules for MAC addresses IPv4 addresses TCP andUDP ports and IPv4+port combinations are supported
It is assumed that the rules will be applied to an outside inter-face
------
Enabled Proto-cols
Shift+Ctrl+RThis menu item allows the user to enabledisable protocoldissectors see Section 941 ldquoThe Enabled Protocols dia-log boxrdquo
Decode AsThis menu item allows the user to force Wireshark to decodecertain packets as a particular protocol see Section 942ldquoUser Specified Decodesrdquo
User SpecifiedDecodes This menu item allows the user to force Wireshark to decode
certain packets as a particular protocol see Section 943ldquoShow User Specified Decodesrdquo
------
Follow TCPStream This menu item brings up a separate window and displays all
the TCP segments captured that are on the same TCP connec-tion as a selected packet see Section 72 ldquoFollowing TCPstreamsrdquo
Follow UDPStream Same functionality as Follow TCP Stream but for UDP
streams
Follow SSLStream Same functionality as Follow TCP Stream but for SSL
streams XXX - how to provide the SSL keys
Expert InfoOpen a dialog showing some expert information about thecaptured packets in a log style display The amount of in-formation will depend on the protocol and varies from verydetailed to none existing This is currently a work in pro-gress XXX - add a new section about this and link from here
Expert InfoComposite Same information as in Expert Info but trying to group
items together for faster analysis
User Interface
45
311 The Statistics menuThe Wireshark Statistics menu contains the fields shown in Table 38 ldquoStatistics menu itemsrdquo
Figure 39 The Statistics Menu
All menu items will bring up a new window showing specific statistical information
Table 38 Statistics menu items
Menu Item Accelerator Description
SummaryShow information about the data captured see Section 82ldquoThe Summary windowrdquo
Protocol Hier-archy Display a hierarchical tree of protocol statistics see Sec-
tion 83 ldquoThe Protocol Hierarchy windowrdquo
ConversationsDisplay a list of conversations (traffic between two end-points) see Section 842 ldquoThe Conversations windowrdquo
EndpointsDisplay a list of endpoints (traffic tofrom an address) seeSection 852 ldquoThe Endpoints windowrdquo
IO GraphsDisplay user specified graphs (eg the number of packets inthe course of time) see Section 86 ldquoThe IO Graphs win-dowrdquo
User Interface
46
Menu Item Accelerator Description
------
ConversationList Display a list of conversations obsoleted by the combined
window of Conversations above see Section 843 ldquoThe pro-tocol specific Conversation List windowsrdquo
Endpoint ListDisplay a list of endpoints obsoleted by the combined win-dow of Endpoints above see Section 853 ldquoThe protocolspecific Endpoint List windowsrdquo
Service Re-sponse Time Display the time between a request and the corresponding re-
sponse see Section 87 ldquoService Response Timerdquo
------
ANSISee Section 88 ldquoThe protocol specific statistics windowsrdquo
GSMSee Section 88 ldquoThe protocol specific statistics windowsrdquo
H225See Section 88 ldquoThe protocol specific statistics windowsrdquo
ISUP MessageTypes See Section 88 ldquoThe protocol specific statistics windowsrdquo
MTP3See Section 88 ldquoThe protocol specific statistics windowsrdquo
RTPSee Section 88 ldquoThe protocol specific statistics windowsrdquo
SCTPSee Section 88 ldquoThe protocol specific statistics windowsrdquo
SIPSee Section 88 ldquoThe protocol specific statistics windowsrdquo
VoIP CallsSee Section 88 ldquoThe protocol specific statistics windowsrdquo
WAP-WSPSee Section 88 ldquoThe protocol specific statistics windowsrdquo
------
BOOTP-DHCPSee Section 88 ldquoThe protocol specific statistics windowsrdquo
HTTPHTTP requestresponse statistics see Section 88 ldquoThe pro-tocol specific statistics windowsrdquo
ISUP MessagesSee Section 88 ldquoThe protocol specific statistics windowsrdquo
ONC-RPC Pro-grams See Section 88 ldquoThe protocol specific statistics windowsrdquo
TCP StreamGraph See Section 88 ldquoThe protocol specific statistics windowsrdquo
User Interface
47
312 The Help menuThe Wireshark Help menu contains the fields shown in Table 39 ldquoHelp menu itemsrdquo
Figure 310 The Help Menu
Table 39 Help menu items
Menu Item Accelerator Description
Contents F1This menu item brings up a basic help system
Supported Pro-tocols This menu item brings up a dialog box showing the suppor-
ted protocols and protocol fields
Manual Pagesgt This menu item starts a Web browser showing one of the loc-
ally installed html manual pages
Wireshark On-line gt This menu item starts a Web browser showing the chosen
webpage from httpwwwwiresharkorg
------
About Wire-shark This menu item brings up an information window that
provides some information on Wireshark such as the plu-gins the used folders
User Interface
48
Note
Calling a Web browser might be unsupported in your version of Wireshark If this isthe case the corresponding menu items will be hidden
Note
If calling a Web browser fails on your machine maybe because just nothing happensor the browser is started but no page is shown have a look at the web browser settingin the preferences dialog
User Interface
49
313 The Main toolbarThe main toolbar provides quick access to frequently used items from the menu This toolbar cannotbe customized by the user but it can be hidden using the View menu if the space on the screen isneeded to show even more packet data
As in the menu only the items useful in the current program state will be available The others willbe greyed out (eg you cannot save a capture file if you havent loaded one)
Figure 311 The Main toolbar
Table 310 Main toolbar items
ToolbarIcon
Toolbar Item CorrespondingMenu Item
Description
Interfaces CaptureInter-faces This item brings up the Capture Interfaces List
dialog box (discussed further in Section 43ldquoStart Capturingrdquo)
Options CaptureOptionsThis item brings up the Capture Options dialogbox (discussed further in Section 43 ldquoStart Cap-turingrdquo) and allows you to start capturing pack-ets
Start CaptureStartThis item starts capturing packets with the op-tions form the last time
Stop CaptureStopThis item stops the currently running live captureprocess Section 43 ldquoStart Capturingrdquo)
Restart CaptureRestartThis item stops the currently running live captureprocess and restarts it again for convenience
------
Open FileOpenThis item brings up the file open dialog box thatallows you to load a capture file for viewing It isdiscussed in more detail in Section 521 ldquoTheOpen Capture File dialog boxrdquo
Save As FileSave AsThis item allows you to save the current capturefile to whatever file you would like It pops upthe Save Capture File As dialog box (which isdiscussed further in Section 531 ldquoThe SaveCapture File As dialog boxrdquo)
Note
If you currently have a temporarycapture file the Save icon
will be shown instead
User Interface
50
ToolbarIcon
Toolbar Item CorrespondingMenu Item
Description
Close FileCloseThis item closes the current capture If you havenot saved the capture you will be asked to save itfirst
Reload ViewReloadThis item allows you to reload the current cap-ture file
Print FilePrintThis item allows you to print all (or some of) thepackets in the capture file It pops up the Wire-shark Print dialog box (which is discussed furtherin Section 57 ldquoPrinting packetsrdquo)
------
Find Packet EditFind PacketThis item brings up a dialog box that allows youto find a packet There is further information onfinding packets in Section 67 ldquoFinding packetsrdquo
Go Back GoGo BackThis item jumps back in the packet history
Go Forward GoGo ForwardThis item jumps forward in the packet history
Go to Packet GoGo to PacketThis item brings up a dialog box that allows youto specify a packet number to go to that packet
Go To FirstPacket
GoFirst PacketThis item jumps to the first packet of the capturefile
Go To Last Pack-et
GoLast PacketThis item jumps to the last packet of the capturefile
------
Colorize ViewColorizeColorize the packet list (or not)
Auto Scroll inLive Capture
ViewAuto Scrollin Live Capture Auto scroll packet list while doing a live capture
(or not)
------
Zoom In ViewZoom InZoom into the packet data (increase the fontsize)
Zoom Out ViewZoom OutZoom out of the packet data (decrease the fontsize)
Normal Size ViewNormal SizeSet zoom level back to 100
Resize Columns ViewResizeColumns Resize columns so the content fits into them
------
Capture Filters CaptureCaptureFilters This item brings up a dialog box that allows you
to create and edit capture filters You can namefilters and you can save them for future use
User Interface
51
ToolbarIcon
Toolbar Item CorrespondingMenu Item
Description
More detail on this subject is provided in Sec-tion 66 ldquoDefining and saving filtersrdquo
Display Filters AnalyzeDisplayFilters This item brings up a dialog box that allows you
to create and edit display filters You can namefilters and you can save them for future useMore detail on this subject is provided in Sec-tion 66 ldquoDefining and saving filtersrdquo
Coloring Rules ViewColoringRules This item brings up a dialog box that allows you
color packets in the packet list pane according tofilter expressions you choose It can be very use-ful for spotting certain types of packets More de-tail on this subject is provided in Section 93ldquoPacket colorizationrdquo
Preferences EditPreferencesThis item brings up a dialog box that allows youto set preferences for many parameters that con-trol Wireshark You can also save your prefer-ences so Wireshark will use them the next timeyou start it More detail is provided in Sec-tion 95 ldquoPreferencesrdquo
------
Help HelpContentsThis item brings up help dialog box
User Interface
52
314 The Filter toolbarThe filter toolbar lets you quickly edit and apply display filters More information on display filtersis available in Section 63 ldquoFiltering packets while viewingrdquo
Figure 312 The Filter toolbar
Table 311 Filter toolbar items
ToolbarIcon
Toolbar Item Description
FilterBrings up the filter construction dialog described in Figure 67 ldquoTheCapture Filters and Display Filters dialog boxesrdquo
Filter inputThe area to enter or edit a display filter string see Section 64ldquoBuilding display filter expressionsrdquo A syntax check of your filterstring is done while you are typing The background will turn red ifyou enter an incomplete or invalid string and will become greenwhen you enter a valid string You can click on the pull down arrowto select a previously-entered filter string from a list The entries inthe pull down list will remain available even after a program restart
Note
After youve changed something in this field dont for-get to press the Apply button (or the EnterReturn key)to apply this filter string to the display
Note
This field is also where the current filter in effect is dis-played
ExpressionThe middle button labeled Add Expression opens a dialog boxthat lets you edit a display filter from a list of protocol fields de-scribed in Section 65 ldquoThe Filter Expression dialog boxrdquo
ClearReset the current display filter and clears the edit area
ApplyApply the current value in the edit area as the new display filter
Note
Applying a display filter on large capture files mighttake quite a long time
User Interface
53
315 The Packet List paneThe packet list pane displays all the packets in the current capture file
Figure 313 The Packet List pane
Each line in the packet list corresponds to one packet in the capture file If you select a line in thispane more details will be displayed in the Packet Details and Packet Bytes panes
While dissecting a packet Wireshark will place information from the protocol dissectors into thecolumns As higher level protocols might overwrite information from lower levels you will typic-ally see the information from the highest possible level only
For example lets look at a packet containing TCP inside IP inside an Ethernet packet The Ethernetdissector will write its data (such as the Ethernet addresses) the IP dissector will overwrite this byits 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 pref-erence settings see Section 95 ldquoPreferencesrdquo
The default columns will show
bull No The number of the packet in the capture file This number wont change even if a displayfilter is used
bull Time The timestamp of the packet The presentation format of this timestamp can be changedsee Section 610 ldquoTime display formats and time referencesrdquo
bull Source The address where this packet is coming from
bull Destination The address where this packet is going to
bull Protocol The protocol name in a short (perhaps abbreviated) version
bull Info Additional information about the packet content
There is a context menu (right mouse click) available see details in Figure 63 ldquoPop-up menu of thePacket List panerdquo
User Interface
54
316 The Packet Details paneThe packet details pane shows the current packet (selected in the Packet List pane) in a more de-tailed form
Figure 314 The Packet Details pane
This pane shows the protocols and protocol fields of the packet selected in the Packet List paneThe protocols and fields of the packet are displayed using a tree which can be expanded and col-lapsed
There is a context menu (right mouse click) available see details in Figure 64 ldquoPop-up menu of thePacket Details panerdquo
Some protocol fields are specially displayed
bull Generated fields Wireshark itself will generate additional protocol fields which are surroundedby brackets The information in these fields is derived from the known context to other packetsin the capture file For example Wireshark is doing a sequenceacknowledge analysis of eachTCP stream which is displayed in the [SEQACK analysis] fields of the TCP protocol
bull Links If Wireshark detected a relationship to another packet in the capture file it will generate alink to that packet Links are underlined and displayed in blue If double-clicked Wiresharkjumps to the corresponding packet
User Interface
55
317 The Packet Bytes paneThe packet bytes pane shows the data of the current packet (selected in the Packet List pane) in ahexdump style
Figure 315 The Packet Bytes pane
As usual for a hexdump the left side shows the offset in the packet data in the middle the packetdata is shown in a hexadecimal representation and on the right the corresponding ASCII characters(or if not appropriate) are displayed
Depending on the packet data sometimes more than one page is available eg when Wireshark hasreassembled some packets into a single chunk of data see Section 76 ldquoPacket Reassemblingrdquo Inthis case there are some additional tabs shown at the bottom of the pane to let you select the pageyou want to see
Figure 316 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 Thiscan be helpful if the size in the pane is too small for all the tab labels
User Interface
56
318 The StatusbarThe statusbar displays informational messages
In general the left side will show context related information while the right side will show the cur-rent number of packets
Figure 317 The initial Statusbar
This statusbar is shown while no capture file is loaded eg when Wireshark is started
Figure 318 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 itwas being captured
The right side shows the current number of packets in the capture file The following values are dis-played
bull P the number of captured packets
bull D the number of packets currently being displayed
bull M the number of marked packets
Figure 319 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 arpopcode) can be used as a displayfilter string representing the selected protocol field
User Interface
57
User Interface
58
Chapter 4 Capturing Live NetworkData41 Introduction
Capturing live network data is one of the major features of Wireshark
The Wireshark capture engine provides the following features
bull Capture from different kinds of network hardware (Ethernet Token Ring ATM )
bull Stop the capture on different triggers like amount of captured data captured time capturednumber of packets
bull Simultaneously show decoded packets while Wireshark keeps on capturing
bull Filter packets reducing the amount of data to be captured see Section 48 ldquoFiltering while cap-turingrdquo
bull Capturing into multiple files while doing a long term capture and in addition the option to forma ringbuffer of these files keeping only the last x files useful for a very long term capture seeSection 46 ldquoCapture files and file modesrdquo
The capture engine still lacks the following features
bull Simultaneous capturing from multiple network interfaces (however you can start multiple in-stances of Wireshark and merge capture files later)
bull Stop capturing (or doing some other action) depending on the captured data
59
42 PrerequisitesSetting up Wireshark to capture packets for the first time can be tricky
Tip
A comprehensive guide How To setup a Capture is available at ht-tpwikiwiresharkorgCaptureSetup
Here are some common pitfalls
bull You need to have root Administrator privileges to start a live capture
bull You need to choose the right network interface to capture packet data from
bull You need to capture at the right place in the network to see the traffic you want to see
bull and a lot more
If you have any problems setting up your capture environment you should have a look at the guidementioned above
Capturing Live Network Data
60
43 Start CapturingOne of the following methods can be used to start capturing packets with Wireshark
bull You can get an overview of the available local interfaces using the Capture Interfaces
dialog box see Figure 41 ldquoThe Capture Interfaces dialog boxrdquo You can start a capture fromthis dialog box using (one of) the Capture button(s)
bull You can start capturing using the Capture Options dialog box see Figure 42 ldquoThe
Capture Options dialog boxrdquo
bull If you have selected the right capture options before you can immediately start a capture usingthe Capture Start menu toolbar item The capture process will start immediately
bull If you already know the name of the capture interface you can start Wireshark from the com-mand line and use the following
wireshark -i eth0 -k
This will start Wireshark capturing on interface eth0 more details can be found at Section 92ldquoStart Wireshark from the command linerdquo
Capturing Live Network Data
61
44 The Capture Interfaces dialog boxWhen you select Interfaces from the Capture menu Wireshark pops up the Capture Interfacesdialog box as shown in Figure 41 ldquoThe Capture Interfaces dialog boxrdquo
Warning
As the Capture Interfaces dialog is showing live captured data it is consuming a lotof system resources Close this dialog as soon as possible to prevent excessive systemload
Note
This dialog box will only show the local interfaces Wireshark knows of As Wiresharkmight not be able to detect all local interfaces and it cannot detect the remote inter-faces available there could be more capture interfaces available than listed
Figure 41 The Capture Interfaces dialog box
Description The interface description provided by the operating system
IP The first IP address Wireshark could resolve from this interface Ifno address could be resolved (eg no DHCP server available) un-known will be displayed If more than one IP address could be re-solved only the first is shown (unpredictable which one in thatcase)
Packets The number of packets captured from this interface since this dia-log was opened Will be greyed out if no packet was captured inthe last second
Packetss Number of packets captured in the last second Will be greyed outif no packet was captured in the last second
Stop Stop a currently running capture
Capture Start a capture on this interface immediately using the settingsfrom the last capture
Options Open the Capture Options dialog with this interface selected seeSection 45 ldquoThe Capture Options dialog boxrdquo
Details (Win32 only) Open a dialog with detailed information about the interface
Close Close this dialog box
Capturing Live Network Data
62
Capturing Live Network Data
63
45 The Capture Options dialog boxWhen you select Start from the Capture menu (or use the corresponding item in the Main tool-bar) Wireshark pops up the Capture Options dialog box as shown in Figure 42 ldquoThe CaptureOptions dialog boxrdquo
Figure 42 The Capture Options dialog box
Tip
If you are unsure which options to choose in this dialog box just try keeping the de-faults as this should work well in many cases
You can set the following fields in this dialog box
451 Capture frame
Interface This field specifies the interface you want to capture on Youcan only capture on one interface and you can only captureon interfaces that Wireshark has found on the system It is a
Capturing Live Network Data
64
drop-down list so simply click on the button on the righthand side and select the interface you want It defaults to thefirst non-loopback interface that supports capturing and ifthere are none the first loopback interface On some systemsloopback interfaces cannot be used for capturing (loopbackinterfaces are not available on Windows platforms)
This field performs the same function as the -i ltinterfacegtcommand line option
IP address The IP address(es) of the selected interface If no addresscould be resolved from the system unknown will be shown
Link-layer header type Unless you are in the rare situation that you need this justkeep the default For a detailed description see Section 47ldquoLink-layer header typerdquo
Buffer size n megabyte(s) Enter the buffer size to be used while capturing This is thesize of the kernel buffer which will keep the captured packetsuntil they are written to disk If you encounter packet dropstry increasing this value
Note
This option is only available on Windows plat-forms
Capture packets in promiscuousmode
This checkbox allows you to specify that Wireshark shouldput the interface in promiscuous mode when capturing If youdo not specify this Wireshark will only capture the packetsgoing to or from your computer (not all packets on your LANsegment)
Note
If some other process has put the interface inpromiscuous mode you may be capturing inpromiscuous mode even if you turn off this op-tion
Note
Even in promiscuous mode you still wont ne-cessarily see all packets on your LAN segmentsee http wwwwiresharkorgfaqhtmlpromiscsniff for some more explana-tions
Limit each packet to n bytes This field allows you to specify the maximum amount of datathat will be captured for each packet and is sometimes re-ferred to as the snaplen If disabled the default is 65535which will be sufficient for most protocols Some rules ofthumb
bull If you are unsure just keep the default value
bull If you dont need all of the data in a packet - for exampleif you only need the link-layer IP and TCP headers - youmight want to choose a small snapshot length as less
Capturing Live Network Data
65
CPU time is required for copying packets less bufferspace is required for packets and thus perhaps fewerpackets will be dropped if traffic is very heavy
bull If you dont capture all of the data in a packet you mightfind that the packet data you want is in the part thatsdropped or that reassembly isnt possible as the data re-quired for reassembly is missing
Capture Filter This field allows you to specify a capture filter Capture fil-ters are discussed in more details in Section 48 ldquoFilteringwhile capturingrdquo It defaults to empty or no filter
You can also click on the button labelled Capture Filter andWireshark will bring up the Capture Filters dialog box and al-low you to create andor select a filter Please see Section 66ldquoDefining and saving filtersrdquo
452 Capture File(s) frameAn explanation about capture file usage can be found in Section 46 ldquoCapture files and file modesrdquo
File This field allows you to specify the file name that will beused for the capture file This field is left blank by default Ifthe field is left blank the capture data will be stored in a tem-porary file see Section 46 ldquoCapture files and file modesrdquo fordetails
You can also click on the button to the right of this field tobrowse through the filesystem
Use multiple files Instead of using a single file Wireshark will automaticallyswitch 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 givennumber of byte(s)kilobyte(s)megabyte(s)gigabyte(s) havebeen captured
Next file every n minute(s) Multiple files only Switch to the next file after the givennumber of second(s)minutes(s)hours(s)days(s) haveelapsed
Ring buffer with n files Multiple files only Form a ring buffer of the capture fileswith the given number of files
Stop capture after n file(s) Multiple files only Stop capturing after switching to the nextfile the given number of times
453 Stop Capture frame
after n packet(s) Stop capturing after the given number of packets have beencaptured
after n megabytes(s) Stop capturing after the given number ofbyte(s)kilobyte(s)megabyte(s)gigabyte(s) have been cap-tured This option is greyed out if Use multiple files is se-lected
Capturing Live Network Data
66
after n minute(s) Stop capturing after the given number ofsecond(s)minutes(s)hours(s)days(s) have elapsed
454 Display Options frame
Update list of packets in real time This option allows you to specify that Wireshark should up-date the packet list pane in real time If you do not specifythis Wireshark does not display any packets until you stopthe capture When you check this Wireshark captures in aseparate process and feeds the captures to the display process
Automatic scrolling in live cap-ture
This option allows you to specify that Wireshark should scrollthe packet list pane as new packets come in so you are al-ways looking at the last packet If you do not specify thisWireshark simply adds new packets onto the end of the listbut does not scroll the packet list pane This option is greyedout if Update list of packets in real time is disabled
Hide capture info dialog If this option is checked the capture info dialog described inSection 49 ldquoWhile a Capture is running rdquo will be hidden
455 Name Resolution frame
Enable MAC name resolution This option allows you to control whether or not Wiresharktranslates MAC addresses into names see Section 77 ldquoNameResolutionrdquo
Enable network name resolution This option allows you to control whether or not Wiresharktranslates network addresses into names see Section 77ldquoName Resolutionrdquo
Enable transport name resolu-tion
This option allows you to control whether or not Wiresharktranslates transport addresses into protocols see Section 77ldquoName Resolutionrdquo
456 ButtonsOnce you have set the values you desire and have selected the options you need simply click onStart to commence the capture or Cancel to cancel the capture
If you start a capture Wireshark allows you to stop capturing when you have enough packets cap-tured for details see Section 49 ldquoWhile a Capture is running rdquo
Capturing Live Network Data
67
46 Capture files and file modesWhile capturing the underlying libpcap capturing engine will grab the packets from the networkcard and keep the packet data in a (relatively) small kernel buffer This data is read by Wiresharkand 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 MBs) can be quite slow If you plan to do a longterm capture or capturing from a high traffic network think about using one of theMultiple files options This will spread the captured packets over several smallerfiles which can be much more pleasant to work with
Note
Using Multiple files may cut context related information Wireshark keeps context in-formation of the loaded packet data so it can report context related problems (like astream error) and keeps information about context related protocols (eg where data isexchanged at the establishing phase and only referred to in later packets) As it keepsthis information only for the loaded file using one of the multiple file modes may cutthese contexts If the establishing phase is saved in one file and the things you wouldlike to see is in another you might not see some of the valuable context related inform-ation
Tip
Information about the folders used for the capture file(s) can be found in Appendix AFiles and Folders
Table 41 Capture file mode selected by capture options
File option Use multiplefiles option
Ring bufferwith n files op-tion
Mode Resulting file-name(s) used
- - - Single temporaryfile
etherXXXXXX(where XXXXXX isa unique number)
foocap - - Single named file foocap
foocap x - Multiple filescontinuous
foo_00001_20040205110102capfoo_00002_20040205110102cap
foocap x x Multiple filesring buffer
foo_00001_20040205110102capfoo_00002_20040205110102cap
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 un-der a user specified name
Capturing Live Network Data
68
Single named file A single capture file will be used If you want to place thenew capture file to a specific folder choose this mode
Multiple files continuous Like the Single named file mode but a new file is createdand used after reaching one of the multiple file switch condi-tions (one of the Next file every values)
Multiple files ring buffer Much like Multiple files continuous reaching one of themultiple files switch conditions (one of the Next file every values) will switch to the next file This will be a newlycreated file if value of Ring buffer with n files is notreached otherwise it will replace the oldest of the formerlyused files (thus forming a ring)
This mode will limit the maximum disk usage even for anunlimited amount of capture input data keeping the latestcaptured data
Capturing Live Network Data
69
47 Link-layer header typeIn the usual case you wont have to choose this link-layer header type The following paragraphsdescribe the exceptional cases where selecting this type is possible so you will have a guide ofwhat to do
If you are capturing on an 80211 device on some versions of BSD this might offer a choice of Eth-ernet or 80211 Ethernet will cause the captured packets to have fake Ethernet headers80211 will cause them to have IEEE 80211 headers Unless the capture needs to be read by anapplication that doesnt support 80211 headers you should select 80211
If you are capturing on an Endace DAG card connected to a synchronous serial line this might offera choice of PPP over serial or Cisco HDLC if the protocol on the serial line is PPP select PPPover 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 achoice of RFC 1483 IP-over-ATM or Sun raw ATM If the only traffic being captured is RFC1483 LLC-encapsulated IP or if the capture needs to be read by an application that doesnt supportSunATM 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 Ifyou are capturing traffic from a Cisco Cable Modem Termination System that is putting DOCSIStraffic onto the Ethernet to be captured select DOCSIS otherwise select Ethernet
Capturing Live Network Data
70
48 Filtering while capturingWireshark uses the libpcap filter language for capture filters This is explained in the tcpdump manpage which can be hard to understand so its explained here to some extent
Tip
You will find a lot of Capture Filter examples at ht-tpwikiwiresharkorgCaptureFilters
You enter the capture filter into the Filter field of the Wireshark Capture Options dialog box asshown in Figure 42 ldquoThe Capture Options dialog boxrdquo The following is an outline of the syntaxof the tcpdump capture filter language See the expression option at the tcpdump manual page fordetails httpwwwtcpdumporgtcpdump_manhtml
A capture filter takes the form of a series of primitive expressions connected by conjunctions (andor) and optionally preceded by not
[not] primitive [and|or [not] primitive ]
An example is shown in Example 41 ldquo A capture filter for telnet that captures traffic to and from aparticular host rdquo
Example 41 A capture filter for telnet that captures traffic to and from aparticular host
tcp port 23 and host 10005
This example captures telnet traffic to and from the host 10005 and shows how to use two primit-ives and the and conjunction Another example is shown in Example 42 ldquo Capturing all telnettraffic not from 10005rdquo and shows how to capture all telnet traffic except that from 10005
Example 42 Capturing all telnet traffic not from 10005
tcp port 23 and not src host 10005
XXX - add examples to the following list
A primitive is simply one of the following
[src|dst] host lthostgt This primitive allows you to filter on a host IP address orname You can optionally precede the primitive with thekeyword src|dst to specify that you are only interested insource or destination addresses If these are not present pack-ets where the specified address appears as either the source orthe destination address will be selected
ether [src|dst] host ltehostgt This primitive allows you to filter on Ethernet host addressesYou can optionally include the keyword src|dst between thekeywords ether and host to specify that you are only inter-ested in source or destination addresses If these are not
Capturing Live Network Data
71
present packets where the specified address appears in eitherthe source or destination address will be selected
gateway host lthostgt This primitive allows you to filter on packets that used hostas a gateway That is where the Ethernet source or destina-tion was host but neither the source nor destination IP addresswas host
[src|dst] net ltnetgt [maskltmaskgt|len ltlengt]
This primitive allows you to filter on network numbers Youcan optionally precede this primitive with the keywordsrc|dst to specify that you are only interested in a source ordestination network If neither of these are present packetswill be selected that have the specified network in either thesource or destination address In addition you can specifyeither the netmask or the CIDR prefix for the network if theyare different from your own
[tcp|udp] [src|dst] port ltportgt This primitive allows you to filter on TCP and UDP portnumbers You can optionally precede this primitive with thekeywords src|dst and tcp|udp which allow you to specify thatyou are only interested in source or destination ports and TCPor UDP packets respectively The keywords tcp|udp must ap-pear before src|dst
If these are not specified packets will be selected for both theTCP and UDP protocols and when the specified address ap-pears in either the source or destination port field
less|greater ltlengthgt This primitive allows you to filter on packets whose lengthwas less than or equal to the specified length or greater thanor equal to the specified length respectively
ip|ether proto ltprotocolgt This primitive allows you to filter on the specified protocol ateither the Ethernet layer or the IP layer
ether|ip broadcast|multicast This primitive allows you to filter on either Ethernet or IPbroadcasts or multicasts
ltexprgt relop ltexprgt This primitive allows you to create complex filter expressionsthat select bytes or ranges of bytes in packets Please see thetcpdump man page at http wwwtcpdumporg tcp-dump_manhtml for more details
481 Automatic Remote Traffic FilteringIf Wireshark is running remotely (using eg SSH an exported X11 window a terminal server )the remote content has to be transported over the network adding a lot of (usually unimportant)packets to the actually interesting traffic
To avoid this Wireshark tries to figure out if its remotely connected (by looking at some specificenvironment variables) and automatically creates a capture filter that matches aspects of the connec-tion
The following environment variables are analyzed
SSH_CONNECTION (ssh) ltremote IPgt ltremote portgt ltlocal IPgt ltlocal portgt
SSH_CLIENT (ssh) ltremote IPgt ltremote portgt ltlocal portgt
REMOTEHOST (tcsh others) ltremote namegt
Capturing Live Network Data
72
DISPLAY (x11) [remote name]ltdisplay numgt
SESSIONNAME (terminal server) ltremote namegt
Capturing Live Network Data
73
49 While a Capture is running While a capture is running the following dialog box is shown
Figure 43 The Capture Info dialog box
This dialog box will inform you about the number of captured packets and the time since the capturewas started The selection of which protocols are counted cannot be changed
Tip
This Capture Info dialog box can be hidden using the Hide capture info dialog op-tion in the Capture Options dialog box
491 Stop the running captureA running capture session will be stopped in one of the following ways
1 Using the Stop button from the Capture Info dialog box
Capturing Live Network Data
74
Note
The Capture Info dialog box might be hidden if the option Hide capture infodialog is used
2 Using the menu item Capture Stop
3 Using the toolbar item Stop
4 Pressing the accelerator keys Ctrl+E
5 The capture will be automatically stopped if one of the Stop Conditions is exceeded eg themaximum amount of data was captured
492 Restart a running captureA running capture session can be restarted with the same capture options as the last time this willremove all packets previously captured This can be useful if some uninteresting packets are cap-tured and theres no need to keep them
Restart is a convenience function and equivalent to a capture stop following by an immediate cap-ture start A restart can be triggered in one of the following ways
1 Using the menu item Capture Restart
2 Using the toolbar item Restart
Capturing Live Network Data
75
Capturing Live Network Data
76
Chapter 5 File Input Output andPrinting51 Introduction
This chapter will describe input and output of capture data
bull OpenImport capture files in various capture file formats
bull SaveExport capture files in various capture file formats
bull Merge capture files together
bull Print packets
77
52 Open capture filesWireshark can read in previously saved capture files To read them simply select the menu or tool-bar item File Open Wireshark will then pop up the File Open dialog box which is dis-
cussed in more detail in Section 521 ldquoThe Open Capture File dialog boxrdquo
Its convenient to use drag-and-drop
to open a file by simply dragging the desired file from your file manager and drop-ping it onto Wiresharks main window However drag-and-drop is not availablewontwork in all desktop environments
If you didnt save the current capture file before you will be asked to do so to prevent data loss (thisbehaviour can be disabled in the preferences)
In addition to its native file format (libpcap format also used by tcpdumpWinDump and other libp-capWinPcap-based programs) Wireshark can read capture files from a large number of other pack-et capture programs as well See Section 522 ldquoInput File Formatsrdquo for the list of capture formatsWireshark understands
521 The Open Capture File dialog boxThe Open Capture File dialog box allows you to search for a capture file containing previouslycaptured packets for display in Wireshark Table 51 ldquoThe system specific Open Capture File dia-log boxrdquo shows some examples of the Wireshark Open File Dialog box
The dialog appearance depends on your system
The appearance of this dialog depends on the system and GTK+ toolkit version usedHowever the functionality remains basically the same on any particular system
Common dialog behaviour on all systems
bull Select files and directories
bull Click the OpenOk button to accept your selected file and open it
bull Click the Cancel button to go back to Wireshark and not load a capture file
Wireshark extensions to the standard behaviour of these dialogs
bull View file preview information (like the filesize the number of packets ) if youve selected acapture file
bull Specify a display filter with the Filter button and filter field This filter will be used whenopening the new file The text field background becomes green for a valid filter string and redfor an invalid one Clicking on the Filter button causes Wireshark to pop up the Filters dialogbox (which is discussed further in Section 63 ldquoFiltering packets while viewingrdquo)
XXX - we need a better description of these read filters
bull Specify which name resolution is to be performed for all packets by clicking on one of the name resolution check buttons Details about name resolution can be found in Section 77ldquoName Resolutionrdquo
File Input Output and Printing
78
Save a lot of time loading huge capture files
You can change the display filter and name resolution settings later while viewing thepackets However loading huge capture files can take a significant amount of extratime if these settings are changed later so in such situations it can be a good idea to setat least the filter in advance here
Table 51 The system specific Open Capture File dialog box
Figure 51 Open on nativeWindows
Microsoft Windows (GTK2 installed)
This is the common Windows file open dialog -plus some Wireshark extensions
Specific for this dialog
bull If available the Help button will lead youto this section of this Users Guide
bull XXX - the Filter button currently doesntwork on Windows
bull XXX - missing feature If Wireshark doesntrecognize the selected file as a capture file itshould grey out the Open button
Figure 52 Open - new GTKversion
UnixLinux GTK version gt= 24
This is the common GimpGNOME file opendialog - plus some Wireshark extensions
Specific for this dialog
bull The + Add button allows you to add a dir-ectory selected in the right-hand pane to thefavorites list on the left Those changes arepersistent
bull The - Remove button allows you to removea selected directory from that list again (theitems like Home Desktop and Filesys-tem cannot be removed)
bull If Wireshark doesnt recognize the selectedfile as a capture file it will grey out theOpen button
UnixLinux GTK version lt 24 Microsoft
File Input Output and Printing
79
Figure 53 Open - old GTK version
Windows (GTK1 installed)
This is the file open dialog of former GimpGNOME versions - plus some Wireshark exten-sions
Specific for this dialog
bull If Wireshark doesnt recognize the selectedfile as a capture file it will grey out the Okbutton
522 Input File FormatsThe following file formats from other capture tools can be opened by Wireshark
bull libpcap tcpdump and various other tools using tcpdumps capture format
bull Sun snoop and atmsnoop
bull ShomitiFinisar Surveyor captures
bull Novell LANalyzer captures
bull Microsoft Network Monitor captures
bull AIXs iptrace captures
bull Cinco Networks NetXray captures
bull Network Associates Windows-based Sniffer and Sniffer Pro captures
bull Network GeneralNetwork Associates DOS-based Sniffer (compressed or uncompressed) cap-tures
bull AG GroupWildPackets EtherPeekTokenPeekAiroPeekEtherHelpPacketGrabber captures
bull RADCOMs WANLAN Analyzer captures
bull Network Instruments Observer version 9 captures
bull LucentAscend router debug output
bull HP-UXs nettl
bull Toshibas ISDN routers dump output
bull ISDN4BSD i4btrace utility
bull traces from the EyeSDN USB S0
bull IPLog format from the Cisco Secure Intrusion Detection System
bull pppd logs (pppdump format)
File Input Output and Printing
80
bull the output from VMSs TCPIPtraceTCPtraceUCX$TRACE utilities
bull the text output from the DBS Etherwatch VMS utility
bull Visual Networks Visual UpTime traffic capture
bull the output from CoSine L2 debug
bull the output from Accellents 5Views LAN agents
bull Endace Measurement Systems ERF format captures
bull Linux Bluez Bluetooth stack hcidump -w traces
bull Catapult DCT2000 out files
Opening a file may fail due to invalid packet types
It may not be possible to read some formats dependent on the packet types capturedEthernet captures are usually supported for most file formats but other packet types(eg token ring packets) may not be possible to read from all file formats
File Input Output and Printing
81
53 Saving captured packetsYou can save captured packets simply by using the Save As menu item from the File menu underWireshark You can choose which packets to save and which file format to be used
Saving may reduce the available information
Saving the captured packets will slightly reduce the amount of information eg thenumber of dropped packets will be lost see Section A1 ldquoCapture Filesrdquo for details
531 The Save Capture File As dialog boxThe Save Capture File As dialog box allows you to save the current capture to a file Table 52ldquoThe system specific Save Capture File As dialog boxrdquo shows some examples of this dialog box
The dialog appearance depends on your system
The appearance of this dialog depends on the system and GTK+ toolkit version usedHowever the functionality remains basically the same on any particular system
Table 52 The system specific Save Capture File As dialog box
Figure 54 Save on native Windows
Microsoft Windows (GTK2 installed)
This is the common Windows file save dialog -plus some Wireshark extensions
Specific for this dialog
bull If available the Help button will lead youto this section of this Users Guide
bull If you dont provide a file extension to the fi-lename - eg pcap Wireshark will appendthe standard file extension for that fileformat
Figure 55 Save - new GTK version
UnixLinux GTK version gt= 24
This is the common GimpGNOME file savedialog - plus some Wireshark extensions
Specific for this dialog
bull Clicking on the + at Browse for otherfolders will allow you to browse files andfolders in your file system
File Input Output and Printing
82
Figure 56 Save - old GTK version
UnixLinux GTK version lt 24 MicrosoftWindows (GTK1 installed)
This is the file save dialog of former GimpGNOME versions - plus some Wireshark exten-sions
With this dialog box you can perform the following actions
1 Type in the name of the file you wish to save the captured packets in as a standard file name inyour file system
2 Select the directory to save the file into
File Input Output and Printing
83
3 Select the range of the packets to be saved see Section 58 ldquoThe Packet Range framerdquo
4 Specify the format of the saved capture file by clicking on the File type drop down box Youcan choose from the types described in Section 532 ldquoOutput File Formatsrdquo
The selection of capture formats may be reduced
Some capture formats may not be available depending on the packet types cap-tured
File formats can be converted
You can convert capture files from one format to another by reading in a capturefile and writing it out using a different format
5 Click on the SaveOk button to accept your selected file and save to it If Wireshark has a prob-lem saving the captured packets to the file you specified it will display an error dialog boxAfter clicking OK on that error dialog box you can try again
6 Click on the Cancel button to go back to Wireshark and not save the captured packets
532 Output File FormatsWireshark can save the packet data in its native file format (libpcap) and in the file formats ofsome other protocol analyzers so other tools can read the capture data
File formats have different time stamp accuracies
Saving from the currently used file format to a different format may reduce the timestamp accuracy see the Section 74 ldquoTime Stampsrdquo for details
The following file formats can be saved by Wireshark (with the known file extensions)
bull libpcap tcpdump and various other tools using tcpdumps capture format (pcapcapdmp)
bull Accellent 5Views (5vw)
bull HP-UXs nettl (TRC0TRC1)
bull Microsoft Network Monitor - NetMon (cap)
bull Network Associates Sniffer - DOS (capenctrcfdcsyc)
bull Network Associates Sniffer - Windows (cap)
bull Network Instruments Observer version 9 (bfr)
bull Novell LANalyzer (tr1)
bull Sun snoop (snoopcap)
bull Visual Networks Visual UpTime traffic ()
If the above tools will be more helpful than Wireshark is a different question -)
File Input Output and Printing
84
Third party protocol analyzers may require specific fileextensions
Other protocol analyzers than Wireshark may require that the file has a certain file ex-tension in order to read the files you generate with Wireshark eg
cap for Network Associates Sniffer - Windows
File Input Output and Printing
85
54 Merging capture filesSometimes you need to merge several capture files into one For example this can be useful if youhave captured simultaneously from multiple interfaces at once (eg using multiple instances ofWireshark)
Merging capture files can be done in three ways
bull Use the menu item Merge from the File menu to open the merge dialog see Section 541ldquoThe Merge with Capture File dialog boxrdquo This menu item will be disabled until you haveloaded a capture file
bull Use drag-and-drop to drop multiple files on the main window Wireshark will try to merge thepackets in chronological order from the dropped files into a newly created temporary file If youdrop only a single file it will simply replace a (maybe) existing one
bull Use the mergecap tool which is a command line tool to merge capture files This tool providesthe most options to merge capture files see Section D7 ldquomergecap Merging multiple capturefiles into one rdquo
541 The Merge with Capture File dialog boxThis dialog box let you select a file to be merged into the currently loaded file
You will be prompted for an unsaved file first
If your current data wasnt saved before you will be asked to save it first before thisdialog box is shown
Most controls of this dialog will work the same way as described in the Open Capture File dialogbox see Section 521 ldquoThe Open Capture File dialog boxrdquo
Specific controls of this merge dialog are
Prepend packets to existing file Prepend the packets from the selected file before the currentlyloaded packets
Merge packets chronologically Merge both the packets from the selected and currentlyloaded file in chronological order
Append packets to existing file Append the packets from the selected file after the currentlyloaded packets
Table 53 The system specific Merge Capture File As dialog box
Figure 57 Merge on nativeWindows
Microsoft Windows (GTK2 installed)
This is the common Windows file open dialog -plus some Wireshark extensions
File Input Output and Printing
86
Figure 58 Merge - new GTKversion
UnixLinux GTK version gt= 24
This is the common GimpGNOME file opendialog - plus some Wireshark extensions
Figure 59 Merge - old GTKversion
UnixLinux GTK version lt 24 MicrosoftWindows (GTK1 installed)
This is the file open dialog of former GimpGNOME versions - plus some Wireshark exten-sions
File Input Output and Printing
87
55 File SetsWhen using the Multiple Files option while doing a capture (see Section 46 ldquoCapture files andfile modesrdquo) the capture data is spread over several capture files called a file set
As it can become tedious to work with a file set by hand Wireshark provides some features tohandle these file sets in a convenient way
How does Wireshark detect the files of a file set
A filename in a file set uses the format Prefix_Number_DateTimeSuffix which might looklike this test_00001_20060420183910pcap All files of a file set share the same prefix(eg test) and suffix (eg pcap) and a varying middle part
To find the files of a file set Wireshark scans the directory where the currently loaded fileresides and scans for files matching the filename pattern (prefix and suffix) of the currentlyloaded file
This simple mechanism usually works well but has its drawbacks If several file sets werecaptured with the same prefix and suffix Wireshark will detect them as a single file set Iffiles were renamed or spread over several directories the mechanism will fail to find all filesof a set
The following features in the File Set submenu of the File menu are available to work with filesets in a convenient way
bull The List Files dialog box will list the files Wireshark has recognized as being part of the currentfile set
bull Next File closes the current and opens the next file in the file set
bull Previous File closes the current and opens the previous file in the file set
551 The List Files dialog box
Figure 510 The List Files dialog box
File Input Output and Printing
88
Each line contains information about a file of the file set
bull Filename the name of the file If you click on the filename (or the radio button left to it) thecurrent file will be closed and the corresponding capture file will be opened
bull Created the creation time of the file
bull Last Modified the last time the file was modified
bull 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 setcan be found
The content of this dialog box is updated each time a capture file is openedclosed
The Close button will well close the dialog box
File Input Output and Printing
89
56 Exporting dataWireshark provides several ways and formats to export packet data This section describes generalways to export data from Wireshark
Note
There are more specialized functions to export specific data which will be described atthe appropriate places
XXX - add detailed descriptions of the output formats and some sample output too
561 The Export as Plain Text File dialog boxExport packet data into a plain ASCII text file much like the format used to print packets
Figure 511 The Export as Plain Text File dialog box
bull Export to file frame chooses the file to export the packet data to
bull The Packet Range frame is described in Section 58 ldquoThe Packet Range framerdquo
bull The Packet Details frame is described in Section 59 ldquoThe Packet Format framerdquo
562 The Export as PostScript File dialog boxExport packet data into PostScript much like the format used to print packets
File Input Output and Printing
90
Tip
You can easily convert PostScript files to PDF files using ghostscript For exampleexport to a file named foops and then call ps2pdf foops
Figure 512 The Export as PostScript File dialog box
bull Export to file frame chooses the file to export the packet data to
bull The Packet Range frame is described in Section 58 ldquoThe Packet Range framerdquo
bull The Packet Details frame is described in Section 59 ldquoThe Packet Format framerdquo
563 The Export as CSV (Comma Separated Values)File dialog box
XXX - add screenshot
Export packet summary into CSV used eg by spreadsheet programs to im-export data
bull Export to file frame chooses the file to export the packet data to
bull The Packet Range frame is described in Section 58 ldquoThe Packet Range framerdquo
564 The Export as PSML File dialog box
File Input Output and Printing
91
Export packet data into PSML This is an XML based format including only the packet summaryThe PSML file specification is available at httpwwwnbeeorgDocsNetPDLPSMLhtm
Figure 513 The Export as PSML File dialog box
bull Export to file frame chooses the file to export the packet data to
bull The Packet Range frame is described in Section 58 ldquoThe Packet Range framerdquo
Theres no such thing as a packet details frame for PSML export as the packet format is defined bythe PSML specification
565 The Export as PDML File dialog boxExport packet data into PDML This is an XML based format including the packet details ThePDML file specification is available at httpwwwnbeeorgDocsNetPDLPDMLhtm
The PDML specification is not officially released and Wiresharks implementation of itis still in an early beta state so please expect changes in future Wireshark versions
Figure 514 The Export as PDML File dialog box
File Input Output and Printing
92
bull Export to file frame chooses the file to export the packet data to
bull The Packet Range frame is described in Section 58 ldquoThe Packet Range framerdquo
Theres no such thing as a packet details frame for PDML export as the packet format is defined bythe PDML specification
566 The Export selected packet bytes dialog boxExport the bytes selected in the Packet Bytes pane into a raw binary file
Figure 515 The Export Selected Packet Bytes dialog box
File Input Output and Printing
93
bull Name the filename to export the packet data to
bull The Save in folder field lets you select the folder to save to (from some predefined folders)
bull Browse for other folders provides a flexible way to choose a folder
567 The Export Objects dialog boxThis feature scans through HTTP streams in the currently open capture file or running capture andtakes reassembled objects such as HTML documents image files executables and anything else thatcan be transferred over HTTP and lets you save them to disk If you have a capture running this listis automatically updated every few seconds with any new objects seen The saved objects can thenbe opened with the proper viewer or executed in the case of executables (if it is for the same plat-form you are running Wireshark on) without any further work on your part This feature is not avail-able in the GTK1 build of Wireshark or when using GTK2 versions below 24
Figure 516 The Export Objects dialog box
File Input Output and Printing
94
Columns
bull Packet num The packet number in which this object was found In some cases there can bemultiple objects in the same packet
bull Hostname The hostname of the server that sent the object as a response to an HTTP request
bull Content Type The HTTP content type of this object
bull Bytes The size of this object in bytes
bull Filename The final part of the URI (after the last slash) This is typically a filename but maybe a long complex looking string which typically indicates that the file was received in responseto a HTTP POST request
Buttons
bull Help Opens this section in the users guide
bull Close Closes this dialog
bull Save As Saves the currently selected object as a filename you specify The default filename tosave as is taken from the filename column of the objects list
bull Save All Saves all objects in the list using the filename from the filename column You will beasked what directory folder to save them in If the filename is invalid for the operating system file system you are running Wireshark on then an error will appear and that object will not besaved (but all of the others will be)
File Input Output and Printing
95
57 Printing packetsTo print packets select the Print menu item from the File menu When you do this Wiresharkpops up the Print dialog box as shown in Figure 517 ldquoThe Print dialog boxrdquo
571 The Print dialog box
Figure 517 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
bull Plain Text specifies that the packet print should be in plain text
bull PostScript specifies that the packet print process should use PostScript togenerate a better print output on PostScript aware printers
bull Output to file specifies that printing be done to a file using the filenameentered in the field or selected with the browse button
This field is where you enter the file to print to if you have selected Printto a file or you can click the button to browse the filesystem It is greyedout if Print to a file is not selected
bull Print command specifies that a command be used for printing
File Input Output and Printing
96
Note
These Print command fields are not available on windowsplatforms
This field specifies the command to use for printing It is typically lprYou would change it to specify a particular queue if you need to print to aqueue 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 Section 58 ldquoThe Packet Range framerdquo
Packet Format Select the output format of the packets to be printed You can choose howeach packet is printed see Figure 519 ldquoThe Packet Format framerdquo
File Input Output and Printing
97
58 The Packet Range frameThe packet range frame is a part of various output related dialog boxes It provides options to selectwhich packets should be processed by the output function
Figure 518 The Packet Range frame
If the Captured button is set (default) all packets from the selected rule will be processed If theDisplayed button is set only the currently displayed packets are taken into account to the selectedrule
bull All packets will process all packets
bull Selected packet only process only the selected packet
bull Marked packets only process only the marked packets
bull From first to last marked packet process the packets from the first to the last marked one
bull Specify a packet range process a user specified range of packets eg specifying 510-1520-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
File Input Output and Printing
98
59 The Packet Format frameThe packet format frame is a part of various output related dialog boxes It provides options to selectwhich parts of a packet should be used for the output function
Figure 519 The Packet Format frame
bull Packet summary line enable the output of the summary line just as in the Packet List pane
bull Packet details enable the output of the packet details tree
bull All collapsed the info from the Packet Details pane in all collapsed state
bull As displayed the info from the Packet Details pane in the current state
bull All expanded the info from the Packet Details pane in all expanded state
bull Packet bytes enable the output of the packet bytes just as in the Packet Bytes pane
bull Each packet on a new page put each packet on a separate page (eg when savingprinting to atext file this will put a form feed character between the packets)
File Input Output and Printing
99
File Input Output and Printing
100
Chapter 6 Working with capturedpackets61 Viewing packets you have captured
Once you have captured some packets or you have opened a previously saved capture file you canview the packets that are displayed in the packet list pane by simply clicking on a packet in thepacket 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 mayvary) to the left of that part of the payload and you can select individual fields by clicking on themin the tree view pane An example with a TCP packet selected is shown in Figure 61 ldquoWiresharkwith a TCP packet selected for viewingrdquo It also has the Acknowledgment number in the TCP head-er selected which shows up in the byte view as the selected bytes
Figure 61 Wireshark with a TCP packet selected for viewing
You can also select and view packets the same way while Wireshark is capturing if you selectedUpdate list of packets in real time in the Wireshark Capture Preferences dialog box
In addition you can view individual packets in a separate window as shown in Figure 62 ldquoViewinga packet in a separate windowrdquo Do this by selecting the packet in which you are interested in thepacket list pane and then select Show Packet in New Windows from the Display menu This al-lows you to easily compare two or even more packets
101
Figure 62 Viewing a packet in a separate window
Working with captured packets
102
62 Pop-up menusYou can bring up a pop-up menu over either the Packet List Packet Details or Packet Bytespane by clicking your right mouse button at the corresponding pane
621 Pop-up menu of the Packet List pane
Figure 63 Pop-up menu of the Packet List pane
The following table gives an overview of which functions are available in this pane where to findthe corresponding function in the main menu and a short description of each item
Table 61 The menu items of the Packet List pop-up menu
Item Identical to mainmenus item
Description
Mark Packet(toggle)
EditMarkunmark a packet
Set Time Refer-ence (toggle)
EditSetreset a time reference
-----
Apply as Filter AnalyzePrepare and apply a display filter based on the currently se-lected item
Prepare a Filter AnalyzePrepare a display filter based on the currently selecteditem
Conversation Fil- -This menu item applies a display filter with the address in-
Working with captured packets
103
Item Identical to mainmenus item
Description
terformation from the selected packet Eg the IP menu entrywill set a filter to show the traffic between the two IP ad-dresses of the current packet XXX - add a new section de-scribing this better
Colorize Conver-sation
-This menu item uses a display filter with the address in-formation from the selected packet to build a new coloriz-ing rule
SCTP -XXX - add an explanation of this
Follow TCPStream
AnalyzeAllows you to view all the data on a TCP stream between apair of nodes
Follow SSLStream
AnalyzeSame as Follow TCP Stream but for SSL XXX - add anew section describing this better
-----
Copy Summary(Text)
-Copy the summary fields as displayed to the clipboard astab-separated text
Copy Summary(CSV)
-Copy the summary fields as displayed to the clipboard ascomma-separated text
Copy As FilterPrepare a display filter based on the currently selected itemand copy that filter to the clipboard
Copy Bytes(Offset Hex Text)
-Copy the packet bytes to the clipboard in hexdump-likeformat
Copy Bytes(Offset Hex)
-Copy the packet bytes to the clipboard in hexdump-likeformat but without the text portion
Copy Bytes(Printable TextOnly)
-Copy the packet bytes to the clipboard as ASCII text ex-cluding non-printable characters
Copy Bytes (HexStream)
-Copy the packet bytes to the clipboard as an unpunctuatedlist of hex digits
Copy Bytes(Binary Stream)
-Copy the packet bytes to the clipboard as raw binary Thedata is stored in the clipboard as MIME-type applicationoct-et-stream
This option is not available in versions of Wireshark builtusing GTK+ 1x
Export SelectedPacket Bytes
FileThis menu item is the same as the File menu item of thesame name It allows you to export raw packet bytes to abinary file
-----
Decode As AnalyzeChange or apply a new relation between two dissectors
Print FilePrint packets
Working with captured packets
104
Item Identical to mainmenus item
Description
Show Packet inNew Window
ViewDisplay the selected packet in a new window
622 Pop-up menu of the Packet Details pane
Figure 64 Pop-up menu of the Packet Details pane
The following table gives an overview of which functions are available in this pane where to findthe corresponding function in the main menu and a short description of each item
Table 62 The menu items of the Packet Details pop-up menu
Item Identical to mainmenus item
Description
Expand Subtrees ViewExpand the currently selected subtree
Expand All ViewExpand all subtrees in all packets in the capture
Collapse All ViewWireshark keeps a list of all the protocol subtrees that areexpanded and uses it to ensure that the correct subtrees areexpanded when you display a packet This menu item col-lapses the tree view of all packets in the capture list
Working with captured packets
105
Item Identical to mainmenus item
Description
-----
Copy Descrip-tion
-Copy the displayed text of the selected field to the systemclipboard
Copy As Filter EditPrepare a display filter based on the currently selected itemand copy it to the clipboard
Copy Bytes(Offset Hex Text)
-Copy the packet bytes to the clipboard in hexdump-likeformat similar to the Packet List Pane command but cop-ies only the bytes relevant to the selected part of the tree(the bytes selected in the Packet Bytes Pane)
Copy Bytes(Offset Hex)
-Copy the packet bytes to the clipboard in hexdump-likeformat but without the text portion similar to the PacketList Pane command but copies only the bytes relevant tothe selected part of the tree (the bytes selected in the PacketBytes Pane)
Copy Bytes(Printable TextOnly)
-Copy the packet bytes to the clipboard as ASCII text ex-cluding non-printable characters similar to the Packet ListPane command but copies only the bytes relevant to theselected part of the tree (the bytes selected in the PacketBytes Pane)
Copy Bytes (HexStream)
-Copy the packet bytes to the clipboard as an unpunctuatedlist of hex digits similar to the Packet List Pane commandbut copies only the bytes relevant to the selected part of thetree (the bytes selected in the Packet Bytes Pane)
Copy Bytes(Binary Stream)
-Copy the packet bytes to the clipboard as raw binary simil-ar to the Packet List Pane command but copies only thebytes relevant to the selected part of the tree (the bytes se-lected in the Packet Bytes Pane) The data is stored in theclipboard as MIME-type applicationoctet-stream
This option is not available in versions of Wireshark builtusing GTK+ 1x
Export SelectedPacket Bytes
FileThis menu item is the same as the File menu item of thesame name It allows you to export raw packet bytes to abinary file
-----
Apply as Filter AnalyzePrepare and apply a display filter based on the currently se-lected item
Prepare a Filter AnalyzePrepare a display filter based on the currently selecteditem
Colorize with Fil-ter
-Prepare a display filter based on the currently selected itemand use it to prepare a new colorize rule
Follow TCPStream
AnalyzeAllows you to view all the data on a TCP stream between apair of nodes
Follow SSL Analyze
Working with captured packets
106
Item Identical to mainmenus item
Description
StreamSame as Follow TCP Stream but for SSL XXX - add anew section describing this better
-----
Wiki ProtocolPage
-Show the wiki page corresponding to the currently selectedprotocol in your web browser
Filter Field Ref-erence
-Show the filter field reference web page corresponding tothe currently selected protocol in your web browser
Protocol Prefer-ences
-The menu item takes you to the properties dialog and se-lects the page corresponding to the protocol if there areproperties associated with the highlighted field More in-formation on preferences can be found in Figure 98 ldquoThepreferences dialog boxrdquo
-----
Decode As AnalyzeChange or apply a new relation between two dissectors
Resolve Name ViewCauses a name resolution to be performed for the selectedpacket but NOT every packet in the capture
Go to Corres-ponding Packet
GoIf the selected field has a corresponding packet go to itCorresponding packets will usually be a requestresponsepacket pair or such
Working with captured packets
107
63 Filtering packets while viewingWireshark has two filtering languages One used when capturing packets and one used when dis-playing packets In this section we explore that second type of filter Display filters The first onehas already been dealt with in Section 48 ldquoFiltering while capturingrdquo
Display filters allow you to concentrate on the packets you are interested in while hiding the cur-rently uninteresting ones They allow you to select packets by
bull Protocol
bull The presence of a field
bull The values of fields
bull A comparison between fields
bull and a lot more
To select packets based on protocol type simply type the protocol in which you are interested in theFilter field in the filter toolbar of the Wireshark window and press enter to initiate the filter Fig-ure 65 ldquoFiltering on the TCP protocolrdquo shows an example of what happens when you type tcp inthe filter field
Note
All protocol and field names are entered in lowercase Also dont forget to press enterafter entering the filter expression
Figure 65 Filtering on the TCP protocol
Working with captured packets
108
As you might have noticed only packets of the TCP protocol are displayed now (eg packets 1-10are hidden) The packet numbering will remain as before so the first packet shown is now packetnumber 11
Note
When using a display filter all packets remain in the capture file The display filteronly changes the display of the capture file but not its content
You can filter on any protocol that Wireshark understands You can also filter on any field that adissector adds to the tree view but only if the dissector has added an abbreviation for the field Alist of such fields is available in Wireshark in the Add Expression dialog box You can find moreinformation on the Add Expression dialog box in Section 65 ldquoThe Filter Expression dialogboxrdquo
For example to narrow the packet list pane down to only those packets to or from the IP address19216801 use ipaddr==19216801
Note
To remove the filter click on the Clear button to the right of the filter field
Working with captured packets
109
64 Building display filter expressionsWireshark provides a simple but powerful display filter language that allows you to build quite com-plex filter expressions You can compare values in packets as well as combine expressions into morespecific expressions The following sections provide more information on doing this
Tip
You will find a lot of Display Filter examples at the Wireshark Wiki Display Filterpage at httpwikiwiresharkorgDisplayFilters
641 Display filter fieldsEvery field in the packet details pane can be used as a filter string this will result in showing onlythe packets where this field exists For example the filter string tcp will show all packets contain-ing the tcp protocol
There is a complete list of all filter fields available through the menu item HelpSupported Proto-cols in the page Display Filter Fields of the Supported Protocols dialog
XXX - add some more info here and a link to the statusbar info
642 Comparing valuesYou can build display filters that compare values using a number of different comparison operatorsThey are shown in Table 63 ldquoDisplay Filter comparison operatorsrdquo
Tip
You can use English and C-like terms in the same way they can even be mixed in afilter string
Table 63 Display Filter comparison operators
English C-like Description and example
eq== Equal
ipsrc==10005
ne= Not equal
ipsrc=10005
gtgt Greater than
framelen gt 10
ltlt Less than
framelen lt 128
Working with captured packets
110
English C-like Description and example
gegt= Greater than or equal to
framelen ge 0x100
lelt= Less than or equal to
framelen lt= 0x20
In addition all protocol fields are typed Table 64 ldquoDisplay Filter Field Typesrdquo provides a list ofthe types and example of how to express them
Table 64 Display Filter Field Types
Type Example
Unsigned integer (8-bit 16-bit 24-bit 32-bit)You can express integers in decimal octal orhexadecimal The following display filters areequivalent
iplen le 1500iplen le 02734iplen le 0x436
Signed integer (8-bit 16-bit 24-bit 32-bit)
BooleanA boolean field is present in the protocol decodeonly if its value is true For exampletcpflagssyn is present and thus true only if theSYN flag is present in a TCP segment header
Thus the filter expression tcpflagssyn will se-lect only those packets for which this flag existsthat is TCP segments where the segment headercontains the SYN flag Similarly to find source-routed token ring packets use a filter expressionof trsr
Ethernet address (6 bytes)Separators can be a colon () dot () or dash (-)and can have one or two bytes between separat-ors
ethdst == ffffffffffffethdst == ff-ff-ff-ff-ff-ffethdst == ffffffffffff
IPv4 addressipaddr == 19216801
Classless InterDomain Routing (CIDR) notationcan be used to test if an IPv4 address is in a cer-tain subnet For example this display filter willfind all packets in the 129111 Class-B network
ipaddr == 1291110016
IPv6 address ipv6addr == 1
Working with captured packets
111
Type Example
IPX address ipxaddr == 00000000ffffffffffff
String (text) httprequesturi == httpwwwwiresharkorg
643 Combining expressionsYou can combine filter expressions in Wireshark using the logical operators shown in Table 65ldquoDisplay Filter Logical Operationsrdquo
Table 65 Display Filter Logical Operations
English C-like Description and example
and ampampLogical AND
ipsrc==10005 and tcpflagsfin
or ||Logical OR
ipscr==10005 or ipsrc==192111
xor ^^Logical XOR
trdst[03] == 0629 xor trsrc[03] == 0629
not Logical NOT
not llc
[]Substring Operator
Wireshark allows you to select subsequences of a sequence in rather elab-orate ways After a label you can place a pair of brackets [] containing acomma separated list of range specifiers
ethsrc[03] == 000083
The example above uses the nm format to specify a single range In thiscase n is the beginning offset and m is the length of the range being spe-cified
ethsrc[1-2] == 0083
The example above uses the n-m format to specify a single range In thiscase n is the beginning offset and m is the ending offset
ethsrc[4] == 00008300
The example above uses the m format which takes everything from the
Working with captured packets
112
English C-like Description and example
beginning of a sequence to offset m It is equivalent to 0m
ethsrc[4] == 2020
The example above uses the n format which takes everything from offsetn to the end of the sequence
ethsrc[2] == 83
The example above uses the n format to specify a single range In this casethe element in the sequence at offset n is selected This is equivalent ton1
ethsrc[031-2442] ==000083008300008300202083
Wireshark allows you to string together single ranges in a comma separ-ated list to form compound ranges as shown above
644 A common mistake
Warning
Using the = operator on combined expressions like ethaddr ipaddr tcpportudpport and alike will probably not work as expected
Often people use a filter string to display something like ipaddr == 1234 which will display allpackets containing the IP address 1234
Then they use ipaddr = 1234 to see all packets not containing the IP address 1234 in it Unfor-tunately this does not do the expected
Instead that expression will even be true for packets where either source or destination IP addressequals 1234 The reason for this is that the expression ipaddr = 1234 must be read as thepacket contains a field named ipaddr with a value different from 1234 As an IP datagram con-tains both a source and a destination address the expression will evaluate to true whenever at leastone of the two addresses differs from 1234
If you want to filter out all packets containing IP datagrams to or from IP address 1234 then thecorrect filter is (ipaddr == 1234) as it reads show me all the packets for which it is not true thata field named ipaddr exists with a value of 1234 or in other words filter out all packets forwhich there are no occurrences of a field named ipaddr with the value 1234
Working with captured packets
113
65 The Filter Expression dialog boxWhen you are accustomed to Wiresharks filtering system and know what labels you wish to use inyour filters it can be very quick to simply type a filter string However if you are new to Wiresharkor are working with a slightly unfamiliar protocol it can be very confusing to try to figure out whatto type The Filter Expression dialog box helps with this
Tip
The Filter Expression dialog box is an excellent way to learn how to write Wiresharkdisplay filter strings
Figure 66 The Filter Expression dialog box
When you first bring up the Filter Expression dialog box you are shown a tree list of field namesorganized by protocol and a box for selecting a relation
Field Name Select a protocol field from the protocol field tree Every protocol with filterablefields is listed at the top level (You can search for a particular protocol entry byentering the first few letters of the protocol name) By clicking on the + next to aprotocol name you can get a list of the field names available for filtering for thatprotocol
Relation Select a relation from the list of available relation The is present is a unary rela-tion which is true if the selected field is present in a packet All other listed rela-tions are binary relations which require additional data (eg a Value to match) tocomplete
When you select a field from the field name list and select a binary relation (such as the equality re-lation ==) you will be given the opportunity to enter a value and possibly some range information
Working with captured packets
114
Value You may enter an appropriate value in the Value text box The Valuewill 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 likeenums in C If the selected protocol field has such values defined youcan choose one of them here
Range XXX - add an explanation here
OK When you have built a satisfactory expression click OK and a filterstring will be built for you
Cancel You can leave the Add Expression dialog box without any effect byclicking the Cancel button
Working with captured packets
115
66 Defining and saving filtersYou can define filters with Wireshark and give them labels for later use This can save time in re-membering 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 Cap-ture menu or the Display Filters menu item from the Analyze menu Wireshark will then pop upthe Filters dialog as shown in Figure 67 ldquoThe Capture Filters and Display Filters dialogboxesrdquo
Note
The mechanisms for defining and saving capture filters and display filters are almostidentical So both will be described here differences between these two will be markedas such
Warning
You must use Save to save your filters permanently Ok or Apply will not save the fil-ters so they will be lost when you close Wireshark
Figure 67 The Capture Filters and Display Filters dialog boxes
Working with captured packets
116
New This button adds a new filter to the list of filters The currently enteredvalues from Filter name and Filter string will be used If any of thesefields are empty it will be set to new
Delete This button deletes the selected filter It will be greyed out if no filter isselected
Filter You can select a filter from this list (which will fill in the filter nameand filter string in the fields down at 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 identifythe filter for your convenience it will not be used else-where You can add multiple filters with the same namebut this is not very useful
Filter string You can change the filter string of the currently selected filter here Dis-play Filter only the string will be syntax checked while you are typing
Add Expression Display Filter only This button brings up the Add Expression dialogbox which assists in building filter strings You can find more informa-tion about the Add Expression dialog in Section 65 ldquoThe Filter Ex-pression dialog boxrdquo
OK Display Filter only This button applies the selected filter to the currentdisplay and closes the dialog
Apply Display Filter only This button applies the selected filter to the currentdisplay and keeps the dialog open
Save Save the current settings in this dialog The file location and format isexplained in Appendix A Files and Folders
Close Close this dialog This will discard unsaved settings
Working with captured packets
117
67 Finding packetsYou can easily find packets once you have captured some packets or have read in a previously savedcapture file Simply select the Find Packet menu item from the Edit menu Wireshark will pop upthe dialog box shown in Figure 68 ldquoThe Find Packet dialog boxrdquo
671 The Find Packet dialog box
Figure 68 The Find Packet dialog box
You might first select the kind of thing to search for
bull 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 19216801 use thefollowing filter string
ipsrc==19216801 and tcpflagssyn==1
For more details on display filters see Section 63 ldquoFiltering packets while viewingrdquo
bull Hex Value
Search for a specific byte sequence in the packet data
For example use 0000 to find the next packet including two null bytes in the packet data
bull String
Find a string in the packet data with various options
The value to be found will be syntax checked while you type it in If the syntax check of your valuesucceeds the background of the entry field will turn green if it fails it will turn red
Working with captured packets
118
You can choose the search direction
bull Up
Search upwards in the packet list (decreasing packet numbers)
bull Down
Search downwards in the packet list (increasing packet numbers)
672 The Find Next commandFind Next will continue searching with the same options used in the last Find Packet
673 The Find Previous commandFind Previous will do the same thing as Find Next but with reverse search direction
Working with captured packets
119
68 Go to a specific packetYou can easily jump to specific packets with one of the menu items in the Go menu
681 The Go Back commandGo back in the packet history works much like the page history in current web browsers
682 The Go Forward commandGo forward in the packet history works much like the page history in current web browsers
683 The Go to Packet dialog box
Figure 69 The Go To Packet dialog box
This dialog box will let you enter a packet number When you press OK Wireshark will jump tothat packet
684 The Go to Corresponding Packet commandIf a protocol field is selected which points to another packet in the capture file this command willjump to that packet
Note
As these protocol fields now work like links (just as in your Web browser) its easierto simply double-click on the field to jump to the corresponding field
685 The Go to First Packet commandThis command will simply jump to the first packet displayed
686 The Go to Last Packet commandThis command will simply jump to the last packet displayed
Working with captured packets
120
69 Marking packetsYou can mark packets in the Packet List pane A marked packet will be shown with black back-ground regardless of the coloring rules set Marking a packet can be useful to find it later while ana-lyzing in a large capture file
Warning
The packet marks are not stored in the capture file or anywhere else so all packetmarks will be lost if you close the capture file
You can use packet marking to control the output of packets when savingexportingprinting To doso an option in the packet range is available see Section 58 ldquoThe Packet Range framerdquo
There are three functions to manipulate the marked state of a packet
bull Mark packet (toggle) toggles the marked state of a single packet
bull Mark all packets set the mark state of all packets
bull 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 isalso available from the pop-up menu of the Packet List pane
Working with captured packets
121
610 Time display formats and timereferences
While packets are captured each packet is timestamped These timestamps will be saved to the cap-ture file so they will be available for later analysis
A detailed description of timestamps timezones and alike can be found at Section 74 ldquoTimeStampsrdquo
The timestamp presentation format and the precision in the packet list can be chosen using the Viewmenu see Figure 35 ldquoThe View Menurdquo
The available presentation formats are
bull Date and Time of Day 1970-01-01 010203123456 The absolute date and time of the daywhen the packet was captured
bull Time of Day 010203123456 The absolute time of the day when the packet was captured
bull Seconds Since Beginning of Capture 123123456 The time relative to the start of the capturefile or the first Time Reference before this packet (see Section 6101 ldquoPacket time referen-cingrdquo)
bull Seconds Since Previous Captured Packet 1123456 The time relative to the previous capturedpacket
bull Seconds Since Previous Displayed Packet 1123456 The time relative to the previous dis-played packet
The available precisions (aka the number of displayed decimal places) are
bull Automatic The timestamp precision of the loaded capture file format will be used (the default)
bull Seconds Deciseconds Centiseconds Milliseconds Microseconds or Nanoseconds Thetimestamp precision will be forced to the given setting If the actually available precision issmaller zeros will be appended If the precision is larger the remaining decimal places will becut off
Precision example If you have a timestamp and its displayed using Seconds Since Previous Pack-et the value might be 1123456 This will be displayed using the Automatic setting for libpcapfiles (which is microseconds) If you use Seconds it would show simply 1 and if you use Nano-seconds it shows 1123456000
6101 Packet time referencingThe user can set time references to packets A time reference is the starting point for all subsequentpacket time calculations It will be useful if you want to see the time values relative to a specialpacket eg the start of a new request Its 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 thecapture file
Working with captured packets
122
Note
Time referencing will only be useful if the time display format is set to SecondsSince Beginning of Capture If one of the other time display formats are used timereferencing 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 seeSection 36 ldquoThe Edit menurdquo or from the pop-up menu of the Packet List pane
bull Set Time Reference (toggle) Toggles the time reference state of the currently selected packet toon or off
bull Find Next Find the next time referenced packet in the Packet List pane
bull Find Previous Find the previous time referenced packet in the Packet List pane
Figure 610 Wireshark showing a time referenced packet
A time referenced packet will be marked with the string REF in the Time column (see packetnumber 10) All subsequent packets will show the time since the last time reference
Working with captured packets
123
Working with captured packets
124
Chapter 7 Advanced Topics71 Introduction
In this chapter some of the advanced features of Wireshark will be described
125
72 Following TCP streamsIf you are working with TCP based protocols it can be very helpful to see the data from a TCPstream in the way that the application layer sees it Perhaps you are looking for passwords in a Tel-net stream or you are trying to make sense of a data stream Maybe you just need a display filter toshow only the packets of that TCP stream If so Wiresharks ability to follow a TCP stream will beuseful to you
Simply select a TCP packet in the packet list of the streamconnection you are interested in and thenselect the Follow TCP Stream menu item from the Wireshark Tools menu (or use the context menuin the packet list) Wireshark will set an appropriate display filter and pop up a dialog box with allthe data from the TCP stream laid out in order as shown in Figure 71 ldquoThe Follow TCP Streamdialog boxrdquo
Note
It is worthwhile noting that Follow TCP Stream installs a display filter to select all thepackets in the TCP stream you have selected
721 The Follow TCP Stream dialog box
Figure 71 The Follow TCP Stream dialog box
The stream content is displayed in the same sequence as it appeared on the network Traffic from Ato B is marked in red while traffic from B to A is marked in blue If you like you can change thesecolors in the EditPreferences Colors page
Non-printable characters will be replaced by dots XXX - What about line wrapping (maximum line
Advanced Topics
126
length) and CRNL conversions
The stream content wont be updated while doing a live capture To get the latest content youll haveto reopen the dialog
You can choose from the following actions
1 Save As Save the stream data in the currently selected format
2 Print Print the stream data in the currently selected format
3 Direction Choose the stream direction to be displayed (Entire conversation data from A toB only or data from B to A only)
4 Filter out this stream Apply a display filter removing the current TCP stream data from thedisplay
5 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
1 ASCII In this view you see the data from each direction in ASCII Obviously best for ASCIIbased protocols eg HTTP
2 EBCDIC For the big-iron freaks out there
3 HEX Dump This allows you to see all the data This will require a lot of screen space and isbest used with binary protocols
4 C Arrays This allows you to import the stream data into your own C program
5 Raw This allows you to load the unaltered stream data into a different program for further ex-amination The display will look the same as the ASCII setting but Save As will result in abinary file
Advanced Topics
127
73 Expert InfosThe expert infos is a kind of log of the anomalies found by Wireshark in a capture file
The general idea behind the following Expert Info is to have a better display of uncommon orjust notable network behaviour This way both novice and expert users will hopefully find probablenetwork problems a lot faster compared to scanning the packet list manually
Expert infos are only a hint
Take expert infos as a hint whats worth looking at but not more For example Theabsense of expert infos doesnt necessarily mean everything is ok
The amount of expert infos largely depends on theprotocol being used
While some common protocols like TCPIP will show detailed expert infos most otherprotocols currently wont show any expert infos at all
The following will first describe the components of a single expert info then the User Interface
731 Expert Info EntriesEach expert info will contain the following things which will be described in detail below
Table 71 Some example expert infos
Packet Severity Group Protocol Summary
1 Note Sequence TCP DuplicateACK (1)
2 Chat Sequence TCP Connectionreset (RST)
8 Note Sequence TCP Keep-Alive
9 Warn Sequence TCP Fast retrans-mission(suspected)
7311 Severity
Every expert info has a specific severity level The following severity levels are used in parenthesesare the colors in which the items will be marked in the GUI
bull Chat (grey) information about usual workflow eg a TCP packet with the SYN flag set
bull Note (cyan) notable things eg an application returned an usual error code like HTTP 404
bull Warn (yellow) warning eg application returned an unusual error code like a connectionproblem
bull Error (red) serious problem eg [Malformed Packet]
7312 Group
Advanced Topics
128
There are some common groups of expert infos The following are currently implemented
bull Checksum a checksum was invalid
bull Sequence protocol sequence suspicious eg sequence wasnt continuous or a retransmissionwas detected or
bull Response Code problem with application response code eg HTTP 404 page not found
bull Request Code an application request (eg File Handle == x) usually Chat level
bull Undecoded dissector incomplete or data cant be decoded for other reasons
bull Reassemble problems while reassembling eg not all fragments were available or an exceptionhappened while reassembling
bull Malformed malformed packet or dissector has a bug dissection of this packet aborted
bull Debug debugging (should not occur in release versions)
Its possible that more such group values will be added in the future
7313 Protocol
The protocol in which the expert info was caused
7314 Summary
Each expert info will also have a short additional text with some further explanation
732 Expert Info Composite dialogFrom the main menu you can open the expert info dialog using AnalyzeExpert Info Composite
XXX - AnalyzeExpert Info also exists but is subject to removal and therefore not explained here
XXX - add explanation of the dialogs context menu
7321 Errors Warnings Notes Chats tabs
An easy and quick way to find the most interesting infos (rather than using the Details tab) is tohave a look at the separate tabs for each severity level As the tab label also contains the number ofexisting entries its easy to find the tab with the most important entries
There are usually a lot of identical expert infos only differing in the packet number These identical
Advanced Topics
129
infos will be combined into a single line - with a count column showing how often they appeared inthe capture file Clicking on the plus sign shows the individual packet numbers in a tree view
7322 Details tab
The Details tab provides the expert infos in a log like view each entry on its own line (much likethe packet list) As the amount of expert infos for a capture file can easily become very large gettingan idea of the interesting infos with this view can take quite a while The advantage of this tab is tohave all entries in the sequence as they appeared this is sometimes a help to pinpoint problems
733 Colorized Protocol Details Tree
The protocol field causing an expert info is colorized eg uses a cyan background for a note sever-ity level This color is propagated to the toplevel protocol item in the tree so its easy to find thefield that caused the expert info
For the example screenshot above the IP Time to live value is very low (only 1) so the corres-ponding protocol field is marked with a cyan background To easier find that item in the packet treethe IP protocol toplevel item is marked cyan as well
734 Expert Packet List Column (optional)
An optional Expert Info Severity packet list column is available (since SVN 22387 -gt 0997) thatdisplays the most significant severity of a packet or stays empty if everything seems ok Thiscolumn is not displayed by default but can be easily added using the Preferences Columns page de-scribed in Section 95 ldquoPreferencesrdquo
Advanced Topics
130
74 Time StampsTime stamps their precisions and all that can be quite confusing This section will provide you withinformation about whats going on while Wireshark processes time stamps
While packets are captured each packet is time stamped as it comes in These time stamps will besaved to the capture file so they also will be available for (later) analysis
So where do these time stamps come from While capturing Wireshark gets the time stamps fromthe libpcap (WinPcap) library which in turn gets them from the operating system kernel If the cap-ture data is loaded from a capture file Wireshark obviously gets the data from that file
741 Wireshark internalsThe internal format that Wireshark uses to keep a packet time stamp consists of the date (in dayssince 111970) and the time of day (in nanoseconds since midnight) You can adjust the way Wire-shark displays the time stamp data in the packet list see the Time Display Format item in the Sec-tion 37 ldquoThe View menurdquo for details
While reading or writing capture files Wireshark converts the time stamp data between the capturefile format and the internal format as required
While capturing Wireshark uses the libpcap (WinPcap) capture library which supports microsecondresolution Unless you are working with specialized capturing hardware this resolution should beadequate
742 Capture file formatsEvery capture file format that Wireshark knows supports time stamps The time stamp precisionsupported by a specific capture file format differs widely and varies from one second 0 to onenanosecond 0123456789 Most file formats store the time stamps with a fixed precision (eg mi-croseconds) while some file formats are even capable of storing 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) supportsa fixed microsecond resolution 0123456 only
Note
Writing data into a capture file format that doesnt provide the capability to store theactual precision will lead to loss of information Example If you load a capture filewith nanosecond resolution and store the capture data to a libpcap file (with micro-second resolution) Wireshark obviously must reduce the precision from nanosecond tomicrosecond
743 AccuracyIts often asked Which time stamp accuracy is provided by Wireshark Well Wireshark doesntcreate any time stamps itself but simply gets them from somewhere else and displays them So ac-curacy will depend on the capture system (operating system performance ) that you use Becauseof 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 Theincoming packets have to take a long and winding road to travel through the USBcable until they actually reach the kernel As the incoming packets are time stampedwhen they are processed by the kernel this time stamping mechanism becomes very
Advanced Topics
131
inaccurate
Conclusion dont use USB connected NICs when you need precise time stamp accur-acy (XXX - are there any such NICs that generate time stamps on the USB hard-ware)
Advanced Topics
132
75 Time ZonesIf you travel across the planet time zones can be confusing If you get a capture file from some-where 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
bull You are only interested in the time differences between the packet time stamps and dont need toknow the exact date and time of the captured packets (which is often the case)
bull You dont get capture files from different time zones than your own so there are simply no timezone problems For example everyone in your team is working in the same time zone as your-self
What are time zones
People expect that the time reflects the sunset Dawn should be in the morning maybe around0600 and dusk in the evening maybe at 2000 These times will obviously vary depending onthe season It would be very confusing if everyone on earth would use the same global time asthis 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 timethat corresponds to the local sunset
The time zones base time is UTC (Coordinated Universal Time) or Zulu Time (military andaviation) The older term GMT (Greenwich Mean Time) shouldnt be used as it is slightly in-correct (up to 09 seconds difference to UTC) The UTC base time equals to 0 (based atGreenwich 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 youare in time zone +1 (time difference in hours compared to UTC) If its 3 oclock in Berlinits 2 oclock in UTC at the same moment
Be aware that at a few places on earth dont use time zones with even hour offsets (eg NewDelhi uses UTC+0530)
Further information can be found at httpenwikipediaorgwikiTime_zone and ht-tpenwikipediaorgwikiCoordinated_Universal_Time
What is daylight saving time (DST)
Daylight Saving Time (DST) also known as Summer Time is intended to save some day-light during the summer months To do this a lot of countries (but not all) add a DST hour tothe already existing UTC offset So you may need to take another hour (or in very rare caseseven two hours) difference into your time zone calculations
Unfortunately the date at which DST actually takes effect is different throughout the worldYou may also note that the northern and southern hemispheres have opposite DSTs (egwhile its summer in Europe its winter in Australia)
Keep in mind UTC remains the same all year around regardless of DST
Further information can be found at httpenwikipediaorgwikiDaylight_saving
Further time zone and DST information can be found at httpwwpgreenwichmeantimecom andhttpwwwtimeanddatecomworldclock
Advanced Topics
133
751 Set your computers time correctlyIf you work with people around the world its very helpful to set your computers time and timezone right
You should set your computers time and time zone in the correct sequence
1 Set your time zone to your current location
2 Set your computers 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 its an often made mistake to adjust the hours of yourcomputer clock to the local time Dont adjust the hours but your time zone setting in-stead For your computer the time is essentially the same as before you are simply ina different time zone with a different local time
Tip
You can use the Network Time Protocol (NTP) to automatically adjust your computerto the correct time by synchronizing it to Internet NTP clock servers NTP clients areavailable for all operating systems that Wireshark supports (and for a lot more) for ex-amples see httpwwwntporg
752 Wireshark and Time ZonesSo whats the relationship between Wireshark and time zones anyway
Wiresharks native capture file format (libpcap format) and some other capture file formats such asthe Windows Sniffer EtherPeek AiroPeek and Sun snoop formats save the arrival time of packetsas UTC values UNX systems and Windows NT based systems (Windows NT 40 Windows2000 Windows XP Windows Server 2003 Windows Vista) represent time internally as UTCWhen Wireshark is capturing no conversion is necessary However if the system time zone is notset correctly the systems UTC time might not be correctly set even if the system clock appears todisplay 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 be-fore supplying it to Wireshark If the systems time zone is not set correctly that conversion will notbe done correctly
Other capture file formats such as the Microsoft Network Monitor DOS-based Sniffer and Net-work Instruments Observer formats save the arrival time of packets as local time values
Internally to Wireshark time stamps are represented in UTC this means that when reading capturefiles that save the arrival time of packets as local time values Wireshark must convert those localtime values to UTC values
Wireshark in turn will display the time stamps always in local time The displaying computer willconvert them from UTC to local time and displays this (local) time For capture files saving the ar-rival time of packets as UTC values this means that the arrival time will be displayed as the localtime in your time zone which might not be the same as the arrival time in the time zone in whichthe packet was captured For capture files saving the arrival time of packets as local time values theconversion to UTC will be done using your time zones offset from UTC and DST rules whichmeans the conversion will not be done correctly the conversion back to local time for display mightundo this correctly in which case the arrival time will be displayed as the arrival time in which thepacket was captured
Advanced Topics
134
Table 72 Time zone examples for UTC arrival times (without DST)
Los Angeles New York Madrid London Berlin Tokyo
CaptureFile (UTC)
1000 1000 1000 1000 1000 1000
Local Offsetto UTC
-8 -5 -1 0 +1 +9
DisplayedTime (LocalTime)
0200 0500 0900 1000 1100 1900
An example Lets assume that someone in Los Angeles captured a packet with Wireshark at exactly2 oclock local time and sends you this capture file The capture files time stamp will be representedin UTC as 10 oclock You are located in Berlin and will see 11 oclock on your Wireshark display
Now you have a phone call video conference or Internet meeting with that one to talk about thatcapture file As you are both looking at the displayed time on your local computers the one in LosAngeles still sees 2 oclock but you in Berlin will see 11 oclock The time displays are different asboth Wireshark displays will show the (different) local times at the same point in time
Conclusion You may not bother about the datetime of the time stamp you currently look at unlessyou must make sure that the datetime is as expected So if you get a capture file from a differenttime zone andor DST youll have to find out the time zoneDST difference between the two localtimes and mentally adjust the time stamps accordingly In any case make sure that every com-puter in question has the correct time and time zone setting
Advanced Topics
135
76 Packet Reassembling761 What is it
Network protocols often need to transport large chunks of data which are complete in themselveseg when transferring a file The underlying protocol might not be able to handle that chunk size(eg limitation of the network packet size) or is stream-based like TCP which doesnt know datachunks at all
In that case the network protocol has to handle the chunk boundaries itself and (if required) spreadthe data over multiple packets It obviously also needs a mechanism to determine the chunk bound-aries on the receiving side
Tip
Wireshark calls this mechanism reassembling although a specific protocol specifica-tion might use a different term for this (eg desegmentation defragmentation )
762 How Wireshark handles itFor some of the network protocols Wireshark knows of a mechanism is implemented to find de-code and display these chunks of data Wireshark will try to find the corresponding packets of thischunk and will show the combined data as additional pages in the Packet Bytes pane (for inform-ation about this pane see Section 317 ldquoThe Packet Bytes panerdquo)
Figure 72 The Packet Bytes pane with a reassembled tab
Note
Reassembling might take place at several protocol layers so its possible that multipletabs 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 (eg an HTML page) is returned Wire-shark will show the hex dump of the data in a new tab Uncompressed entity body in the PacketBytes pane
Reassembling is enabled in the preferences by default The defaults were changed from disabled toenabled in September 2005 If you created your preference settings before this date you might lookif 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
1 the lower level protocol (eg TCP) must support reassembly Often this reassembly can be en-abled or disabled via the protocol preferences
Advanced Topics
136
2 the higher level protocol (eg HTTP) must use the reassembly mechanism to reassemble frag-mented protocol data This too can often be enabled or disabled via the protocol preferences
The tooltip of the higher level protocol setting will notify you if and which lower level protocol set-ting also has to be considered
Advanced Topics
137
77 Name ResolutionName resolution tries to resolve some of the numerical address values into a human readable formatThere are two possible ways to do these conversations depending on the resolution to be done call-ing systemnetwork services (like the gethostname function) andor evaluate from Wireshark specif-ic configuration files For details about the configuration files Wireshark uses for name resolutionand alike see Appendix A Files and Folders
The name resolution feature can be en-disabled separately for the protocol layers of the followingsections
771 Name Resolution drawbacksName resolution can be invaluable while working with Wireshark and may even save you hours ofwork Unfortunately it also has its drawbacks
bull Name resolution will often fail The name to be resolved might simply be unknown by thename servers asked or the servers are just not available and the name is also not found in Wire-sharks configuration files
bull The resolved names are not stored in the capture file or somewhere else So the resolvednames might not be available if you open the capture file later or on a different machine Eachtime you open a capture file it may look slightly different maybe simply because you cantconnect to a name server (which you could connect before)
bull DNS may add additional packets to your capture file You may see packets tofrom your ma-chine in your capture file which are caused by name resolution network services of the machineWireshark captures from XXX - are there any other such packets than DNS ones
bull Resolved DNS names are cached by Wireshark This is required for acceptable performanceHowever if the name resolution information should change while Wireshark is running Wire-shark wont notice a change to the name resolution information once it gets cached If this in-formation changes while Wireshark is running eg a new DHCP lease takes effect Wiresharkwont 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 beresolved after a packet was added to the list that former entry wont be changed Asthe name resolution results are cached you can use ViewReload to rebuild the pack-et list this time with the correctly resolved names However this isnt possible while acapture is in progress
772 Ethernet name resolution (MAC layer)Try to resolve an Ethernet MAC address (eg 00095b010203) to something more human read-able
ARP name resolution (system service) Wireshark will ask the operating system to convert an Eth-ernet address to the corresponding IP address (eg 00095b010203 -gt 19216801)
Ethernet codes (ethers file) If the ARP name resolution failed Wireshark tries to convert the Eth-ernet address to a known device name which has been assigned by the user using an ethers file (eg00095b010203 -gt homerouter)
Ethernet manufacturer codes (manuf file) If neither ARP or ethers returns a result Wiresharktries to convert the first 3 bytes of an ethernet address to an abbreviated manufacturer name whichhas been assigned by the IEEE (eg 00095b010203 -gt Netgear_010203)
Advanced Topics
138
773 IP name resolution (network layer)Try to resolve an IP address (eg 2162393799) to something more human readable
DNSADNS name resolution (systemlibrary service) Wireshark will ask the operating system(or the ADNS library) to convert an IP address to the hostname associated with it (eg2162393799 -gt www1googlecom) The DNS service is using synchronous calls to the DNSserver So Wireshark will stop responding until a response to a DNS request is returned If possibleyou might consider using the ADNS library (which wont wait for a network response)
Warning
Enabling network name resolution when your name server is unavailable may signific-antly slow down Wireshark while it waits for all of the name server requests to timeout Use ADNS in that case
DNS vs ADNS heres a short comparison Both mechanisms are used to convert an IP address tosome human readable (domain) name The usual DNS call gethostname() will try to convert the ad-dress to a name To do this it will first ask the systems hosts file (eg etchosts) if it finds a match-ing 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 DNSserver about a name resolution The system call gethostname() will wait until a name is resolved oran 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 wont wait forthe answer It will just return to Wireshark in a very short amount of time The actual (and the fol-lowing) address fields wont show the resolved name until the ADNS call returned As mentionedabove the values get cached so you can use ViewReload to update these fields to show the re-solved values
hosts name resolution (hosts file) If DNS name resolution failed Wireshark will try to convert anIP address to the hostname associated with it using a hosts file provided by the user (eg2162393799 -gt wwwgooglecom)
774 IPX name resolution (network layer)ipxnet name resolution (ipxnets file) XXX - add ipxnets name resolution explanation
775 TCPUDP port name resolution (transport layer)Try to resolve a TCPUDP port (eg 80) to something more human readable
TCPUDP port conversion (system service) Wireshark will ask the operating system to convert aTCP or UDP port to its well known name (eg 80 -gt http)
XXX - mention the role of the etcservices file (but dont forget the files and folders section)
Advanced Topics
139
78 ChecksumsSeveral network protocols use checksums to ensure data integrity
Tip
Applying checksums as described here is also known as redundancy checking
What are checksums for
Checksums are used to ensure the integrity of data portions for data transmission or storageA checksum is basically a calculated summary of such a data portion
Network data transmissions often produce errors such as toggled missing or duplicated bitsAs a result the data received might not be identical to the data transmitted which is obvi-ously a bad thing
Because of these transmission errors network protocols very often use checksums to detectsuch errors The transmitter will calculate a checksum of the data and transmits the data to-gether with the checksum The receiver will calculate the checksum of the received data withthe same algorithm as the transmitter If the received and calculated checksums dont match atransmission error has occurred
Some checksum algorithms are able to recover (simple) errors by calculating where the ex-pected error must be and repairing it
If there are errors that cannot be recovered the receiving side throws away the packet De-pending on the network protocol this data loss is simply ignored or the sending side needs todetect this loss somehow and retransmits the required packet(s)
Using a checksum drastically reduces the number of undetected transmission errorsHowever the usual checksum algorithms cannot guarantee an error detection of 100 so avery small number of transmission errors may remain undetected
There are several different kinds of checksum algorithms an example of an often used check-sum algorithm is CRC32 The checksum algorithm actually chosen for a specific networkprotocol will depend on the expected error rate of the network medium the importance of er-ror detection the processor load to perform the calculation the performance needed andmany other things
Further information about checksums can be found at http enwikipediaorg wikiChecksum
781 Wireshark checksum validationWireshark will validate the checksums of several protocols eg IP TCP UDP
It will do the same calculation as a normal receiver would do and shows the checksum fields inthe packet details with a comment eg [correct] [invalid must be 0x12345678] or alike
Checksum validation can be switched off for various protocols in the Wireshark protocol prefer-ences eg to (very slightly) increase performance
If the checksum validation is enabled and it detected an invalid checksum features like packet reas-sembling wont be processed This is avoided as incorrect connection data could confuse the in-ternal database
Advanced Topics
140
782 Checksum offloadingThe 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 thereceiving hardware validates this checksum If the received checksum is wrong Wireshark wonteven see the packet as the Ethernet hardware internally throws away the packet
Higher level checksums are traditionally calculated by the protocol implementation and the com-pleted packet is then handed over to the hardware
Recent network hardware can perform advanced features such as IP checksum calculation alsoknown as checksum offloading The network driver wont calculate the checksum itself but willsimply 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 transmittedare handed over to Wireshark before the checksums are actually calculated Wiresharkgets these empty checksums and displays them as invalid even though the packetswill 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 bequite annoying As mentioned above invalid checksums may lead to unreassembled packets mak-ing the analysis of the packet data much harder
You can do two things to avoid this checksum offloading problem
bull Turn off the checksum offloading in the network driver if this option is available
bull Turn off checksum validation of the specific protocol in the Wireshark preferences
Advanced Topics
141
Advanced Topics
142
Chapter 8 Statistics81 Introduction
Wireshark provides a wide range of network statistics which can be accessed via the Statisticsmenu
These statistics range from general information about the loaded capture file (like the number ofcaptured packets) to statistics about specific protocols (eg statistics about the number of HTTP re-quests and responses captured)
bull General statistics
bull Summary about the capture file
bull Protocol Hierarchy of the captured packets
bull Conversations eg traffic between specific IP addresses
bull Endpoints eg traffic to and from an IP addresses
bull IO Graphs visualizing the number of packets (or similar) in time
bull Protocol specific statistics
bull Service Response Time between request and response of some protocols
bull Various other protocol specific statistics
Note
The protocol specific statistics requires detailed knowledge about the specific protocolUnless you are familiar with that protocol statistics about it will be pretty hard to un-derstand
143
82 The Summary windowGeneral statistics about the current capture file
Figure 81 The Summary window
bull File general information about the capture file
Statistics
144
bull Time the timestamps when the first and the last packet were captured (and the time betweenthem)
bull Capture information from the time when the capture was done (only available if the packetdata was captured from the network and not loaded from a file)
bull Display some display related information
bull Traffic some statistics of the network traffic seen If a display filter is set you will see values inthe Captured column and if any packages are marked you will see values in the Markedcolumn The values in the Captured column will remain the same as before while the values inthe Displayed column will reflect the values corresponding to the packets shown in the displayThe values in the Marked column will reflect the values corresponding to the marked packages
Statistics
145
83 The Protocol Hierarchy windowThe protocol hierarchy of the captured packets
Figure 82 The Protocol Hierarchy window
This is a tree of all the protocols in the capture You can collapse or expand subtrees by clicking onthe plus minus icons By default all trees are expanded
Each row contains the statistical values of one protocol The Display filter will show the currentdisplay filter
The following columns containing the statistical values are available
bull Protocol this protocols name
bull Packets the percentage of protocol packets relative to all packets in the capture
bull Packets the absolute number of packets of this protocol
bull Bytes the absolute number of bytes of this protocol
bull MBits the bandwidth of this protocol relative to the capture time
bull End Packets the absolute number of packets of this protocol (where this protocol was thehighest protocol to decode)
bull End Bytes the absolute number of bytes of this protocol (where this protocol was the highestprotocol to decode)
bull End MBits the bandwidth of this protocol relative to the capture time (where this protocolwas the highest protocol to decode)
Statistics
146
Note
Packets will usually contain multiple protocols so more than one protocol will becounted for each packet Example In the screenshot IP has 9917 and TCP 8583(which is together much more than 100)
Note
Protocol layers can consist of packets that wont contain any higher layer protocol sothe sum of all higher layer packets may not sum up to the protocols packet count Ex-ample In the screenshot TCP has 8583 but the sum of the subprotocols (HTTP )is much less This may be caused by TCP protocol overhead eg TCP ACK packetswont be counted as packets of the higher layer)
Note
A single packet can contain the same protocol more than once In this case the pro-tocol is counted more than once For example in some tunneling configurations the IPlayer can appear twice
Statistics
147
84 ConversationsStatistics of the captured conversations
841 What is a ConversationA network conversation is the traffic between two specific endpoints For example an IP conversa-tion is all the traffic between two IP addresses The description of the known endpoint types can befound in Section 851 ldquoWhat is an Endpointrdquo
842 The Conversations windowOther than the list content the conversations window works the same way as the endpoint Windowsee Section 852 ldquoThe Endpoints windowrdquo for a description how it works
Figure 83 The Conversations window
The copy button will copy the list values to the clipboard in CSV (Comma Seperated Values)format
843 The protocol specific Conversation Listwindows
Before the combined window described above was available each of its pages was shown as a sep-arate window Even though the combined window is much more convenient to use these separatewindows are still available The main reason is that they might process faster for very large capturefiles However as the functionality is exactly the same as in the combined window they wont bediscussed in detail here
Statistics
148
85 EndpointsStatistics of the endpoints captured
Tip
If you are looking for a feature other network tools call a hostlist here is the rightplace to look The list of Ethernet or IP endpoints is usually what youre looking for
851 What is an EndpointA network endpoint is the logical endpoint of separate protocol traffic of a specific protocol layerThe endpoint statistics of Wireshark will take the following endpoints into account
bull Ethernet an Ethernet endpoint is identical to the Ethernets MAC address
bull Fibre Channel XXX - insert info here
bull FDDI a FDDI endpoint is identical to the FDDI MAC address
bull IPv4 an IP endpoint is identical to its IP address
bull IPX XXX - insert info here
bull TCP a TCP endpoint is a combination of the IP address and the TCP port used so differentTCP ports on the same IP address are different TCP endpoints
bull Token Ring a Token Ring endpoint is identical to the Token Ring MAC address
bull UDP a UDP endpoint is a combination of the IP address and the UDP port used so differentUDP ports on the same IP address are different UDP endpoints
Broadcast multicast endpoints
Broadcast multicast traffic will be shown separately as additional endpoints Ofcourse as these endpoints are virtual endpoints the real traffic will be received by all(multicast some) of the listed unicast endpoints
852 The Endpoints windowThis window shows statistics about the endpoints captured
Figure 84 The Endpoints window
Statistics
149
For each supported protocol a tab is shown in this window Each tab label shows the number of en-dpoints captured (eg the tab label Ethernet 5 tells you that five ethernet endpoints have beencaptured) If no endpoints of a specific protocol were captured the tab label will be greyed 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 protocollayer (MAC layer for the selected Ethernet endpoints page) As you might have noticed the firstrow has a name resolution of the first three bytes Netgear the second rows address was resolvedto an IP address (using ARP) and the third was resolved to a broadcast (unresolved this would stillbe ffffffffffff) the last two Ethernet addresses remain unresolved
The copy button will copy the list values to the clipboard in CSV (Comma Seperated Values)format
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
853 The protocol specific Endpoint List windowsBefore the combined window described above was available each of its pages was shown as a sep-arate window Even though the combined window is much more convenient to use these separatewindows are still available The main reason is that they might process faster for very large capturefiles However as the functionality is exactly the same as in the combined window they wont bediscussed in detail here
Statistics
150
86 The IO Graphs windowUser configurable graph of the captured network packets
You can define up to five differently colored graphs
Figure 85 The IO Graphs window
The user can configure the following things
bull Graphs
bull Graph 1-5 enable the specific graph 1-5 (only graph 1 is enabled by default)
bull Color the color of the graph (cannot be changed)
bull Filter a display filter for this graph (only the packets that pass this filter will be taken intoaccount for this graph)
bull Style the style of the graph (LineImpulseFBarDot)
bull X Axis
bull Tick interval an interval in x direction lasts (101 minutes or 101010010001 seconds)
bull Pixels per tick use 10521 pixels per tick interval
bull View as time of day option to view x direction labels as time of day instead of seconds orminutes since beginning of capture
bull Y Axis
bull Unit the unit for the y direction (PacketsTick BytesTick BitsTick Advanced)
Statistics
151
bull Scale the scale for the y unit (102050100200500) [XXX - describe the Advanced fea-ture]
The save button will save the currently displayed portion of the graph as one of various file formatsThe save feature is only available when using GTK version 26 or higher (the latest Windows ver-sions comply with this requirement) and Wireshark version 0997 or higher
The copy button will copy values from selected graphs to the clipboard in CSV (Comma SeperatedValues) format The copy feature is only available in Wireshark version 0998 or higher
Statistics
152
87 Service Response TimeThe service response time is the time between a request and the corresponding response This in-formation is available for many protocols
Service response time statistics are currently available for the following protocols
bull DCE-RPC
bull Fibre Channel
bull H225 RAS
bull LDAP
bull MGCP
bull ONC-RPC
bull 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 slightlydifferent) compared to the following description
871 The Service Response Time DCE-RPC windowThe service response time of DCE-RPC is the time between the request and the corresponding re-sponse
First of all you have to select the DCE-RPC interface
Figure 86 The Compute DCE-RPC statistics window
You can optionally set a display filter to reduce the amount of packets
Statistics
153
Figure 87 The DCE-RPC Statistic for window
Each row corresponds to a method of the interface selected (so the EPM interface in version 3 has 7methods) For each method the number of calls and the statistics of the SRT time is calculated
Statistics
154
88 The protocol specific statistics windowsThe protocol specific statistics windows display detailed information of specific protocols and mightbe described in a later version of this document
Some of these statistics are described at the httpwikiwiresharkorgStatistics pages
Statistics
155
Statistics
156
Chapter 9 Customizing Wireshark91 Introduction
Wiresharks default behaviour will usually suit your needs pretty well However as you becomemore familiar with Wireshark it can be customized in various ways to suit your needs even betterIn this chapter we explore
bull How to start Wireshark with command line parameters
bull How to colorize the packet list
bull How to control protocol dissection
bull How to use the various preference settings
157
92 Start Wireshark from the command lineYou can start Wireshark from the command line but it can also be started from most Window man-agers as well In this section we will look at starting it from the command line
Wireshark supports a large number of command line parameters To see what they are simply enterthe command wireshark -h and the help information shown in Example 91 ldquoHelp informationavailable from Wiresharkrdquo (or something similar) should be printed
Example 91 Help information available from Wireshark
Wireshark 0996Interactively dump and analyze network trafficSee httpwwwwiresharkorg for more information
Copyright 1998-2007 Gerald Combs ltgeraldwiresharkorggt and contributorsThis is free software see the source for copying conditions There is NOwarranty not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE
Usage wireshark [options] [ ltinfilegt ]
Capture interface-i ltinterfacegt name or idx of interface (def first non-loopback)-f ltcapture filtergt packet filter in libpcap filter syntax-s ltsnaplengt packet snapshot length (def 65535)-p dont capture in promiscuous mode-k start capturing immediately (def do nothing)-Q quit Wireshark after capturing-S update packet display when new packets are captured-l turn on automatic scrolling while -S is in use-B ltbuffer sizegt size of kernel buffer (def 1MB)-y ltlink typegt link layer type (def first appropriate)-D print list of interfaces and exit-L print list of link-layer types of iface and exit
Capture stop conditions-c ltpacket countgt stop after n packets (def infinite)-a ltautostop condgt durationNUM - stop after NUM seconds
filesizeNUM - stop this file after NUM KBfilesNUM - stop after NUM files
Capture output-b ltringbuffer optgt durationNUM - switch to next file after NUM secs
filesizeNUM - switch to next file after NUM KBfilesNUM - ringbuffer replace after NUM files
Input file-r ltinfilegt set the filename to read from (no pipes or stdin)
Processing-R ltread filtergt packet filter in Wireshark display filter syntax-n disable all name resolutions (def all enabled)-N ltname resolve flagsgt enable specific name resolution(s) mntC
User interface-g ltpacket numbergt go to specified packet number after -r-m ltfontgt set the font name used for most text-t ad|a|r|d|dd|e output format of time stamps (def r rel to first)-X ltkeygtltvaluegt eXtension options see man page for details-z ltstatisticsgt show various statistics see man page for details
Output-w ltoutfile|-gt set the output filename (or - for stdout)
Miscellaneous-h display this help and exit-v display version info and exit-P ltkeypathgt persconfpath - personal configuration files
persdatapath - personal data files-o ltnamegtltvaluegt override preference or recent setting
We will examine each of the command line options in turn
The first thing to notice is that issuing the command wireshark by itself will bring up WiresharkHowever you can include as many of the command line parameters as you like Their meanings areas follows ( in alphabetical order ) XXX - is the alphabetical order a good choice Maybe better
Customizing Wireshark
158
task based
-a ltcapture autostop conditiongt Specify a criterion that specifies when Wireshark is to stopwriting to a capture file The criterion is of the formtestvalue where test is one of
durationvalue Stop writing to a capture file aftervalue of seconds have elapsed
filesizevalue Stop writing to a capture file after itreaches a size of value kilobytes(where a kilobyte is 1000 bytes not1024 bytes) If this option is used to-gether with the -b option Wiresharkwill stop writing to the current capturefile and switch to the next one if files-ize is reached
filesvalue Stop writing to capture files aftervalue number of files were written
-b ltcapture ring buffer optiongt If a maximum capture file size was specified this optioncauses Wireshark to run in ring buffer mode with the spe-cified number of files In ring buffer mode Wireshark willwrite to several capture files Their name is based on thenumber of the file and on the creation date and time
When the first capture file fills up Wireshark will switch towriting to the next file until it fills up the last file at whichpoint itll discard the data in the first file (unless 0 is spe-cified in which case the number of files is unlimited) andstart writing to that file and so on
If the optional duration is specified Wireshark will alsoswitch to the next file when the specified number of secondshas elapsed even if the current file is not completely fills up
durationvalue Switch to the next file after valueseconds have elapsed even if the cur-rent file is not completely filled up
filesizevalue Switch to the next file after it reachesa size of value kilobytes (where a kilo-byte is 1000 bytes not 1024 bytes)
filesvalue Begin again with the first file aftervalue number of files were written(form a ring buffer)
-B ltcapture buffer size (Win32only)gt
Win32 only set capture buffer size (in MB default is 1MB)This is used by the the capture driver to buffer packet data un-til that data can be written to disk If you encounter packetdrops while capturing try to increase this size
-c ltcapture packet countgt This option specifies the maximum number of packets to cap-ture when capturing live data It would be used in conjunctionwith the -k option
-D Print a list of the interfaces on which Wireshark can captureand exit For each network interface a number and an inter-face name possibly followed by a text description of the in-terface is printed The interface name or the number can be
Customizing Wireshark
159
supplied to the -i flag to specify an interface on which to cap-ture
This can be useful on systems that dont have a command tolist them (eg Windows systems or UNIX systems lackingifconfig -a) the number can be useful on Windows 2000 andlater systems where the interface name is a somewhat com-plex string
Note that can capture means that Wireshark was able toopen that device to do a live capture if on your system aprogram doing a network capture must be run from an ac-count with special privileges (for example as root) then ifWireshark is run with the -D flag and is not run from such anaccount it will not list any interfaces
-f ltcapture filtergt This option sets the initial capture filter expression to be usedwhen capturing packets
-g ltpacket numbergt After reading in a capture file using the -r flag go to the giv-en packet number
-h The -h option requests Wireshark to print its version and us-age instructions (as shown above) and exit
-i ltcapture interfacegt Set the name of the network interface or pipe to use for livepacket capture
Network interface names should match one of the names lis-ted in wireshark -D (described above) a number as reportedby wireshark -D can also be used If youre using UNIXnetstat -i or ifconfig -a might also work to list interfacenames although not all versions of UNIX support the -a flagto ifconfig
If no interface is specified Wireshark searches the list of in-terfaces choosing the first non-loopback interface if there areany non-loopback interfaces and choosing the first loopbackinterface if there are no non-loopback interfaces if there areno interfaces Wireshark reports an error and doesnt start thecapture
Pipe names should be either the name of a FIFO (named pipe)or ``- to read data from the standard input Data read frompipes must be in standard libpcap format
-k The -k option specifies that Wireshark should start capturingpackets immediately This option requires the use of the -iparameter to specify the interface that packet capture will oc-cur from
-l This option turns on automatic scrolling if the packet list paneis being updated automatically as packets arrive during a cap-ture ( as specified by the -S flag)
-L List the data link types supported by the interface and exit
-m ltfontgt This option sets the name of the font used for most text dis-played by Wireshark XXX - add an example
-n Disable network object name resolution (such as hostnameTCP and UDP port names)
Customizing Wireshark
160
-N ltname resolving flagsgt Turns on name resolving for particular types of addresses andport numbers the argument is a string that may contain theletters m to enable MAC address resolution n to enable net-work address resolution and t to enable transport-layer portnumber resolution This overrides -n if both -N and -n arepresent The letter C enables concurrent (asynchronous) DNSlookups
-o ltpreferencerecent settingsgt Sets a preference or recent value overriding the default valueand any value read from a preferencerecent file The argu-ment to the flag is a string of the form prefnamevalue whereprefname is the name of the preference (which is the samename that would appear in the preferencerecent file) andvalue is the value to which it should be set Multiple instancesof -o ltpreference settingsgt can be given on a single com-mand line
An example of setting a single preference would be
wireshark -o mgcpdisplay_dissect_treeTRUE
An example of setting multiple preferences would be
wireshark -o mgcpdisplay_dissect_treeTRUE -omgcpudpcallagent_port2627
Tip
You can get a list of all available preferencestrings from the preferences file see Ap-pendix A Files and Folders
-p Dont put the interface into promiscuous mode Note that theinterface might be in promiscuous mode for some other reas-on hence -p cannot be used to ensure that the only trafficthat is captured is traffic sent to or from the machine onwhich Wireshark is running broadcast traffic and multicasttraffic to addresses received by that machine
-P ltpath settinggt Special path settings usually detected automatically This isused for special cases eg starting Wireshark from a knownlocation on an USB stick
The criterion is of the form keypath where key is one of
persconfpath path of personal configuration files likethe preferences files
persdatapath path of personal data files its the folderinitially opened After the initilizationthe recent file will keep the folder lastused
-Q This option forces Wireshark to exit when capturing is com-plete It can be used with the -c option It must be used inconjunction with the -i and -w options
-r ltinfilegt This option provides the name of a capture file for Wiresharkto read and display This capture file can be in one of theformats Wireshark understands
-R ltread (display) filtergt This option specifies a display filter to be applied when read-
Customizing Wireshark
161
ing packets from a capture file The syntax of this filter is thatof the display filters discussed in Section 63 ldquoFiltering pack-ets while viewingrdquo Packets not matching the filter are dis-carded
-s ltcapture snaplengt This option specifies the snapshot length to use when captur-ing packets Wireshark will only capture ltsnaplengt bytes ofdata for each packet
-S This option specifies that Wireshark will display packets as itcaptures them This is done by capturing in one process anddisplaying them in a separate process This is the same as Up-date list of packets in real time in the Capture Options dialogbox
-t lttime stamp formatgt This option sets the format of packet timestamps that are dis-played in the packet list window The format can be one of
bull r relative which specifies timestamps are displayed relat-ive to the first packet captured
bull a absolute which specifies that actual times be displayedfor all packets
bull ad absolute with date which specifies that actual datesand times be displayed for all packets
bull d delta which specifies that timestamps are relative to theprevious packet
bull e epoch which specifies that timestamps are secondssince epoch (Jan 1 1970 000000)
-v The -v option requests Wireshark to print out its version in-formation and exit
-w ltsavefilegt This option sets the name of the savefile to be used when sav-ing a capture file
-y ltcapture link typegt If a capture is started from the command line with -k set thedata link type to use while capturing packets The values re-ported by -L are the values that can be used
-X lteXtension optiongt Specify an option to be passed to a TShark module The eX-tension option is in the form extension_keyvalue where ex-tension_key can be
lua_scriptlua_script_filename Tells Wireshark to load thegiven script in addition to the default Lua scripts
-z ltstatistics-stringgt Get Wireshark to collect various types of statistics and dis-play the result in a window that updates in semi-real timeXXX - add more details here
Customizing Wireshark
162
93 Packet colorizationA very useful mechanism available in Wireshark is packet colorization You can set-up Wiresharkso that it will colorize packets according to a filter This allows you to emphasize the packets youare (usually) interested in
Tip
You will find a lot of Coloring Rule examples at the Wireshark Wiki Coloring Rulespage at httpwikiwiresharkorgColoringRules
There are two types of coloring rules in Wireshark Temporary ones that are only used until you quitthe program And permanent ones that will be saved to a preference file so that they are available ona next session
Temporary coloring rules can be added by selecting a packet and pressing the ltctrlgt key togetherwith one of the number keys This will create a coloring rule based on the currently selected conver-sation It will try to create a conversation filter based on TCP first then UDP then IP and at lastEthernet Temporary filters can also be created by selecting the Colorize with Filter gt Color Xmenu items when rightclicking in the packet-detail pane
To permanently colorize packets select the Coloring Rules menu item from the View menuWireshark will pop up the Coloring Rules dialog box as shown in Figure 91 ldquoThe ColoringRules dialog boxrdquo
Figure 91 The Coloring Rules dialog box
Once the Coloring Rules dialog box is up there are a number of buttons you can use depending onwhether or not you have any color filters installed already
Note
You will need to carefully select the order the coloring rules are listed as they are ap-plied in order from top to bottom So more specific rules need to be listed before moregeneral rules For example if you have a color rule for UDP before the one for DNSthe color rule for DNS will never be applied (as DNS uses UDP so the UDP rule willmatch first)
Customizing Wireshark
163
If this is the first time you have used Coloring Rules click on the New button which will bring upthe Edit color filter dialog box as shown in Figure 92 ldquoThe Edit Color Filter dialog boxrdquo
Figure 92 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 theFilter text field Figure 92 ldquoThe Edit Color Filter dialog boxrdquo shows the values arp and arpwhich means that the name of the color filter is arp and the filter will select protocols of type arpOnce you have entered these values you can choose a foreground and background color for packetsthat match the filter expression Click on Foreground color or Background color to achievethis and Wireshark will pop up the Choose foregroundbackground color for protocol dialog box asshown in Figure 93 ldquoThe Choose color dialog boxrdquo
Figure 93 The Choose color dialog box
Customizing Wireshark
164
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 theRGB values Alternatively you can set the values to select the color you want
Figure 94 ldquoUsing color filters with Wiresharkrdquo shows an example of several color filters beingused in Wireshark You may not like the color choices however feel free to choose your own
If you are uncertain which coloring rule actually took place for a specific packet have a look at the[Coloring Rule Name ] and [Coloring Rule String ] fields
Figure 94 Using color filters with Wireshark
Customizing Wireshark
165
94 Control Protocol dissectionThe user can control how protocols are dissected
Each protocol has its own dissector so dissecting a complete packet will typically involve severaldissectors As Wireshark tries to find the right dissector for each packet (using static routes andheuristics guessing) it might choose the wrong dissector in your specific case For example Wire-shark wont know if you use a common protocol on an uncommon TCP port eg using HTTP onTCP port 800 instead of the standard port 80
There are two ways to control the relations between protocol dissectors disable a protocol dissectorcompletely or temporarily divert the way Wireshark calls the dissectors
941 The Enabled Protocols dialog boxThe Enabled Protocols dialog box lets you enable or disable specific protocols all protocols are en-abled by default When a protocol is disabled Wireshark stops processing a packet whenever thatprotocol is encountered
Note
Disabling a protocol will prevent information about higher-layer protocols from beingdisplayed For example suppose you disabled the IP protocol and selected a packetcontaining Ethernet IP TCP and HTTP information The Ethernet information wouldbe displayed but the IP TCP and HTTP information would not - disabling IP wouldprevent it and the other protocols from being displayed
To enabledisable protocols select the Enabled Protocols item from the Analyze menu Wire-shark will pop up the Enabled Protocols dialog box as shown in Figure 95 ldquoThe Enabled Proto-cols dialog boxrdquo
Figure 95 The Enabled Protocols dialog box
Customizing Wireshark
166
To disable or enable a protocol simply click on it using the mouse or press the space bar when theprotocol is highlighted Note that typing the first few letters of the protocol name when the EnabledProtocols dialog box is active will temporarily open a search text box and automatically select thefirst matching protocol name (if it exists)
Warning
You have to use the Save button to save your settings The OK or Apply buttons willnot save your changes permanently so they will be lost when Wireshark is closed
You can choose from the following actions
1 Enable All Enable all protocols in the list
2 Disable All Disable all protocols in the list
3 Invert Toggle the state of all protocols in the list
Customizing Wireshark
167
4 OK Apply the changes and close the dialog box
5 Apply Apply the changes and keep the dialog box open
6 Save Save the settings to the disabled_protos see Appendix A Files and Folders for details
7 Cancel Cancel the changes and close the dialog box
942 User Specified DecodesThe Decode As functionality let you temporarily divert specific protocol dissections This mightbe useful for example if you do some uncommon experiments on your network
Decode As is accessed by selecting the Decode As item from the Analyze menu Wireshark willpop up the Decode As dialog box as shown in Figure 96 ldquoThe Decode As dialog boxrdquo
Figure 96 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 Wireshark these settings willbe lost
1 Decode Decode packets the selected way
2 Do not decode Do not decode packets the selected way
Customizing Wireshark
168
3 LinkNetworkTransport Specify the network layer at which Decode As should take placeWhich of these pages are available depends on the content of the selected packet when this dia-log box is opened
4 Show Current Open a dialog box showing the current list of user specified decodes
5 OK Apply the currently selected decode and close the dialog box
6 Apply Apply the currently selected decode and keep the dialog box open
7 Cancel Cancel the changes and close the dialog box
943 Show User Specified DecodesThis dialog box shows the currently active user specified decodes
Figure 97 The Decode As Show dialog box
1 OK Close this dialog box
2 Clear Removes all user specified decodes
Customizing Wireshark
169
95 PreferencesThere are a number of preferences you can set Simply select the Preferences menu item from theEdit menu and Wireshark will pop up the Preferences dialog box as shown in Figure 98 ldquoThepreferences dialog boxrdquo with the User Interface page as default On the left side is a tree whereyou can select the page to be shown
Note
Preference settings are added frequently For a recent explanation of the preferencepages and their settings have a look at the Wireshark Wiki Preferences page at ht-tpwikiwiresharkorgPreferences
Warning
The OK or Apply button will not save the preference settings youll have to save thesettings by clicking the Save button
bull The OK button will apply the preferences settings and close the dialog
bull The Apply button will apply the preferences settings and keep the dialog open
bull The Save button will apply the preferences settings save the settings on the hard disk and keepthe dialog open
bull The Cancel button will restore all preferences settings to the last saved state
Figure 98 The preferences dialog box
Customizing Wireshark
170
96 Configuration ProfilesConfiguration Profiles can be used to configure and use more than one set of preferences and con-figurations Select the Configuration Profiles menu item from the Edit menu or simply pressShift-Ctrl-A and Wireshark will pop up the Configuration Profiles dialog box as shown in Fig-ure 99 ldquoThe configuration profiles dialog boxrdquo
Configuration files stored in the Profiles
bull Preferences (preferences)
bull Capture Filters (cfilters)
bull Display Filters (dfilters)
bull Coloring Rules (colorfilters)
bull Disabled Protocols (disabled_protos)
bull User Accessible Tables
bull Display Filter Macros (dfilter_macros)
bull K12 Protocols (k12_protos)
bull SCCP Users Table (sccp_users)
bull SMI Modules (smi_modules)
bull SMI Paths (smi_paths)
bull SNMP Users (snmp_users)
bull User DLTs Table (user_dlts)
Note
All other configurations are stored in the personal configuration folder and are com-mon to all profiles
Figure 99 The configuration profiles dialog box
Customizing Wireshark
171
New This button adds a new profile to the profiles list
Delete This button deletes the selected profile
Configuration Profiles You can select a configuration profile from this list (which willfill in the profile name in the fields down at the bottom of thedialog box)
Profile name You can change the name of the currently selected profile here
Note
The profile name will be used as a folder name inthe configured Personal configurations folder Ifadding multiple profiles with the same name onlyone profile will be created
Note
On Windows the profile name cannot start or endwith a period () and cannot contain any of the fol-lowing characters lt gt |
On Unix the profile name cannot contain the
Customizing Wireshark
172
character
OK This button saves all changes applies the selected profile andcloses the dialog
Apply This button saves all changes applies the selected profile andkeeps the dialog open
Cancel Close this dialog This will discard unsaved settings
Customizing Wireshark
173
97 User TableThe User Table editor is used for managing various tables in wireshark Its main dialog works verysimilarly to that of Section 93 ldquoPacket colorizationrdquo
Customizing Wireshark
174
98 Display Filter MacrosDisplay Filter Macros are a mechanism to create shortcuts for complex filters For example defininga display filter macro named tcp_conv whose text is ( (ipsrc == $1 and ipdst == $2 andtcpsrcport == $3 and tcpdstport == $4) or (ipsrc == $2 and ipdst == $1 and tcpsrcport ==$4 and tcpdstport == $3) ) would allow to use a display filter like$tcp_conv101121011312001400 instead of typing the whole filter
Display Filter Macros can be managed with a Section 97 ldquoUser Tablerdquo by selecting the DisplayFilter Macros menu item from the View Menu The User Table has the following fields
name The name of the macro
text The replacement text for the macro it uses $1 $2 $3 as the input arguments
Customizing Wireshark
175
99 Tektronix K12xx15 RF5 protocols TableThe Tektronix K12xx15 rf5 file format uses helper files (stk) to identify the various protocols thatare used by a certain interface Wireshark doesnt read these stk files it uses a table that helps itidentify which lowest layer protocol to use
Stk file to protocol matching is handled by an Section 97 ldquoUser Tablerdquo with the following fields
match A partial match for an stk filename the first match wins so if you have a specific caseand a general one the specific one must appear first in the list
protos This is the name of the encapsulating protocol (the lowest layer in the packet data) it canbe either just the name of the protocol (eg mtp2 eth_witoutfcs sscf-nni ) or the nameof the encapsulation protocol and the application protocol over it separated by a colon(eg sscopsscf-nni sscopalcap sscopnbap )
Customizing Wireshark
176
910 User DLTs protocol tableWhen a pcap file uses one of the user DLTs (147 to 162) wireshark uses this table to know whichprotocol(s) to use for each user DLT
This table is handled by an Section 97 ldquoUser Tablerdquo with the following fields
encap One of the user dlts
payload_proto This is the name of the payload protocol (the lowest layer in the packet data)(eg eth for ethernet ip for IPv4)
header_size If there is a header protocol (before the payload protocol) this tells which sizethis header is A value of 0 disables the header protocol
header_proto The name of the header protocol to be used (uses data as default)
trailer_size If there is a trailer protocol (after the payload protocol) this tells which sizethis trailer is A value of 0 disables the trailer protocol
trailer_proto The name of the trailer protocol to be used (uses data as default)
Customizing Wireshark
177
911 SNMP users TableWireshark uses this table to verify auhentication and to decrypt encrypted SNMPv3 packets
This table is handled by an Section 97 ldquoUser Tablerdquo with the following fields
engine_id If given this entry will be used only for packets whose engine id is this Thisfield takes an hexadecimal string in the form 0102030405
userName This is the userName When a single user has more than one password for dif-ferent SNMP-engines the first entry to match both is taken if you need a catchall engine-id (empty) that entry should be the last one
auth_model Which auth model to use (either MD5 or SHA1)
authPassword The authentication password Use xDD for unprintable charachters An hexa-decimal password must be entered as a sequence of xDD characters For ex-ample the hex passowrd 010203040506 must be entered asx01x02x03x04x05x06
priv_proto Which encryption algorithm to use (either DES or AES)
privPassword The privacy password Use xDD for unprintable charachters An hexadecimalpassword must be entered as a sequence of xDD characters For example thehex passowrd 010203040506 must be entered as x01x02x03x04x05x06
Customizing Wireshark
178
912 SCCP users TableWireshark uses this table to map specific protocols to a certain DPCSSN combination for SCCP
This table is handled by an Section 97 ldquoUser Tablerdquo with the following fields
ni An Integer representing the network indicator for which this association is valid
called_pc An range of integers representing the dpcs for which this association is valid
called_ssn An range of integers representing the ssns for which this association is valid
user The protocol that is carried over this association
Customizing Wireshark
179
Customizing Wireshark
180
Chapter 10 Lua Support in Wireshark101 Introduction
Wireshark has an embedded Lua interpreter Lua is a powerful light-weight programming languagedesigned for extending applications Lua is designed and implemented by a team at PUC-Rio thePontifical Catholic University of Rio de Janeiro in Brazil Lua was born and raised at Tecgraf theComputer Graphics Technology Group of PUC-Rio and is now housed at Luaorg Both Tecgrafand Luaorg are laboratories of the Department of Computer Science
In Wireshark Lua can be used to write dissectors and taps
Wiresharks Lua interpreter starts by loading initlua that is located in the global configuration dir-ectory of Wireshark Lua is disabled by default by setting the variable disable_lua to true ininitlua To enable lua the line that sets that variable must be removed or commented out
After loading initlua from the data directory if lua is enabled Wireshark will try to load a filenamed initlua in the users directory
The command line option -X lua_scriptltfileluagt can be used to load lua scripts as well
The Lua code will be executed once after all the protocols have being initialized and before readingany file
181
102 Example of Dissector written in Luado
local p_multi = Proto(multiMultiProto)
local vs_protos = [2] = mtp2[3] = mtp3[4] = alcap[5] = h248[6] = ranap[7] = rnsap[8] = nbap
local f_proto = ProtoFielduint8(multiprotocolProtocolbaseDECvs_protos)local f_dir = ProtoFielduint8(multidirectionDirectionbaseDEC [1] = incoming [0] = outgoing)local f_text = ProtoFieldstring(multitextText)
p_multifields = f_proto f_dir f_text
local data_dis = Dissectorget(data)
local protos = [2] = Dissectorget(mtp2)[3] = Dissectorget(mtp3)[4] = Dissectorget(alcap)[5] = Dissectorget(h248)[6] = Dissectorget(ranap)[7] = Dissectorget(rnsap)[8] = Dissectorget(nbap)[9] = Dissectorget(rrc)[10] = DissectorTableget(sctpppi)get_dissector(3) -- m3ua[11] = DissectorTableget(ipproto)get_dissector(132) -- sctp
function p_multidissector(bufpktroot)
local t = rootadd(p_multibuf(02))tadd(f_protobuf(01))tadd(f_dirbuf(11))
local proto_id = buf(01)uint()
local dissector = protos[proto_id]
if dissector ~= nil thendissectorcall(buf(2)tvb()pktroot)
elseif proto_id lt 2 thentadd(f_textbuf(2))-- pktcolsinfoset(buf(2buflen() - 3)string())
elsedata_discall(buf(2)tvb()pktroot)
end
end
local wtap_encap_table = DissectorTableget(wtap_encap)local udp_encap_table = DissectorTableget(udpport)
wtap_encap_tableadd(wtapUSER15p_multi)wtap_encap_tableadd(wtapUSER12p_multi)udp_encap_tableadd(7555p_multi)
end
Lua Support in Wireshark
182
103 Example of Listener written in Lua-- This program will register a menu that will open a window with a count of occurrences-- of every address in the capture
dolocal function menuable_tap()
-- Declare the window we will uselocal tw = TextWindownew(Address Counter)
-- This will contain a hash of counters of appereances of a certain addresslocal ips =
-- this is our taplocal tap = Listenernew()
function remove()-- this way we remove the listener than otherwise will remain running indifinitellytapremove()
end
-- we tell the window to call the remove() function when closedtwset_atclose(remove)
-- this function will be called once for each packetfunction tappacket(pinfotvb)
local src = ips[tostring(pinfosrc)] or 0local dst = ips[tostring(pinfodst)] or 0
ips[tostring(pinfosrc)] = src + 1ips[tostring(pinfodst)] = dst + 1
end
-- this function will be called once every few seconds to update our windowfunction tapdraw(t)
twclear()for ipnum in pairs(ips) do
twappend(ip t num n)end
end
-- this function will be called whenever a reset is needed-- eg when reloading the capture filefunction tapreset()
twclear()ips =
endend
-- using this function we register our fuction-- to be called when the user selects the Tools-gtTest-gtPackets menuregister_menu(TestPacketsmenuable_tap)
end
Lua Support in Wireshark
183
104 Wiresharks Lua API Reference ManualThis Part of the User Guide describes the Wireshark specific functions in the embedded Lua
1041 saving capture files
10411 Dumper
104111 Dumpernew(filename [filetype] [encap])
Creates a file to write packets Dumpernew_for_current() will probably be a better choice
1041111 Arguments
filename The name of the capture file to be created
filetype (optional) The type of the file to be created
encap (optional) The encapsulation to be used in the file to be created
1041112 Returns
The newly created Dumper object
1041113 Errors
bull not every filetype handles every encap
104112 dumperclose()
Closes a dumper
1041121 Errors
bull Cannot operate on a closed dumper
104113 dumperflush()
Writes all unsaved data of a dumper to the disk
104114 dumperdump(timestamp pseudoheader bytearray)
Dumps an arbitrary packet Note Dumperdump_current() will fit best in most cases
1041141 Arguments
timestamp The absolute timestamp the packet will have
pseudoheader The Pseudoheader to use
bytearray the data to be saved
104115 dumpernew_for_current([filetype])
Lua Support in Wireshark
184
Creates a capture file using the same encapsulation as the one of the cuurrent packet
1041151 Arguments
filetype (optional) The file type Defaults to pcap
1041152 Returns
The newly created Dumper Object
1041153 Errors
bull cannot be used outside a tap or a dissector
104116 dumperdump_current()
Dumps the current packet as it is
1041161 Errors
bull cannot be used outside a tap or a dissector
10412 PseudoHeader
A pseudoheader to be used to save captured frames
104121 PseudoHeadernone()
Creates a no pseudoheader
1041211 Returns
A null pseudoheader
104122 PseudoHeadereth([fcslen])
Creates an ethernet pseudoheader
1041221 Arguments
fcslen (optional) the fcs length
1041222 Returns
The ethernet pseudoheader
104123 PseudoHeaderatm([aal] [vpi] [vci] [channel] [cells] [aal5u2u][aal5len])
Creates an ATM pseudoheader
1041231 Arguments
aal (optional) AAL number
Lua Support in Wireshark
185
vpi (optional) VPI
vci (optional) VCI
channel (optional) Channel
cells (optional) Number of cells in the PDU
aal5u2u (optional) AAL5 User to User indicator
aal5len (optional) AAL5 Len
1041232 Returns
The ATM pseudoheader
104124 PseudoHeadermtp2()
Creates an MTP2 PseudoHeader
1041241 Returns
The MTP2 pseudoheader
1042 obtaining dissection data
10421 Field
A Field extractor to to obtain field values
104211 Fieldnew(fieldname)
Create a Field extractor
1042111 Arguments
fieldname The filter name of the field (eg ipaddr)
1042112 Returns
The field extractor
1042113 Errors
bull a Field extractor must be defined before Taps or Dissectors get called
104212 field__call()
obtain all values (see FieldInfo) for this field
1042121 Returns
All the values of this field
1042122 Errors
bull fields cannot be used outside dissectors or taps
Lua Support in Wireshark
186
10422 FieldInfo
An extracted Field
104221 fieldinfo__len()
Obtain the Length of the field
104222 fieldinfo__unm()
Obtain the Offset of the field
104223 fieldinfo__call()
Obtain the Value of the field
104224 fieldinfo__tostring()
the string representation of the field
104225 fieldinfo__eq()
checks whether lhs is within rhs
1042251 Errors
bull data source must be the same for both fields
104226 fieldinfo__le()
checks whether the end byte of lhs is before the end of rhs
104227 fieldinfo__lt()
checks whether the end byte of rhs is before the beginning of rhs
1042271 Errors
bull data source must be the same for both fields
104228 fieldinfoname
The name of this field
104229 fieldinfolabel
The string representing this field
1042210 fieldinfovalue
The value of this field
1042211 fieldinfolen
The length of this field
1042212 fieldinfooffset
Lua Support in Wireshark
187
The offset of this field
10423 Non Method Functions
104231 all_field_infos()
obtain all fields from the current tree
1042311 Errors
bull Cannot be called outside a listener or dissector
1043 GUI support
10431 TextWindow
Manages a text window
104311 TextWindownew([title])
Creates a new TextWindow
1043111 Arguments
title (optional) Title of the new window
1043112 Returns
The newly created TextWindow object
104312 textwindowset_atclose(action)
Set the function that will be called when the window closes
1043121 Arguments
action A function to be executed when the user closes the window
1043122 Returns
The TextWindow object
1043123 Errors
bull cannot be called for something not a TextWindow
104313 textwindowset(text)
Sets the text
1043131 Arguments
text The text to be used
Lua Support in Wireshark
188
1043132 Returns
The TextWindow object
1043133 Errors
bull cannot be called for something not a TextWindow
104314 textwindowappend(text)
Appends text
1043141 Arguments
text The text to be appended
1043142 Returns
The TextWindow object
1043143 Errors
bull cannot be called for something not a TextWindow
104315 textwindowprepend(text)
Prepends text
1043151 Arguments
text The text to be appended
1043152 Returns
The TextWindow object
1043153 Errors
bull cannot be called for something not a TextWindow
104316 textwindowclear()
Errases all text in the window
1043161 Returns
The TextWindow object
1043162 Errors
bull cannot be called for something not a TextWindow
Lua Support in Wireshark
189
104317 textwindowget_text()
Get the text of the window
1043171 Returns
The TextWindows text
1043172 Errors
bull cannot be called for something not a TextWindow
bull cannot be called for something not a TextWindow
104318 textwindowset_editable([editable])
Make this window editable
1043181 Arguments
editable (optional) A boolean flag defaults to true
1043182 Returns
The TextWindow object
1043183 Errors
bull cannot be called for something not a TextWindow
104319 textwindowadd_button(label function)
1043191 Arguments
label The label of the button
function The function to be called when clicked
1043192 Returns
The TextWindow object
1043193 Errors
bull cannot be called for something not a TextWindow
10432 Non Method Functions
104321 gui_enabled()
Checks whether the GUI facility is enabled
1043211 Returns
Lua Support in Wireshark
190
A boolean true if it is enabled false if it isnt
104322 register_menu(name action group)
Register a menu item in the Statistics menu
1043221 Arguments
name The name of the menu item
action The function to be called when the menu item is invoked
group The menu group into which the menu item is to be inserted
104323 new_dialog(title action )
Pops up a new dialog
1043231 Arguments
title Title of the dialogs window
action Action to be performed when OKd
A series of strings to be used as labels of the dialogs fields
1043232 Errors
bull at least one field required
bull all fields must be strings
104324 retap_packets()
Rescan all packets and just run taps - dont reconstruct the display
104325 copy_to_clipboard(text)
copy a string into the clipboard
1043251 Arguments
text The string to be copied into the clipboard
104326 open_capture_file(filename filter)
open and display a capture file
1043261 Arguments
filename The name of the file to be opened
filter A filter tgo be applied as the file gets opened
Lua Support in Wireshark
191
104327 set_filter(text)
set the main filter text
1043271 Arguments
text The filters text
104328 apply_filter()
apply the filter in the main filter box
104329 reload()
reload the current capture file
1043210 browser_open_url(url)
open an url in a browser
10432101 Arguments
url The url
1043211 browser_open_data_file(filename)
open an file in a browser
10432111 Arguments
filename The url
1044 post-dissection packet analysis
10441 Listener
A Listener is called once for every packet that matches a certain filter or has a certain tap It canread the tree the packets Tvb eventually the tapped data but it cannot add elements to the tree
104411 Listenernew([tap] [filter])
Creates a new Listener listener
1044111 Arguments
tap (optional) the name of this tap
filter (optional) a filter that when matches the tappacket function gets called (use nil tobe called for every packet)
1044112 Returns
The newly created Listener listener object
Lua Support in Wireshark
192
1044113 Errors
bull tap registration error
104412 listenerremove()
Removes a tap listener
104413 listenerpacket
A function that will be called once every packet matches the Listener listener filter functiontappacket(pinfotvbuserdata) end
104414 listenerdraw
A function that will be called once every few seconds to redraw the gui objects in tshark this funtionis called oly at the very end of the capture file function tapdraw(userdata) end
104415 listenerreset
A function that will be called at the end of the capture run function tapreset(userdata) end
1045 obtaining packet information
10451 Address
Represents an address
104511 Addressip(hostname)
Creates an Address Object representing an IP address
1045111 Arguments
hostname The address or name of the IP host
1045112 Returns
the Address object
104512 address__tostring()
1045121 Returns
The string representing the address
104513 address__eq()
compares two Addresses
104514 address__le()
compares two Addresses
104515 address__lt()
compares two Addresses
Lua Support in Wireshark
193
10452 Column
A Column in the packet list
104521 column__tostring()
1045211 Returns
A string representing the column
104522 columnclear()
Clears a Column
104523 columnset(text)
Sets the text of a Column
1045231 Arguments
text The text to which to set the Column
104524 columnappend(text)
Appends text to a Column
1045241 Arguments
text The text to append to the Column
104525 columnpreppend(text)
Prepends text to a Column
1045251 Arguments
text The text to prepend to the Column
10453 Columns
The Columns of the packet list
104531 columns__tostring()
1045311 Returns
The string Columns no real use just for debugging purposes
104532 columns__newindex(column text)
Sets the text of a specific column
1045321 Arguments
column the name of the column to set
Lua Support in Wireshark
194
text the text for the column
10454 Pinfo
Packet information
104541 pinfonumber
The number of this packet in the current file
104542 pinfolen
The length of the frame
104543 pinfocaplen
The captured length of the frame
104544 pinfoabs_ts
When the packet was captured
104545 pinforel_ts
Number of seconds passed since beginning of capture
104546 pinfodelta_ts
Number of seconds passed since the last captured packet
104547 pinfodelta_dis_ts
Number of seconds passed since the last displayed packet
104548 pinfovisited
Whether this packet hass been already visited
104549 pinfosrc
Source Address of this Packet
1045410 pinfodst
Destination Address of this Packet
1045411 pinfolo
lower Address of this Packet
1045412 pinfohi
higher Address of this Packet
1045413 pinfodl_src
Data Link Source Address of this Packet
1045414 pinfodl_dst
Lua Support in Wireshark
195
Data Link Destination Address of this Packet
1045415 pinfonet_src
Network Layer Source Address of this Packet
1045416 pinfonet_dst
Network Layer Destination Address of this Packet
1045417 pinfoptype
Type of Port of src_port and dst_port
1045418 pinfosrc_port
Source Port of this Packet
1045419 pinfodst_port
Source Address of this Packet
1045420 pinfoipproto
IP Protocol id
1045421 pinfocircuit_id
For circuit based protocols
1045422 pinfomatch
PortData we are matching
1045423 pinfocurr_proto
Which Protocol are we dissecting
1045424 pinfocolumns
Accesss to the packet list columns
1045425 pinfocols
Accesss to the packet list columns (equivalent to pinfocols)
1046 functions for writing dissectors
10461 Dissector
A refererence to a dissector used to call a dissector against a packet or a part of it
104611 Dissectorget(name)
Obtains a dissector reference by name
1046111 Arguments
name The name of the dissector
Lua Support in Wireshark
196
1046112 Returns
The Dissector reference
104612 dissectorcall(tvb pinfo tree)
Calls a dissector against a given packet (or part of it)
1046121 Arguments
tvb The buffer to dissect
pinfo The packet info
tree The tree on which to add the protocol items
10462 DissectorTable
A table of subdissectors of a particular protocol (eg TCP subdissectors like http smtp sip are ad-ded to table tcpport) Useful to add more dissectors to a table so that they appear in the DecodeAs dialog
104621 DissectorTablenew(tablename [uiname] [type])
Creates a new DissectorTable for your dissectors use
1046211 Arguments
tablename The short name of the table
uiname (optional) The name of the table in the User Interface (defaults to the name given)
type (optional) either FT_UINT or FT_STRING (defaults to FT_UINT32)
1046212 Returns
The newly created DissectorTable
104622 DissectorTableget(tablename)
Obtain a reference to an existing dissector table
1046221 Arguments
tablename The short name of the table
1046222 Returns
The DissectorTable
104623 dissectortableadd(pattern dissector)
Add a dissector to a table
1046231 Arguments
Lua Support in Wireshark
197
pattern The pattern to match (either an integer or a string depending on the tables type)
dissector The dissector to add (either an Proto or a Dissector)
104624 dissectortableremove(pattern dissector)
Remove a dissector from a table
1046241 Arguments
pattern The pattern to match (either an integer or a string depending on the tables type)
dissector The dissector to add (either an Proto or a Dissector)
104625 dissectortabletry(pattern tvb pinfo tree)
Try to call a dissector from a table
1046251 Arguments
pattern The pattern to be matched (either an integer or a string depending on the tables type)
tvb The buffer to dissect
pinfo The packet info
tree The tree on which to add the protocol items
104626 dissectortableget_dissector(pattern)
Try to obtain a dissector from a table
1046261 Arguments
pattern The pattern to be matched (either an integer or a string depending on the tables type)
1046262 Returns
The dissector handle if found
nil if not found
10463 Pref
A preference of a Protocol
104631 Prefbool(label default descr)
Creates a boolean preference to be added to a Protocols prefs table
1046311 Arguments
label The Label (text in the right side of the preference input) for this preference
default The default value for this preference
Lua Support in Wireshark
198
descr A description of what this preference is
104632 Prefuint(label default descr)
Creates an (unsigned) integer preference to be added to a Protocols prefs table
1046321 Arguments
label The Label (text in the right side of the preference input) for this preference
default The default value for this preference
descr A description of what this preference is
104633 Prefstring(label default descr)
Creates a string preference to be added to a Protocols prefs table
1046331 Arguments
label The Label (text in the right side of the preference input) for this preference
default The default value for this preference
descr A description of what this preference is
104634 Prefenum(label default descr enum radio)
Creates an enum preference to be added to a Protocols prefs table
1046341 Arguments
label The Label (text in the right side of the preference input) for this preference
default The default value for this preference
descr A description of what this preference is
enum enum
radio radio_button or combobox
104635 Prefrange(label default descr range max)
Creates a range preference to be added to a Protocols prefs table
1046351 Arguments
label The Label (text in the right side of the preference input) for this preference
default The default value for this preference
descr A description of what this preference is
range The range
Lua Support in Wireshark
199
max The maximum value
104636 Prefstext(label text)
Creates a static text preference to be added to a Protocols prefs table
1046361 Arguments
label The Label (text in the right side of the preference input) for this preference
text The static text
10464 Prefs
The table of preferences of a protocol
104641 prefs__newindex(name pref)
creates a new preference
1046411 Arguments
name The abbreviation of this preference
pref A valid but still unassigned Pref object
1046412 Errors
bull unknow Pref type
104642 prefs__index(name)
get the value of a preference setting
1046421 Arguments
name The abbreviation of this preference
1046422 Returns
the current value of the preference
1046423 Errors
bull unknow Pref type
10465 Proto
A new protocol in wireshark Protocols have more uses the main one is to dissect a protocol Butthey can be just dummies used to register preferences for other purposes
104651 Protonew(name desc)
Lua Support in Wireshark
200
1046511 Arguments
name The name of the protocol
desc A Long Text description of the protocol (usually lowercase)
1046512 Returns
The newly created protocol
104652 protodissector
the protocols dissector a function you define
104653 protofields
the Fields Table of this dissector
104654 protoget_prefs
the preferences of this dissector
104655 protoinit
the init routine of this dissector a function you define
104656 protoname
the name given to this dissector
10466 ProtoField
A Protocol field (to be used when adding items to the dissection tree)
104661 ProtoFieldnew(name abbr type [valuestring] [base] [mask][descr])
Creates a new field to be used in a protocol
1046611 Arguments
name Actual name of the field (the string that appears in the tree)
abbr Filter name of the field (the string that is used in filters)
type Field Type (FT_)
valuestring (optional) a ValueString object
base (optional) The representation BASE_
mask (optional) the bitmask to be used
descr (optional) The description of the field
1046612 Returns
The newly created ProtoField object
Lua Support in Wireshark
201
104662 ProtoFielduint8(abbr [name] [base] [valuestring] [mask] [desc])
1046621 Arguments
abbr abbreviated name of the field (the string used in filters)
name (optional) Actual name of the field (the string that appears in the tree)
base (optional) one of baseDEC baseHEX or baseOCT
valuestring (optional) a table containing the text that corresponds to the values
mask (optional) integer mask of this field
desc (optional) description of the field
1046622 Returns
a protofield item to be added to a ProtoFieldArray
104663 ProtoFielduint16(abbr [name] [base] [valuestring] [mask] [desc])
1046631 Arguments
abbr abbreviated name of the field (the string used in filters)
name (optional) Actual name of the field (the string that appears in the tree)
base (optional) one of baseDEC baseHEX or baseOCT
valuestring (optional) a table containing the text that corresponds to the values
mask (optional) integer mask of this field
desc (optional) description of the field
1046632 Returns
a protofield item to be added to a ProtoFieldArray
104664 ProtoFielduint24(abbr [name] [base] [valuestring] [mask] [desc])
1046641 Arguments
abbr abbreviated name of the field (the string used in filters)
name (optional) Actual name of the field (the string that appears in the tree)
base (optional) one of baseDEC baseHEX or baseOCT
valuestring (optional) a table containing the text that corresponds to the values
mask (optional) integer mask of this field
desc (optional) description of the field
1046642 Returns
Lua Support in Wireshark
202
a protofield item to be added to a ProtoFieldArray
104665 ProtoFielduint32(abbr [name] [base] [valuestring] [mask] [desc])
1046651 Arguments
abbr abbreviated name of the field (the string used in filters)
name (optional) Actual name of the field (the string that appears in the tree)
base (optional) one of baseDEC baseHEX or baseOCT
valuestring (optional) a table containing the text that corresponds to the values
mask (optional) integer mask of this field
desc (optional) description of the field
1046652 Returns
a protofield item to be added to a ProtoFieldArray
104666 ProtoFielduint64(abbr [name] [base] [valuestring] [mask] [desc])
1046661 Arguments
abbr abbreviated name of the field (the string used in filters)
name (optional) Actual name of the field (the string that appears in the tree)
base (optional) one of baseDEC baseHEX or baseOCT
valuestring (optional) a table containing the text that corresponds to the values
mask (optional) integer mask of this field
desc (optional) description of the field
1046662 Returns
a protofield item to be added to a ProtoFieldArray
104667 ProtoFieldint8(abbr [name] [base] [valuestring] [mask] [desc])
1046671 Arguments
abbr abbreviated name of the field (the string used in filters)
name (optional) Actual name of the field (the string that appears in the tree)
base (optional) one of baseDEC baseHEX or baseOCT
valuestring (optional) a table containing the text that corresponds to the values
mask (optional) integer mask of this field
desc (optional) description of the field
Lua Support in Wireshark
203
1046672 Returns
a protofield item to be added to a ProtoFieldArray
104668 ProtoFieldint16(abbr [name] [base] [valuestring] [mask] [desc])
1046681 Arguments
abbr abbreviated name of the field (the string used in filters)
name (optional) Actual name of the field (the string that appears in the tree)
base (optional) one of baseDEC baseHEX or baseOCT
valuestring (optional) a table containing the text that corresponds to the values
mask (optional) integer mask of this field
desc (optional) description of the field
1046682 Returns
a protofield item to be added to a ProtoFieldArray
104669 ProtoFieldint24(abbr [name] [base] [valuestring] [mask] [desc])
1046691 Arguments
abbr abbreviated name of the field (the string used in filters)
name (optional) Actual name of the field (the string that appears in the tree)
base (optional) one of baseDEC baseHEX or baseOCT
valuestring (optional) a table containing the text that corresponds to the values
mask (optional) integer mask of this field
desc (optional) description of the field
1046692 Returns
a protofield item to be added to a ProtoFieldArray
1046610 ProtoFieldint32(abbr [name] [base] [valuestring] [mask] [desc])
10466101 Arguments
abbr abbreviated name of the field (the string used in filters)
name (optional) Actual name of the field (the string that appears in the tree)
base (optional) one of baseDEC baseHEX or baseOCT
valuestring (optional) a table containing the text that corresponds to the values
mask (optional) integer mask of this field
desc (optional) description of the field
Lua Support in Wireshark
204
10466102 Returns
a protofield item to be added to a ProtoFieldArray
1046611 ProtoFieldint64(abbr [name] [base] [valuestring] [mask] [desc])
10466111 Arguments
abbr abbreviated name of the field (the string used in filters)
name (optional) Actual name of the field (the string that appears in the tree)
base (optional) one of baseDEC baseHEX or baseOCT
valuestring (optional) a table containing the text that corresponds to the values
mask (optional) integer mask of this field
desc (optional) description of the field
10466112 Returns
a protofield item to be added to a ProtoFieldArray
1046612 ProtoFieldframenum(abbr [name] [base] [valuestring] [mask][desc])
a frame number (for hyperlinks between frames)
10466121 Arguments
abbr abbreviated name of the field (the string used in filters)
name (optional) Actual name of the field (the string that appears in the tree)
base (optional) one of baseDEC baseHEX or baseOCT
valuestring (optional) a table containing the text that corresponds to the values
mask (optional) integer mask of this field
desc (optional) description of the field
10466122 Returns
a protofield item to be added to a ProtoFieldArray
1046613 ProtoFieldipv4(abbr [name] [desc])
10466131 Arguments
abbr abbreviated name of the field (the string used in filters)
name (optional) Actual name of the field (the string that appears in the tree)
desc (optional) description of the field
10466132 Returns
Lua Support in Wireshark
205
a protofield item to be added to a ProtoFieldArray
1046614 ProtoFieldipv6(abbr [name] [desc])
10466141 Arguments
abbr abbreviated name of the field (the string used in filters)
name (optional) Actual name of the field (the string that appears in the tree)
desc (optional) description of the field
10466142 Returns
a protofield item to be added to a ProtoFieldArray
1046615 ProtoFieldether(abbr [name] [desc])
10466151 Arguments
abbr abbreviated name of the field (the string used in filters)
name (optional) Actual name of the field (the string that appears in the tree)
desc (optional) description of the field
10466152 Returns
a protofield item to be added to a ProtoFieldArray
1046616 ProtoFieldfloat(abbr [name] [desc])
10466161 Arguments
abbr abbreviated name of the field (the string used in filters)
name (optional) Actual name of the field (the string that appears in the tree)
desc (optional) description of the field
10466162 Returns
a protofield item to be added to a ProtoFieldArray
1046617 ProtoFielddouble(abbr [name] [desc])
10466171 Arguments
abbr abbreviated name of the field (the string used in filters)
name (optional) Actual name of the field (the string that appears in the tree)
desc (optional) description of the field
10466172 Returns
Lua Support in Wireshark
206
a protofield item to be added to a ProtoFieldArray
1046618 ProtoFieldstring(abbr [name] [desc])
10466181 Arguments
abbr abbreviated name of the field (the string used in filters)
name (optional) Actual name of the field (the string that appears in the tree)
desc (optional) description of the field
10466182 Returns
a protofield item to be added to a ProtoFieldArray
1046619 ProtoFieldstrigz(abbr [name] [desc])
10466191 Arguments
abbr abbreviated name of the field (the string used in filters)
name (optional) Actual name of the field (the string that appears in the tree)
desc (optional) description of the field
10466192 Returns
a protofield item to be added to a ProtoFieldArray
1046620 ProtoFieldbytes(abbr [name] [desc])
10466201 Arguments
abbr abbreviated name of the field (the string used in filters)
name (optional) Actual name of the field (the string that appears in the tree)
desc (optional) description of the field
10466202 Returns
a protofield item to be added to a ProtoFieldArray
1046621 ProtoFieldubytes(abbr [name] [desc])
10466211 Arguments
abbr abbreviated name of the field (the string used in filters)
name (optional) Actual name of the field (the string that appears in the tree)
desc (optional) description of the field
10466212 Returns
Lua Support in Wireshark
207
a protofield item to be added to a ProtoFieldArray
1046622 ProtoFieldguid(abbr [name] [desc])
10466221 Arguments
abbr abbreviated name of the field (the string used in filters)
name (optional) Actual name of the field (the string that appears in the tree)
desc (optional) description of the field
10466222 Returns
a protofield item to be added to a ProtoFieldArray
1046623 ProtoFieldoid(abbr [name] [desc])
10466231 Arguments
abbr abbreviated name of the field (the string used in filters)
name (optional) Actual name of the field (the string that appears in the tree)
desc (optional) description of the field
10466232 Returns
a protofield item to be added to a ProtoFieldArray
1046624 ProtoFieldbool(abbr [name] [desc])
10466241 Arguments
abbr abbreviated name of the field (the string used in filters)
name (optional) Actual name of the field (the string that appears in the tree)
desc (optional) description of the field
10466242 Returns
a protofield item to be added to a ProtoFieldArray
10467 Non Method Functions
104671 register_postdissector(proto)
make a protocol (with a dissector) a postdissector It will be called for every frame after dissection
1046711 Arguments
proto the protocol to be used as postdissector
1047 adding information to the dissection tree
Lua Support in Wireshark
208
10471 TreeItem
TreeItems represent information in the packet-details pane A root TreeItem is passed to dissectorsas first argument
104711 treeitemadd()
Adds an child item to a given item returning the child tree_itemadd([proto_field | proto][tvbrange] [label] ) if the proto_field represents a numeric value (int uint or float) is to be treatedas a Big Endian (network order) Value
1047111 Returns
The child item
104712 treeitemadd_le()
Adds (and returns) an child item to a given item returning the child tree_itemadd([proto_field |proto] [tvbrange] [label] ) if the proto_field represents a numeric value (int uint or float) is to betreated as a Little Endian Value
1047121 Returns
The child item
104713 treeitemset_text(text)
sets the text of the label
1047131 Arguments
text The text to be used
104714 treeitemappend_text(text)
appends text to the label
1047141 Arguments
text The text to be appended
104715 treeitemset_expert_flags([group] [severity])
Sets the expert flags of the item
1047151 Arguments
group (optional) One of PI_CHECKSUM PI_SEQUENCE PI_RESPONSE_CODEPI_REQUEST_CODE PI_UNDECODED PI_REASSEMBLEPI_MALFORMED or PI_DEBUG
severity (optional) One of PI_CHAT PI_NOTE PI_WARN PI_ERROR
104716 treeitemadd_expert_info([group] [severity] [text])
Sets the expert flags of the item and adds expert info to the packet
Lua Support in Wireshark
209
1047161 Arguments
group (optional) One of PI_CHECKSUM PI_SEQUENCE PI_RESPONSE_CODEPI_REQUEST_CODE PI_UNDECODED PI_REASSEMBLEPI_MALFORMED or PI_DEBUG
severity (optional) One of PI_CHAT PI_NOTE PI_WARN PI_ERROR
text (optional) the text for the expert info
104717 treeitemset_generated()
marks the TreeItem as a generated field (with data infered but not contained in the packet)
104718 treeitemset_hidden()
should not be used
1048 functions for handling packet data
10481 ByteArray
104811 ByteArraynew([hexbytes])
creates a ByteArray Object
1048111 Arguments
hexbytes (optional) A string consisting of hexadecimal bytes like 00 B1 A2 or1a2b3c4d
1048112 Returns
The new ByteArray object
104812 bytearray__concat(first second)
concatenate two ByteArrays
1048121 Arguments
first first array
second second array
1048122 Returns
The new composite ByteArray
1048123 Errors
bull both arguments must be ByteArrays
104813 bytearrayprepend(prepended)
Lua Support in Wireshark
210
prepend a ByteArray to this ByteArray
1048131 Arguments
prepended array to be prepended
1048132 Errors
bull both arguments must be ByteArrays
104814 bytearrayappend(appended)
append a ByteArray to this ByteArray
1048141 Arguments
appended array to be appended
1048142 Errors
bull both arguments must be ByteArrays
104815 bytearrayset_size(size)
Sets the size of a ByteArray either truncating it or filling it with zeros
1048151 Arguments
size new size of the array
104816 bytearrayset_index(index value)
sets the value of an index of a ByteArray
1048161 Arguments
index the position of the byte to be set
value the char value to set [0-255]
104817 bytearrayget_index(index)
get the value of a byte in a ByteArray
1048171 Arguments
index the position of the byte to be set
1048172 Returns
Lua Support in Wireshark
211
The value [0-255] of the byte
104818 bytearraylen()
obtain the length of a ByteArray
1048181 Returns
The length of the ByteArray
104819 bytearraysubset(offset length)
obtain a segment of a ByteArray
1048191 Arguments
offset the position of the first byte
length the length of the segment
1048192 Returns
a ByteArray contaning the requested segment
a string contaning a representaion of the ByteArray
10482 Tvb
a Tvb represents the packets buffer It is passed as an argument to listeners and dissectors and canbe used to extract information (via TvbRange) from the packets data Beware that Tvbs are usableonly by the current listener or dissector call and are destroyed as soon as the listenerdissector re-turns so references to them are unusable once the function has returned To create a tvbrange thetvb must be called with offset and length as optional arguments ( the offset defaults to 0 and thelength to tvblen() )
104821 Tvbnew_real(bytearray name)
Creates a new Tvb from a bytearray (it gets added to the current frame too)
1048211 Arguments
bytearray The data source for this Tvb
name The name to be given to the new data-source
1048212 Returns
the created Tvb
104822 Tvbnew_subset(range)
creates a (sub)Tvb from using a TvbRange
1048221 Arguments
range the TvbRange from which to create the new Tvb
Lua Support in Wireshark
212
104823 tvb__tostring()
convert the bytes of a Tvb into a string to be used for debugging purposes as will be appended incase the string is too long
1048231 Returns
the string
104824 tvblen()
obtain the length of a TVB
1048241 Returns
the length of the Tvb
104825 tvboffset()
returns the raw offset (from the beginning of the source Tvb) of a sub Tvb
1048251 Returns
the raw offset of the Tvb
104826 tvb__call()
equivalent to tvbrange()
10483 TvbRange
a TvbRange represents an usable range of a Tvb and is used to extract data from the Tvb that gen-erated it TvbRanges are created by calling a tvb (eg tvb(offsetlength)) If the TvbRange span isoutside the Tvbs range the creation will cause a runtime error
104831 tvbrange([offset] [length])
creates a tvbr from this Tvb This is used also as the Tvb__call() metamethod
1048311 Arguments
offset (optional) The offset (in octets) from the begining of the Tvb Defaults to 0
length (optional) The length (in octets) of the range Defaults to until the end of the Tvb
1048312 Returns
the TvbRange
104832 tvbrangeget_uint()
get a Big Endian (network order) unsigned integer from a TvbRange The range must be 1 2 3 or 4octets long Theres no support yet for 64 bit integers
1048321 Returns
the unsigned integer value
104833 tvbrangeget_le_uint()
Lua Support in Wireshark
213
get a Little Endian unsigned integer from a TvbRange The range must be 1 2 3 or 4 octets longTheres no support yet for 64 bit integers
1048331 Returns
the unsigned integer value
104834 tvbrangeget_float()
get a Big Endian (network order) floating point number from a TvbRange The range must be 4 or 8octets long
1048341 Returns
the flaoting point value
104835 tvbrangeget_le_float()
get a Little Endian floating point number from a TvbRange The range must be 4 or 8 octets long
1048351 Returns
the flaoting point value
104836 tvbrangeget_ipv4()
get an IPv4 Address from a TvbRange
1048361 Returns
the IPv4 Address
104837 tvbrangeget_le_ipv4()
get an Little Endian IPv4 Address from a TvbRange
1048371 Returns
the IPv4 Address
104838 tvbrangeget_ether()
get an Ethernet Address from a TvbRange
1048381 Returns
the Ethernet Address
1048382 Errors
bull The range must be 6 bytes long
104839 tvbrangeget_string()
obtain a string from a TvbRange
1048391 Returns
the string
1048310 tvbrangeget_bytes()
Lua Support in Wireshark
214
obtain a ByteArray
10483101 Returns
the ByteArray
1048311 tvbrange__tostring()
converts the TvbRange into a string As the string gets truncated you should use this only for debug-ging purposes or if what you want is to have a truncated string in the format 6789AB
1048312 tvbrangetvb
The Tvb from which this TvbRange was generated
1048313 tvbrangelen
The length (in octets) of this TvbRange
1048314 tvbrangeoffset
The offset (in octets) of this TvbRange
1049 Utility Functions
10491 Dir
A Directory
104911 Diropen(pathname [extension])
usage for filename in Diropen(path) do end
1049111 Arguments
pathname the pathname of the directory
extension (optional) if given only file with this extension will be returned
1049112 Returns
the Dir object
104912 dir__call()
at every invocation will return one file (nil when done)
104913 dirclose()
closes the directory
10492 Non Method Functions
104921 format_date(timestamp)
Formats an absolute timestamp into a human readable date
1049211 Arguments
Lua Support in Wireshark
215
timestamp A timestamp value to convert
1049212 Returns
a string with the formated date
104922 format_time(timestamp)
Formats a relative timestamp in a human readable form
1049221 Arguments
timestamp a timestamp value to convert
1049222 Returns
a string with the formated time
104923 report_failure(text)
reports a failure to the user
1049231 Arguments
text message
104924 critical()
Will add a log entry with critical severity
1049241 Arguments
objects to be printed
104925 warn()
Will add a log entry with warn severity
1049251 Arguments
objects to be printed
104926 message()
Will add a log entry with message severity
1049261 Arguments
objects to be printed
104927 info()
Will add a log entry with info severity
Lua Support in Wireshark
216
1049271 Arguments
objects to be printed
104928 debug()
Will add a log entry with debug severity
1049281 Arguments
objects to be printed
104929 loadfile(filename)
Luas loadfile() has been modified so that if a file does not exist in the current directory it will lookfor it in wiresharks user and system directories
1049291 Arguments
filename name of the file to be loaded
1049210 dofile(filename)
Luas dofile() has been modified so that if a file does not exist in the current directory it will look forit in wiresharks user and system directories
10492101 Arguments
filename name of the file to be run
1049211 persconffile_path([filename])
10492111 Arguments
filename (optional) a filename
10492112 Returns
the full pathname for a file in the personal configuration directory
1049212 datafile_path([filename])
10492121 Arguments
filename (optional) a filename
10492122 Returns
the full pathname for a file in wiresharks configuration directory
1049213 register_stat_cmd_arg(argument [action])
Lua Support in Wireshark
217
Register a function to handle a -z option
10492131 Arguments
argumentaction (optional)
Lua Support in Wireshark
218
Lua Support in Wireshark
219
Appendix A Files and FoldersA1 Capture Files
To understand which information will remain available after the captured packets are saved to a cap-ture file its helpful to know a bit about the capture file contents
Wireshark uses the libpcap file format as the default format to save captured packets this format hasexisted for a long time and its pretty simple However it has some drawbacks its not extensibleand lacks some information that would be really helpful (eg being able to add a comment to apacket such as the problems start here would be really nice)
In addition to the libpcap format Wireshark supports several different capture file formatsHowever the problems described above also applies for these formats
A new capture file format PCAP Next Generation Dump File Format is currently under develop-ment which will fix these drawbacks However it still might take a while until the new file formatis ready and Wireshark can use it
A11 Libpcap File ContentsAt the start of each libpcap capture file some basic information is stored like a magic number toidentify the libpcap file format The most interesting information of this file start is the link layertype (Ethernet Token Ring )
The following data is saved for each packet
bull the timestamp with millisecond resolution
bull the packet length as it was on the wire
bull the packet length as its saved in the file
bull the packets raw bytes
A detailed description of the libpcap file format can be found at httpwikiwiresharkorgDevelop-mentLibpcapFileFormat
A12 Not Saved in the Capture FileProbably even more interesting for everyday Wireshark usage is to know the things that are notsaved in the capture file
bull current selections (selected packet )
bull name resolution information see Section 77 ldquoName Resolutionrdquo for details
Warning
The name resolution information is rebuilt each time Wireshark is restarted so thisinformation might even change when the capture file is reopened on the same ma-chine later
bull the number of packets dropped while capturing
bull packet marks set with EditMark Packet
220
bull time references set with EditTime Reference
bull the current display filter
bull
Files and Folders
221
A2 Configuration Files and FoldersWireshark uses a number of files and folders while it is running Some of these reside in the person-al configuration folder and are used to maintain information between runs of Wireshark while someof them are maintained in system areas
Tip
A list of the folders Wireshark actually uses can be found under the Folders tab in thedialog box shown when you select About Wireshark from the Help menu
The content format of the configuration files is the same on all platforms However to match thedifferent policies for Unix and Windows platforms different folders are used for these files
Table A1 Configuration files and folders overview
FileFolder Description UnixLinuxfolders
Windows folders
preferences Settings from thePreferences dialogbox
etcwire-sharkconf$HOMEwiresharkpreferences
WIRESHARKwiresharkconfAPPDATAWiresharkpreferences
recent Recent GUI set-tings (eg recentfiles lists)
$HOMEwiresharkrecent
APPDATAWiresharkrecent
cfilters Capture filters $HOMEwiresharkcfilters
WIRESHARKcfiltersAPPDATAWiresharkcfilters
dfilters Display filters $HOMEwiresharkdfilters
WIRESHARKdfiltersAPPDATAWiresharkdfilters
colorfilters Coloring rules $HOMEwiresharkcolorfilters
WIRESHARKcolorfiltersAPPDATAWiresharkcolorfilters
dis-abled_protos
Disabled proto-cols
$HOMEwiresharkdisabled_protos
WIRESHARKdisabled_protosAPPDATAWiresharkdisabled_protos
ethers Ethernet name res-olution
etcethers$HOMEwiresharkethers
WIRESHARKethersAPPDATAWiresharkethers
manuf Ethernet name res-olution
etcmanuf$HOMEwiresharkmanuf
WIRESHARKmanufAPPDATAWiresharkmanuf
hosts IPv4 and IPv6name resolution
etchosts$HOMEwiresharkhosts
WIRESHARKhostsAPPDATAWiresharkhosts
subnets IPv4 subnet nameresolution
etcsubnets$HOMEwiresharksubnets
WIRESHARKsubnetsAPPDATAWiresharksubnets
ipxnets IPX name resolu-tion
etcipxnets$HOMEwiresharkipxnets
WIRESHARKipxnetsAPPDATAWiresharkipxnets
plugins Plugin directories usrsharewire-sharkplugins
WIRESHARKpluginsltversiongtAPPDATAWiresharkplugins
Files and Folders
222
FileFolder Description UnixLinuxfolders
Windows folders
usrloc-alsharewire-sharkplugins$HOMEwiresharkplugins
temp Temporary files EnvironmentTMPDIR
Environment TMPDIR or TEMP
Windows folders
APPDATA points to the personal configuration folder eg CDocumentsand SettingsltusernamegtApplication Data (details can be found atSection A31 ldquoWindows profilesrdquo)
WIRESHARK points to the Wireshark program folder eg CProgramFilesWireshark
UnixLinux folders
The etc folder is the global Wireshark configuration folder The folder actually usedon your system may vary maybe something like usrlocaletc
$HOME is usually something like homeltusernamegt
preferenceswiresharkconf This file contains your Wireshark preferences including de-faults for capturing and displaying packets It is a simple textfile containing statements of the form
variable value
The settings from this file are read in at program start andwritten to disk when you press the Save button in the Prefer-ences dialog box
recent This file contains various GUI related settings like the mainwindow position and size the recent files list and such It is asimple 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 definedand saved It consists of one or more lines where each linehas the following format
ltfilter namegt ltfilter stringgt
The settings from this file are read in at program start andwritten to disk when you press the Save button in the Cap-ture Filters dialog box
dfilters This file contains all the display filters that you have defined
Files and Folders
223
and saved It consists of one or more lines where each linehas the following format
ltfilter namegt ltfilter stringgt
The settings from this file are read in at program start andwritten to disk when you press the Save button in the Dis-play Filters dialog box
colorfilters This file contains all the color filters that you have definedand saved It consists of one or more lines where each linehas the following format
ltfilter namegtltfilter stringgt[ltbg RGB(16-bit)gt][ltfg RGB(16-bit)gt]
The settings from this file are read in at program start andwritten to disk when you press the Save button in the Color-ing Rules dialog box
disabled_protos Each line in this file specifies a disabled protocol name Thefollowing are some examples
tcpudp
The settings from this file are read in at program start andwritten to disk when you press the Save button in the En-abled Protocols dialog box
ethers When Wireshark is trying to translate Ethernet hardware ad-dresses to names it consults the files listed in Table A1ldquoConfiguration files and folders overviewrdquo If an address isnot found in etcethers Wireshark looks in$HOMEwiresharkethers
Each line in these files consists of one hardware address andname separated by whitespace The digits of hardware ad-dresses are separated by colons () dashes (-) or periods()The following are some examples
ff-ff-ff-ff-ff-ff Broadcastc0-00-ff-ff-ff-ff TR_broadcast002b08934ba1 Freds_machine
The settings from this file are read in at program start andnever written by Wireshark
manuf Wireshark uses the files listed in Table A1 ldquoConfigurationfiles and folders overviewrdquo to translate the first three bytes ofan Ethernet address into a manufacturers name This file hasthe same format as the ethers file except addresses are threebytes long
An example is
000001 Xerox XEROX CORPORATION
Files and Folders
224
The settings from this file are read in at program start andnever written by Wireshark
hosts Wireshark uses the files listed in Table A1 ldquoConfigurationfiles and folders overviewrdquo to translate IPv4 and IPv6 ad-dresses into names
This file has the same format as the usual etchosts file onUnix systems
An example is
Comments must be prepended by the sign19216801 homeserver
The settings from this file are read in at program start andnever written by Wireshark
subnets Wireshark uses the files listed in Table A1 ldquoConfigurationfiles and folders overviewrdquo to translate an IPv4 address into asubnet name If no exact match from the hosts file or fromDNS is found Wireshark will attempt a partial match for thesubnet of the address
Each line of this file consists of an IPv4 address a subnetmask length separated only by a and a name separated bywhitespace While the address must be a full IPv4 addressany values beyond the mask length are subsequently ignored
An example is
Comments must be prepended by the sign1921680024 ws_test_network
A partially matched name will be printed as subnet-nameremaining-address For example 19216801 underthe subnet above would be printed as ws_test_network1 ifthe mask length above had been 16 rather than 24 the printedaddress would be ws_test_network01
The settings from this file are read in at program start andnever written by Wireshark
ipxnets Wireshark uses the files listed in Table A1 ldquoConfigurationfiles and folders overviewrdquo to translate IPX network numbersinto names
An example is
C0A82C00 HRc0-a8-1c-00 CEO0000BEEF IT_Server1110f FileServer3
The settings from this file are read in at program start andnever written by Wireshark
plugins folder Wireshark searches for plugins in the directories listed in Ta-ble A1 ldquoConfiguration files and folders overviewrdquo They are
Files and Folders
225
searched in the order listed
temp folder If you start a new capture and dont specify a filename for itWireshark uses this directory to store that file see Sec-tion 46 ldquoCapture files and file modesrdquo
Files and Folders
226
A3 Windows foldersHere 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 Wireshark dialog
A31 Windows profilesWindows uses some special directories to store user configuration files which define the user pro-file This can be confusing as the default directory location changed from Windows version to ver-sion and might also be different for English and internationalized versions of Windows
Note
If youve upgraded to a new Windows version your profile might be kept in the formerlocation so the defaults mentioned here might not apply
The following guides you to the right place where to look for Wiresharks profile data
Vista CUsersltusernamegtAppDataRoamingWireshark
XP2000 CDocuments and Set-tingsltusernamegtApplication Data Docu-ments and Settings and Application Data might be interna-tionalized
NT 4 (no longer supported byWireshark)
CWINNTProfilesltusernamegtApplicationDataWireshark
ME98 - with enabled user pro-files (no longer supported byWireshark)
In Windows ME and 98 you can enable separate user profilesIn that case something likeCwindowsProfilesltusernamegtApplication DataWireshark is used
ME9895 (no longer supportedby Wireshark)
The default in Windows ME9895 is all users work with thesame profile which is located atCwindowsApplication DataWireshark
A32 Windows VistaXP2000NT roaming profilesThe following will only be applicable if you are using roaming profiles This might be the case ifyou work in a Windows domain environment (used in company networks) The configurations of allprograms you use wont be saved on the local hard drive of the computer you are currently workingon but on the domain server
As Wireshark is using the correct places to store its profile data your settings will travel with you ifyou logon to a different computer the next time
There is an exception to this The Local Settings folder in your profile data (typically somethinglike CDocuments and SettingsltusernamegtLocal Settings) will not be trans-ferred to the domain server This is the default for temporary capture files
A33 Windows temporary folderWireshark uses the folder which is set by the TMPDIR or TEMP environment variable This vari-
Files and Folders
227
able will be set by the Windows installer
Vista XXX - could someone give information about this
XP2000 CDocuments and SettingsltusernamegtLocal SettingsTemp
NT 4 CTEMP
Files and Folders
228
Files and Folders
229
Appendix B Protocols and ProtocolFields
Wireshark distinguishes between protocols (eg tcp) and protocol fields (eg tcpport)
A comprehensive list of all protocols and protocol fields can be found at ht-tpwwwwiresharkorgdocsdfref
230
Appendix C Wireshark MessagesWireshark provides you with additional information generated out of the plain packet data or it mayneed to indicate dissection problems Messages generated by Wireshark are usually placed in [] par-entheses
C1 Packet List MessagesThese messages might appear in the packet list
C11 [Malformed Packet]Malformed packet means that the protocol dissector cant dissect the contents of the packet any fur-ther There can be various reasons
bull Wrong dissector Wireshark erroneously has chosen the wrong protocol dissector for this pack-et This will happen eg if you are using a protocol not on its well known TCP or UDP portYou may try Analyze|Decode As to circumvent this problem
bull Packet not reassembled The packet is longer than a single frame and it is not reassembled seeSection 76 ldquoPacket Reassemblingrdquo for further details
bull Packet is malformed The packet is actually wrong (malformed) meaning that a part of thepacket is just not as expected (not following the protocol specifications)
bull Dissector is buggy The corresponding protocol dissector is simply buggy or still incomplete
Any of the above is possible Youll have to look into the specific situation to determine the reasonYou could disable the dissector by disabling the protocol on the Analyze menu and check howWireshark displays the packet then You could (if its TCP) enable reassembly for TCP and the spe-cific dissector (if possible) in the Edit|Preferences menu You could check the packet contents your-self by reading the packet bytes and comparing it to the protocol specification This could reveal adissector bug Or you could find out that the packet is indeed wrong
C12 [Packet size limited during capture]The packet size was limited during capture see Limit each packet to n bytes at the Section 45ldquoThe Capture Options dialog boxrdquo While dissecting the current protocol dissector was simplyrunning out of packet bytes and had to give up Theres nothing else you can do now except to re-peat the whole capture process again with a higher (or no) packet size limitation
231
C2 Packet Details MessagesThese messages might appear in the packet details
C21 [Response in frame 123]The current packet is the request of a detected requestresponse pair You can directly jump to thecorresponding response packet just by double clicking on this message
C22 [Request in frame 123]Same as Response in frame 123 above but the other way round
C23 [Time from request 0123 seconds]The time between the request and the response packets
C24 [Stream setup by PROTOCOL (frame 123)]The session control protocol (SDP H225 etc) message which signaled the creation of this sessionYou can directly jump to the corresponding packet just by double clicking on this message
Wireshark Messages
232
Wireshark Messages
233
Appendix D Related command linetoolsD1 Introduction
Besides the Wireshark GUI application there are some command line tools which can be helpful fordoing some more specialized things These tools will be described in this chapter
234
D2 tshark Terminal-based WiresharkTShark is a terminal oriented version of Wireshark designed for capturing and displaying packetswhen an interactive user interface isnt necessary or available It supports the same options as wire-shark For more information on tshark see the manual pages (man tshark)
Related command line tools
235