Home

Wireshark - 0.99.7 User Guide

Contents

1. e Use the latest SVN sources or alike It s a good idea to work with the same sources that are used by the other developer s this makes it usually much easier to apply your patch For inform ation about the different ways to get the sources see Section 3 3 Obtain the Wireshark sources e Update your SVN sources just before making a patch For the same reasons as the previous point e Doa make clean before generating the patch This removes a lot of unneeded intermediate files like object files which can confuse the diff tool generating a lot of unneeded stuff which you have to remove by hand from the patch again e Find a good descriptive filename for your patch Think a moment to find a proper name for your patch file Often a filename like wireshark diff is used which isn t really helpful if keeping several of these files and find the right one later For example If you want to commit changes to the datatypes of dissector foo a good filename might be packet foo datatypes diff e Don t put unrelated things into one large patch A few smaller patches are usually easier to apply but also don t put every changed line into a separate patch Remove any parts of the patch not related to the changes you want to submit You can use a text editor for this A common example for win32 developers are the differences in your private config nmake file In general making it easier to understand and apply your patch by
2. ss eseesseresseerrsrerrrererrrrrese 31 3 9 Contribute your changes sseesssesserrrssrerrsrrerreresrrresrreersrrerrereseene 32 3 9 1 What is a diff file a patch seeseeseeessenenessseresssresesrererereresse 32 3 9 2 Generate a Patch arer ndn AE E EPES EEE EE EET 33 3 9 3 Some tips for a good patch sessssseessesrsseerrsrrrrrrresrrererrerrsreee 34 394 Code Requirements assoi e E ENEE 34 3 9 5 Sending your patch for inclusion cece cece cece eee e eee eeeeeenes 35 3 10 Apply a patch from someone else 2 0 0 0 ee eee ects ce eece ence eeeeeeeeeeenees 37 3 10 1 Using pateh isc e esc5 0 ees Stee be s desse guegeasdseesesenyeesseroebeaass 37 3 10 2 CVS ditt obsolete sieis a eramen ie 37 3 11 Add a new file to the Subversion repository cece eee eee coerce eee 39 3 12 Binary packagin s cssees nodra nesr Rap eetsendeshota ngs se SEES ES EPOR RPTP 40 3 12 1 Debian deb packages 200 00 cece ee cece eee cence eeeeeeeeeeea teen es 40 3 12 2 Red Hat rpm packages 2s0ic5 csscssedcseedeenesesesenoensoadesnedeenses 40 3 12 3 W032 NSIS sexe installer sr Seoce yep a Eora spentaecsepen eee 40 4 TOO Relerenees sechset on ECE AA aeck so E tls ete ated eee Sabet oes 43 AN Introduction as hace svoeth as dase Eae eE a E de taue sashes EE EES ees 43 AD Wid 2 Cy SWIM cies a here a Sos othe a dea age Naren Saat eT 44 4 2 1 Add Update Remove Cygwin Packages 00 00 00 cceeeseeeeeee
3. Visual Studio 2008 Ex press Edition Code Name Orcas After correct installation of the toolchain typing at the command line prompt cmd exe gt cl should result in something like Microsoft R 32 bit C C Optimizing Compiler Version 12 00 8804 for 80x86 Copyright C Microsoft Corp 1984 1998 All rights reserved usage cl option filename link linkoption However the version string may vary nmake exe Make nmake is part of the toolchain packages described above Instead of using the workspace dsw and projects dsp files the traditional nmake makefiles are used This has one main reason it makes it much easier to maintain changes simultaneously with the GCC toolchain makefile am files as both file formats are similar However as no Visual Studio workspace project files are available this makes it hard to use the Visual Studio IDE e g for using the integrated debugging feature After correct installation typing at the command line prompt cmd exe gt nmake should result in something like Microsoft R Program Maintenance Utility Version 6 00 9782 0 Copyright C Microsoft Corp 1988 1998 All rights reserved NMAKE fatal error U1064 MAKEFILE not found and no target specified Stop However the version string may vary Documentation on nmake can be found at Microsoft MSDN link exe Linker XXX add info here C Runtime Redistributable files Please note
4. As the requirements for the GLib GTK libraries have increased in the past the required additional libraries depend on the GLib GTK versions you have The 1 x versions only needed GLib GDK GTK 4 while the 2 x versions require all mentioned libs Unix The GLib GTK libraries are available for many unix like platforms and cygwin If these libraries aren t already installed and also aren t available as a package for your platform you can get them at http www gtk org Win32 MSVC You can get the latest version at http www gimp org 7Etm1 gimp win32 downloads html 73 Library Reference 5 5 Net SNMP optional Various tools relating to the Simple Network Management Protocol 5 5 1 Unix If this library isn t already installed or available as a package for your platform you can get it at ht tp sourceforge net projects net snmp 5 5 2 Win32 MSVC Wireshark uses the source Net SNMP distribution at http sourceforge net projects net snmp lib snmp is compiled with the libsnmp Win32 Release project using MSVC 6 0 A file called README wireshark has been placed in the net snmp zip archive at http anonsvn wireshark org wireshark win32 libs trunk packages describing the changes in more detail 74 Library Reference 5 6 GNU adns optional Advanced easy to use asynchronous capable DNS client library and utilities 5 6 1 Unix If this library isn t already installed or avail
5. Part Il Wireshark Development incomplete Part I Wireshark Build Environment The first part describes how to set up the tools libraries and source needed to generate Wireshark and how to do some typical development tasks Part II Wireshark Development The second part describes how the Wireshark sources are structured and how to change the sources e g adding a new dissector Chapter 6 How Wireshark Works 6 1 Introduction This chapter will give you a short overview of how Wireshark works How Wireshark Works 6 2 Overview The following will give you a simplified overview of Wiresharks function blocks Figure 6 1 Wireshark function blocks Wireshark GTK 1 2 Protocol Tree e peeeeeeeeererererererreret e Dissectors Epan Hi Plugins i E Win libpcap The function blocks in more detail GTK 1 2 Handling of all user input output all windows dialogs and such Source code can be found in the gtk directory 88 How Wireshark Works Core Epan Capture Wiretap Win libpcap not part of the Wireshark package Main glue code that holds the other blocks together Source code can be found in the root directory Ethereal Packet ANalyzer XXX is this correct the packet analyzing engine Source code can be found in the epan dir ectory e Protocol Tree Keep data of the capture file protocol in formation e Dissectors The
6. It may take several minutes for committed changes to appear in the public repository so please be patient for a few minutes if you desperately need a code change that was commited to the repository very recently The web interface to the Subversion repository If you need a quick look at the Wireshark source code you will only need a Web browser A simple view on the latest developer version can be found at http anonsvn wireshark org wireshark trunk A comprehensive view of all source versions e g including the capability to show differences between versions is available at 22 Work with the Wireshark sources http anonsvn wireshark org viewvc viewvc cgi Of special interest might be the subdirectories e trunk the very latest source files e releases the source files of all released versions 23 Work with the Wireshark sources 3 3 Obtain the Wireshark sources 3 3 1 3 3 2 3 3 3 There are several ways to obtain the sources from Wireshark s Subversion server Anonymous Subversion access is recommended It can make your life much easier compared to updating your source tree by using any of the zip file methods mentioned below Subversion handles merging of changes into your personal source tree in a very comfortable and quick way So you can update your source tree several times a day without much effort E Keep your sources up to date The following ways to retrieve the W
7. The GTK library Wireshark is based on the GTK toolkit see http www gtk org for details GTK is designed to hide the details of the underlying GUI in a platform independent way As this is appreciated for a multi platform tool this has some drawbacks as it will result in a somewhat non native look and feel GTK is available for a lot of different platforms including but not limited to Unix Linux Mac OS X and Win32 It s the foundation of the famous GNOME desktop so the future development of GTK should be certain GTK is implemented in plain C as is Wireshark itself and available under the LGPL Lesser General Public License being free to used by commercial and noncommercial applications There are other similar toolkits like Qt wxwidgets which could also be used for Wireshark There s no one and only reason for or against any of these toolkits However the decision towards GTK was made a long time ago At the time this document is written there are two major GTK versions available 10 2 1 GTK Version 1 x GTK 1 x was the first major release Today there are 1 2 x and 1 3 x versions in the wild with only very limitted differences in the API Advantages compared to GTK 2 x e available on a lot of different platforms e very stable as it s matured for quite a while now Disadvantages e the look and feel is a bit old fashioned e not recommended for future developments GTK 1 x depends on the following li
8. diff c or diff u line and try to patch dlnames c in the directory you re in rather than in the 37 Work with the Wireshark sources missing subdirectory For cvs diff c or cvs diff u diffs there s a Python script cvsdiff fix py in the tools directory in the Wireshark source tree it will fix up those lines in cvs diff output It reads its standard input by default or can be given a file name on the command line and writes to the standard output so if you re typing at a command interpreter that does piping you could do something such as python tools cvsdiff py patchfile patch p0 to use patchfile You might be able to leave the python out of the command line on many UN Xes svn diff doesn t produce a diff c or diff u line so its output doesn t have that problem Regu lar diff c or diff u output also shouldn t have that problem 38 Work with the Wireshark sources 3 11 Add a new file to the Subversion repository The usual way to commit new files is described in Section 3 9 Contribute your changes However the following might be of interest for the normal developer as well Note This action is only possible allowed by the Wireshark core developers who have write access to the Subversion repository It is put in here to have all information in one place If you as a core developer need to add a file to the SVN repository then you need to perform the
9. 106 Packet dissection Fr amp hf_foo_endflag FOO PDU End Flags foo flags end FT_BOOLEAN 8 NULL FOO_END_FLAG NULL HFILL amp hf_foo_priorityflag FOO PDU Priority Flags foo flags priority FT_BOOLEAN 8 NULL FOO_PRIORITY_FLAG NULL HFILL hy foo_tree hf_foo_flags tvb offset 1 FALSE foo_tree hf_foo_startflag tvb offset 1 FALSE foo_tree hf_foo_endflag tvb offset 1 FALSE foo_tree hf_foo_priorityflag tvb offset 1 FALSE offset 1 proto_tree_add_item proto_tree_add_item proto_tree_add_item proto_tree_add_item Some things to note here For the flags as each bit is a different flag we use the type FT_BOOLEAN as the flag is either on or off Second we include the flag mask in the 7th field of the data which allows the system to mask the relevant bit We ve also changed the 5th field to 8 to indicate that we are looking at an 8 bit quantity when the flags are extracted Then finally we add the extra constructs to the dissection routine Note we keep the same offset for each of the flags This is starting to look fairly full featured now but there are a couple of other things we can do to make things look even more pretty At the moment our dissection shows the packets as Foo Pro tocol which whilst correct is a little uninformative We can enhance this by adding a little more de tail First let s get hold of the actual value of the protocol type We c
10. 2 Coding styleguides The coding styleguides for Wireshark can be found in the Code style section of the file doc README developer 95 Introduction 7 3 The GLib library Glib is used as a basic platform abstraction library it s not related to GUI things To quote the Glib documentation GLib is a general purpose utility library which provides many useful data types macros type conversions string utilities file utilities a main loop abstraction and so on It works on many UNIX like platforms Windows OS 2 and BeOS GLib is released under the GNU Library General Public License GNU LGPL GLib contains lot s of useful things for platform independent development See http de veloper gnome org doc API 2 0 glib index html for details about GLib 96 Introduction 97 Chapter 8 Packet capturing XXX this chapter has to be reviewed and extended 8 1 How to add a new capture type to libpcap The following is an excerpt from a developer mailing list mail about adding ISO 9141 and 14230 simple serial line card diagnostics to Wireshark For libpcap the first thing you d need to do would be to get DLT_ values for all the link layer proto cols you d need If ISO 9141 and 14230 use the same link layer protocol they might be able to share a DLT_ value unless the only way to know what protocols are running above the link layer is to know which link layer protocol is being used
11. GNU adns optional eeii iie oi e E E AEE EEE Ta 75 9 6 15 UNIX tos cc5ccsiesvantia seahorse siawtag ee a IE ES e G 75 5 6 2 Wn32 MSVC sprees errire ced sinvoceccteecee esas EESE VEES CETE EEVEE VT kEi 75 31 PERE optional raisen aema aa NRE REA ts pak Gens E ENRE eee 76 DUT Lic UMIK errre r E E E V EEEE SESS 76 3 7 2 Wi32 MSV O r eea E E EE E iste Na GEEET 76 X9 ZD OptOnal orenen ansaan te aee E EEEE EEA EAS ESEE 71 JSk UNIX Sts et E Ea EE A S EEE N EEN N EAEN 77 9 0223 Win32 MS VO oc a oe itecten E Saceatouel se cau NEA E aren 77 5 9 libpcap WinPcap optional 2 0 0 0 eee ceeeceeece ceca eece een eeneeneeennees 78 5 9 1 Wi xs DP Cap s cs Pics vaten aunwes OE sey eta E EE ARS E 78 5 9 2 Win32 MS VG WinPcap seinere i an nee ne e 78 510 Gnu TLS Optional 0525 eeen aaeeea a as dea a EE E E EAE NE 79 SAKON ER MIX E E EE 79 5 10 2 WM32 MSV C eree cae sass oes sperra po aS betas ge SEEE IOE SENES 79 S11 Gerypt pti al ssor arne ene na EEE E ES 80 SALT UNR 5502 oi oaae a E a aE EEEE G 80 511 2 Win 2 MS VO aseo e E EE EE EE E ESETE EEEE EEEE 80 X 12 Kerberos optional mer eain aaa AR o E NELES EPESA ani 81 S12 WMI Koss 5 ce uscm dees need tes deny iser ss That a e aan besteuviaeauream ats ehanttc 81 D2 12 2 Win3 2 MSNG ouvert et E ek ie EN eta des Seedolieace beh ages 81 91 3 LL UAGCOPuOnal ice cacccsee nad oveye cones onetedete newness peetigeseseteeseeteeomed veneer ty 82 DSA UM D E E AE E aodat hee Moers siet
12. GTK_MAJOR_VERSION gt 2 else endif 10 2 4 GTK resources on the web You can find several resources about GTK First of all have a look at http www gtk org as this will be the first place to look at If you want to develop GTK related things for Wireshark the most important place might be the GTK API docu 122 User Interface mentation at http gtk org api Several mailing lists are available about GTK development see http gtk org mailinglists html the gtk app devel list may be your friend There s no Win32 specific GTK mailing list If you want to post a Win32 specific problem e g a problem in the GtkFileChooser dialog and you are sure that it s really Win32 specific you could send it to GIMPwin users at http www gimp org mail lists html As it s often done wrong You should post a mail to help the developers there instead of only complaining Posting such a thing like I don t like your dialog it looks ugly won t be of much help You might think about what you dislike and describe why you dislike it and provide a sugges tion for a better way 123 User Interface 10 3 GUI Reference documents Although the GUI development of Wireshark is platform independent the Wireshark development team tries to follow the GNOME Human Interface Guidelines HIG where appropriate This is the case because both GNOME and Wireshark are based on the GTK toolkit and the GNOME HIG is excellently written a
13. GtkTextView GtkLabel GtkEntry and other widgets that display text e ATK ATK is the Accessibility Toolkit It provides a set of generic interfaces allowing accessib ility technologies to interact with a graphical user interface For example a screen reader uses ATK to discover the text in an interface and read it to blind users GTK widgets have built in support for accessibility using the ATK framework e GdkPixbuf This is a small library which allows you to create GdkPixbuf pixel buffer ob jects from image data or image files Use a GdkPixbuf in combination with GtkImage to dis play images e GDK GDK is the abstraction layer that allows GTK to support multiple windowing systems GDK provides drawing and window system facilities on X11 Windows and the Linux frame buffer device XXX include Wireshark GTK2 screenshot 10 2 3 Compatibility between 1 x and 2 x The GTK library itself defines some values which makes it easy to distinguish between the versions e g GITK_MAJOR_VERSION GTK_MINOR_VERSION will be set to the GTK version at com pile time somewhere inside the gtk h headers There are some common compatibility issues in Wireshark between the two versions Most of them the more simple ones are collected in gtk compat_macros h and can be used in an version independent manner However there are major differences between the two versions making it necessary to distinguish between them like i
14. The following is not legal advice ask your preferred lawyer instead It s the authors view but this view might be wrong Depending on the Microsoft compiler version you use some binary files coming from Microsoft might be required to be installed on Windows machine to run Wireshark On a developer machine the compiler setup installs these files so they are available but they might not be available on a user machine This is especially true for the C runtime DLL msver dll which contains the implementation of ANSI and alike functions e g fopen malloc The DLL is named like msvcr lt version gt dll an abbreviation for MicroSoft Visual C Runtime For Wireshark to work this DLL must be available 51 Tool Reference on the users machine MSVC6 was using msvert dll which is already available on all recent windows systems no need to redistribute anything Starting with MSVC7 it is necessary to ship the C runtime DLL msver lt version gt dll together with the application installer somehow as that DLL is possibly not available on the target system Note The files to redistribute must be mentioned in the redist txt file of the compiler pack age otherwise it can t be legally redistributed by third parties like us The following MSDN links are recommended for the interested reader e Redistributing Visual C Files 1 e How to Deploy using XCopy 1 Redistribution of the shared C runtime compone
15. There is NO warranty not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE However the version string may vary 46 4 4 Microsoft compiler toolchain Win32 Tool Reference native To compile Wireshark on Windows using the Microsoft C C compiler you ll need 4 4 1 1 C compiler cl exe 2 Linker link exe 3 Make nmake exe 4 C runtime headers and libraries e g stdio h msvert lib 5 Windows platform headers and libraries e g windows h WSock372 lib 6 HTML help headers and libraries htmlhelp h htmlhelp lib Toolchain Package Alternatives The Microsoft Visual C 2005 Express Edition is recommended to compile Wireshark it s free as in beer and gives by far the best development comfort compared to the other free packages However you might already have a different Microsoft C compiler installed With the following dif ferences to the recommendations it s possible to use it as well Compiler Package IDE Debugger Publicly available Platform SDK required con fig nmake MS VC_VARIA NT set compiler PATH and alike settings with Remarks 47 Tool Reference Visual Stu Yes Commercial MSVC6 Microsoft dio 6 0 1 Visual Stu dio VC98 Bi n vcvars32 b at Visual Stu Yes Commercial MSVC2002 Microsoft dio NET 1 Visual Stu 2002 dio NET Vc7 bi n vcevars32 b at N
16. Work with the Wireshark sources other files in the root directory 28 Work with the Wireshark sources 3 6 Run generated Wireshark Tip AS An already installed Wireshark may interfere with your newly generated version in various ways If you have any problems getting your Wireshark running the first time it might be a good idea to remove the previously installed version first XXX add more info here 29 Work with the Wireshark sources 3 Debug your generated Wireshark See the above info on running Wireshark XXX add more info here 3 7 1 Win32 native XXX add more info here 30 Work with the Wireshark sources 3 8 Make changes to the Wireshark sources As the Wireshark developers are working on many different platforms a lot of editors are used to develop Wireshark emacs vi Microsoft Visual Studio and many many others There s no stand ard or default development environment There are several reasons why you might want to change the Wireshark sources e add your own new dissector e change extend an existing dissector e fix a bug e implement a new glorious feature The internal structure of the Wireshark sources will be described in Part II Wireshark Develop ment incomplete 2 Tip Ask the developer mailing list before you really start a new development task If you have an idea what you want to add change it s a good idea to contact the de
17. address Setting up the dissector The first decision you need to make is if this dissector will be a built in dissector included in the main program or a plugin Plugins are the easiest to write initially so let s start with that With a little care the plugin can be made to run as a built in easily too so we haven t lost anything Example 9 1 Dissector Initialisation ifdef HAVE_CONFIG_H include config h endif include lt epan packet h gt include lt epan prefs h gt forward reference void proto_register_foo void proto_reg_handoff_foo void dissect_foo tvbuff_t tvb packet_info pinfo proto_tree tree static int proto_foo 1 static int global_foo_port 1234 static dissector_handle_t foo_handle void proto_register_foo void if proto_foo 1 proto_foo proto_register_protocol FOO Protocol name FOO short name foo abbrev Let s go through this a bit at a time First we have some boiler plate include files These will be pretty constant to start with Here we also pre declare some functions that we ll be writing shortly Next we have an int that is initialised to 1 that records our protocol This will get updated when we register this dissector with the main program We can use this as a handy way to detect if we ve been initialised yet It s good practice to make all variables and functions that aren t exported static to keep name space po
18. and documentation distributed with Wireshark this document is covered by the GNU General Public Licence GNU GPL If you haven t read the GPL before please do so It explains all the things that you are allowed to do with this code and documentation GNU GENERAL PUBLIC LICENSE Version 2 June 1991 Copyright C 1989 1991 Free Software Foundation Inc 59 Temple Place Suite 330 Boston MA 02111 1307 USA Everyone is permitted to copy and distribute verbatim copies of this license document but changing it is not allowed Preamble The licenses for most software are designed to take away your freedom to share and change it By contrast the GNU General Public License is intended to guarantee your freedom to share and change free software to make sure the software is free for all its users This General Public License applies to most of the Free Software Foundation s software and to any other program whose authors commit to using it Some other Free Software Foundation software is covered by the GNU Library General Public License instead You can apply it to your programs too When we speak of free software we are referring to freedom not price Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software and charge for this service if you wish that you receive source code or can get it if you want it that you can change the software or use pieces of it in new free progr
19. belief is probably due to an improper interpretation of the Visual Studio 2003 Toolkit EULA which places redistribution restrictions only on SOURCE CODE SAMPLES which accompany the toolkit 2 Other maintainers believe that the GPL itself forbids using Visual Studio 2003 since one of the required support libraries MSVCR71 DLL does not ship with the Windows operating system This is also a wrongful interpretation and the GPL FAQ explicitly addresses this issue Similar applies to Visual Studio 2005 and alike So in effect it should be perfectly legal to compile Wireshark and distribute run it if it was com piled with any MSVC version gt V6 4 4 3 cl exe C Compiler The following table gives an overview of the possible Microsoft toolchain variants and their specific C compiler versions ordered by release date Compiler Package cl exe define MSC_VER required C Runtime DLL Visual Studio 6 0 6 0 1200 msvert dll Version 6 Visual Studio NET 2002 7 0 1300 msver70 dll NET Framework SDK version 1 0a Visual Studio NET 2003 7 10 1310 msver71 dll NET Framework SDK Version 1 1 Visual Studio 2005 Visual C 2005 Ex press Edition NET Framework 2 0 SDK 8 0 1400 msver80 dll Windows SDK for Windows Vista and NET Framework 3 0 Runtime Components Visual Studio 2008 9 0 1500 msver90 dll Code Name Orcas 50 4 4 4 4 4 5 4 4 6 Tool Reference
20. eee eeee teens 63 4 13 2 Wain32 Natives ditt sired ae e R E E E a a 63 4 14 patch optional secese sa a ei a a a e E 64 4 14 1 UNIX or Win32 Cygwin patch sssesseseesesseerererisrrerrereerreees 64 4 14 2 W032 native P teh sisisi esses ris oas s aai eap iE 64 4 15 Win32 GNU wget optional s eessssessseseissresreresrrerrsrrerreeesreererreees 65 4 16 Win32 GNU unzip optional 2 0 0 0 eee cence cece cece ne eeneeenneeneees 66 4 17 Win32 NSIS optional cc eeeeeeeeeceee eee eeeeceeeeeeeeeeeeaeeeeaeeeeeaeeees 67 5 Eibrary RElerences 2 4 rna ee EN ys EE EA T EEN et eee 69 Del Introduction a ona E A E N E E A EAE 69 5 2 Bi ary library formats 2 3 cucu nre cities Ua ea ee 70 52d UNE sh coadinetveumncesvetuatevsauntec etna nies tua cosy AE EA teens AS E 70 92 2 Win32MSVG sroin e re O E E EV EEEE Se 70 5 2 3 W1032 CYE WIN BCC s eniris aan a septate E ea EEES 70 5 3 Win32 Automated library download 0 0 2 0 cece cece cence ence eeceneeeneees 71 3 3 l Initial download eeaeee E OEEO SERERE PRETER 71 5 3 2 Update of a previous download essesseeeeeeerrsrereerrerrsrrerrreesne 71 5 4 GTK GLib GDK Pango ATK GNU gettext GNU libiconv 73 DAL UDR eee er a stor Sunes votes gooey NEO E AE EEEN AR S t 73 S42 W3 ZMS VE e tetea A EN EE EEEE E E N RES 73 53 Net SNMPE Optional asean aera a E E E E 74 SSUDA see ote N 74 5 3 2 Win32 MS VC kee oeeo RE E EEEE EA EI EE RSE Se 74 5 6
21. following steps 1 Add the Wireshark boilerplate to the new file s 2 Add a line to each new file containing the following text case is important so don t write ID or id or iD Id 3 Add the new file s to the repository svn add new_file 4 Set the line ending property to native for the new file s svn propset svn eol style native new_file 5 Set version keyword to Id for the new file s svn propset svn keywords Id new_file 6 Commit your changes including the added file s svn commit new_file other_files_you_modified Don t forget a brief description of the reason for the commit so other developers don t need to read the diff in order to know what has changed 39 Work with the Wireshark sources 3 12 Binary packaging Delivering binary packages makes it much easier for the end users to install Wireshark on their tar get system This section will explain how the binary packages are made 3 12 1 Debian deb packages The Debian Package is built using dpkg buildpackage based on information found in the source tree under debian See http www debian administration org articles 336 for a more in depth discus sion of the build process In the wireshark directory type make debian package to build the Debian Package 3 12 2 Red Hat rpm packages The RPM is built using rpmbuild http www rpm org which comes as standard on many flavours of Linux including Red Hat and Fedora The
22. for details Sending your patch for inclusion After generating a patch of your changes you might want to have your changes included into the SVN repository To submit a patch open a new ticket in the Wireshark bug database at http bugs wireshark org bugzilla enter_bug cgi product Wireshark You must first create a bug then attach your patch or patches e Set the Product Priority and Severity as needed e Adda Summary and Description and create a bug using the Commit button If your code has passed fuzz testing please say so in the description e Once the bug has been created select Create a New Attachment and upload your patch or patches Set the review_for_checkin flag to e If possible and applicable attach a capture file that demonstrates your new feature or protocol Tip 7 Setting the review_for_checkin is important Without it your patch won t show up in the pending patch request queue You might get one of the following responses to your patch request e Your patch is checked into the SVN repository Congratulations e You are asked to provide additional information capture files or other material If you haven t fuzzed your code you may be asked to do so e Your patch is rejected You should get a response with the reason for rejection Common reas ons include not following the style guide buggy or insecure code and code that won t compile on other platforms In each case you ll have to
23. in which case you might want separate DLT_ values For the rest of the libpcap discussion I ll assume you re working with the current top of tree CVS version of libpcap and that this is on a UN X platform You probably don t want to work with a version older than 0 8 even if whatever OS you re using happens to include libpcap older versions are not as friendly towards adding support for devices other than standard network interfaces Then you d probably add to the pcap_open_live routine for whatever platform or platforms this code should work something such as a check for device names that look like serial port names and if the check succeeds a call to a routine to open the serial port See for example the ifdef HAVE_DAG_API code in pcap linux c and pcap bpf c The serial port open routine would open the serial port device set the baud rate and do anything else needed to open the device It d allocate a pcap_t set its fd member to the file descriptor for the serial device set the snapshot member to the argument passed to the open routine set the link type member to one of the DLT_ values and set the selectable_fd member to the same value as the fd member It should also set the dlt_count member to the number of DLT_ values to sup port and allocate an array of dlt_count u_int s assign it to the dlt_list member and fill in that list with all the DLT_ values You d then set the various _op fields to routines
24. interface A tap is basically a way of allowing other items to see whats happening as a protocol is dissected A tap is registered with the main program and then called on each dissection Some arbritary protocol specific data is provided with the routine that can be used To create a tap you first need to register a tap A tap is registered with an integer handle and re gistered with the routine register_tap This takes a string name with which to find it again Example 9 20 Initialising a tap include lt epan tap h gt static int foo_tap 1 struct FooTap gint packet_type gint priorty foo_tap register_tap foo Whilst you can program a tap without protocol specific data it is generally not very useful There fore it s a good idea to declare a structure that can be passed through the tap This needs to be a stat ic structure as it will be used after the dissection routine has returned Its generally best to pick out some generic parts of the protocol you are dissecting into the tap data A packet type a priority a status code maybe The structure really needs to be included in a header file so that it can be in cluded by other components that want to listen in to the tap Once you have these defined it s simply a case of populating the protocol specific structure and then calling tap_queue_packet probably as the last part of the dissector Example 9 21 Calling a protocol tap static struct FooTap pinfo pin
25. not licensed at all The precise terms and conditions for copying distribution and modification follow GNU GENERAL PUBLIC LICENSE TERMS AND CONDITIONS FOR COPYING DISTRIBUTION AND MODIFICATION 0 This License applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed under the terms of this General Public License The Program below refers to any such program or work and a work based on the Program means either the Program or any derivative work under copyright law that is to say a work containing the Program or a portion of it 129 This Document s License GPL either verbatim or with modifications and or translated into another language Hereinafter translation is included without limitation in the term modification Each licensee is addressed as you Activities other than copying distribution and modification are not covered by this License they are outside its scope The act of running the Program is not restricted and the output from the Program is covered only if its contents constitute a work based on the Program independent of having been made by running the Program Whether that is true depends on what the Program does 1 You may copy and distribute verbatim copies of the Program s source code as you receive it in any medium provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and di
26. one of the maintainers will make it much more likely and faster that it will actually be applied Please remember you don t pay the person on the other side of the mail for his her effort applying your patch 3 9 4 Code Requirements 34 3 9 5 Work with the Wireshark sources The core maintainers have done a lot of work fixing bugs and making code compile on the various platforms Wireshark supports To ensure Wireshark s source code quality and to reduce the workload of the core maintainers there are some things you should think about before submitting a patch A Warn Ignoring the code requirements will make it very likely that your patch will be re jected e Follow the Wireshark source code style guide Just because something compiles on your plat form that doesn t mean it ll compile on all of the other platforms for which Wireshark is built Wireshark runs on many platforms and can be compiled with a number of different compilers See Section 7 2 Coding styleguides for details e Fuzz test your changes Fuzz testing is a very effective way to automatically find a lot of dis sector related bugs You ll take a capture file containing packets affecting your dissector and the fuzz test will randomly change bytes in this file so that unusual code paths in your dissector are checked There are tools available to automatically do this on any number of input files see ht tp wiki wireshark org FuzzTesting
27. see Section 3 3 Obtain the Wireshark sources so the zip filenames in the setup target of Makefile nmake are in sync with the library zip files on the server e Execute the library setup command as described above gt nmake f Makefile nmake setup Note that this command will automatically do a cLean setup which will remove all files pre viously unzipped from the downloaded files in your WIRESHARK_LIBS library path all the subdirs e g c wireshark win32 libs gtkt except for the zip files located at the 71 Library Reference toplevel which are the files downloaded the last time s Also note that as wget will download only the missing updated files existing zip files in the WIRESHARK LIBS dir won t be downloaded again Remaining outdated zip files shouldn t do any harm 72 Library Reference 5 4 GTK GLib GDK Pango ATK GNU gettext GNU libiconv 5 4 1 5 4 2 The Glib library is used as a basic platform abstraction library it s not related to graphical user inter face GUI things For a detailed description about GLib see Section 7 3 The GLib library The GTK and its dependent libraries are used to build Wireshark s GUI For a detailed description of the GTK libraries see Section 10 2 The GTK library All other libraries are dependent on the two libraries mentioned above you will typically not come in touch with these while doing Wireshark development
28. see Section 5 3 Win32 Automated library download for an easier way to install the libraries 69 Library Reference 5 2 Binary library formats Binary libraries are available in different formats depending on the C compiler used to build it and of course the platform they were built for 5 2 1 Unix If you have installed unix binary libraries on your system they will match the C compiler If not already installed the libraries should be available as a package from the platform installer or you can download and compile the source and then install the binaries Win32 MSVC Most of the Win32 binary libraries you will find on the web are in this format You will recognize MSVC libraries by the lib dll file extension Win32 cygwin gcc 5 2 2 5 2 3 Cygwin provides most of the required libraries with file extension a or lib for Wireshark suitable for cygwin s gcc compiler 70 Library Reference 5 3 Win32 Automated library download 5 3 1 Initial download 5 3 2 You can download install all required libraries by using the setup target of the Makefile nmake from the source package Tip It s a really good idea to use the Win32 automated library download to install the re quired libraries as it makes this download very easy Note Before you start the download you must have installed both the required tools see Chapter 4 Tool Reference and also the Wireshark sources see Sectio
29. to handle the operations in question read_op is the routine that d read packets from the device inject_op would be for sending packets if you don t care about that you d set it to a routine that returns an error indication setfilter_op can probably just be set to install_bpf_program set_datalink would just set the linktype member to the specified value if it s one of the values for OBD otherwise it should return an error getnonblock_op can probably be set to pcap_getnonblock_fd setnonblock_op can probably be set to pcap_setnonblock_fd stats_op would be set to a routine that reports statistics close_op can probably be set to pcap_close_common If there s more than one DLT_ value you definitely want a set_datalink routine so that the user can select the appropriate link layer type For Wireshark you d add support for those DLT_ values to wiretap libpcap c which might mean adding one or more WTAP_ENCAP types to wtap h and to the encap_table table in wiretap wtap c You d then have to write a dissector or dissectors for the link layer protocols or protocols and have them register themselves with the wtap_encap dissector table with the appropriate WTAP_ENCAP values by calling dissector_addQ 98 Packet capturing 99 Chapter 9 Packet dissection 9 1 How it works Each dissector decodes its part of the protocol and then hands off decoding to subsequent dissectors for an encapsulated protocol So it might al
30. 255 tse ie aaa i cas cebagsas sons Sasa saber sta ceeau set S 21 3 2 The Wireshark Subversion repository ceceeeeeeeceeeceeeceeeeeeeeeeeenees 22 3 2 1 The web interface to the Subversion repository ce cesses 22 3 3 Obtain the Wireshark sources 0 00 0 eect cece eee cence ence ee ae eeneeeneeeneeeeees 24 3 3 1 Anonymous Subversion access e cece eeeeeeeeceeece teen cece sean eenes 24 3 3 2 Anonymous Subversion web interface 20 0 0 00 eeeeeeee eee eee 24 Wireshark Developer s Guide 3 3 3 Buildbot Smapshots gt is ccs ossgasesesabtsegssstees Seegavesesestendsvenees 24 3 3 4 Released SOULCES yide heads bute eee ihec dest ET tide desbiaemey 25 3 4 Update the Wireshark sources 0 0 0 0 ee cece cece cere cence cea eeueeneeeeeeeees 26 3 4 1 with Anonymous Subversion access ceeeeeeeeeeneeeeeeeeeenes 26 Bi4 2 es from Zip TUES ee a dost nauty deve aes chs bee EEEE E SES 26 3 5 Build Wireshark ss sss ssaece canes deve sens soethae soho gacd a E E E NE 27 SD UNIX orees dah agi wte ntl Rida Rt bat A ea ae ea ee 27 3 3 2 Win 32 Nati VE eenas ote ag e SEE EES PEEP TIPRO AESSR serte nisesases 27 3 6 Run generated Wireshark eseeseseseeerrsresrreesrrerrsrrresrreersrreereeeseree 29 3 7 Debug your generated Wireshark 0 ecee cece cece eeceeeceeeeeeeeeeeenees 30 SeT AS Win32 ative s srta e e a e aE oebeotingeceset 30 3 8 Make changes to the Wireshark sources
31. 32 native python ni aseen aree e teen cena EEE SY 56 A Te Perl io e ee gy EE EEE EE EE AREER E EEEREN E SASS EEEE 57 4 7 1 UNIX or Win32 Cygwin perl oessssseseeseeeessrererrereerrerrererereees 57 4 T 2 Wind ative perl draenen e A avs E E ENNA R 57 a RoT E E EE E SG Co la OE Say 58 4 8 1 UNIX or Win32 Cygwin sed ssseeeseseesseeserrrereeresrrerrereeereees 58 43 2 Win32 native Sed srci itrio reteo eE Eaa ESE EEEE 58 4 9 Vac BISON iie o aea ape a T a AR AEE e aA 59 4 9 1 UNIX or Win32 Cygwin bison esseseeseeeesseererrerrerrerrerrereeees 59 4 9 2 W132 native DISON ccs 655sssoeigsscdscess SEE EES RES ess RTE NPESE EE TNES 59 AAO flex so e RE chee E E E St E E E Sets 60 4 10 1 UNIX or Win32 Cygwin flex eeeseeeseeseseeerrsresrrrresrererreeees 60 4 10 2 Win3 2 Native flex ise ere e EE E E E ES EES 60 Wireshark Developer s Guide 4 11 Subversion SVN client optional cceeeeeeeceeeeeeeeeeeeeeeaeeeeen senor 61 4 11 1 UNIX or Win32 Cygwin SVN oo cece ec eeecneee eee een een eees 61 4 11 2 Win32 native SVN E a eE E E EEE 6l 4 12 Subversion SVN GUI client optional 2 0 0 0 cece ee ceee eee eeeeeneeees 62 4 12 1 UNIX or Win32 Cygwin rapidSVN subcommander 62 4 12 2 Win32 native TortoiseSVN 00 0 cece eeeeee cece eeceeeeereeeeereeenereees 62 4 13 gt ditt Optional scecivsednuyes Taa enak Hea STAR MA Reel ee ae 63 4 13 1 UNIX or Win32 Cygwin GNU diff oo
32. 5 Express Edition 2 Platform SDK Download 420MB and install Platform SDK Server 2003 R2 Install MSVC the usual way Don t forget to install vcvars32 bat or call it manually before building Wireshark vcvars32 bat will set some required environment e g the PATH settings p Other Microsoft C compiler variants possible It s possible to compile Wireshark with a wide range of Microsoft C compiler variants d for details see Section 4 4 Microsoft compiler toolchain Win32 native A Don t use cygwin s gcc Using cygwin s gcc is not recommended and will certainly not work at least without a lot of advanced tweaking For further details on this topic see Section 4 3 GNU compiler toolchain UNIX or Win32 Cygwin XXX mention the compiler and PSDK web installers which significantly reduce download size and find out the required components XXX how to get the right PATH settings Why this is recommended While this is a huge download the 2005 express edition is the only free as in beer version that includes the Visual Studio integrated debugger Install Cygwin Download the cygwin installer and start it At the Select Packages page you ll need to select some additional packages which are not in stalled by default Navigate to the required Category Package row and click on the Skip item in the New column so it shows a version number for e Archive unzip e Devel bison e Devel flex e In
33. AEE 100 9 2 Adding a basic dissector 20 0 cece cece ce eecceecc ence eeceeeeeeeeaeeeueeea eens eeaes 101 9 2 1 Setting up the dissectOr s csascs cosssssseveesaasedsaesedssiaeadssesseonseys 101 9 2 2 Dissecting the details of the protocol 2 0 00 cece eeee eee eee 103 9 2 3 Improving the dissection information ceeeee cece eee ence eee 106 9 3 How to handle transformed data ceeeeeseeeeneeceueeeeeeecenneeeeneeeees 109 9 4 How to reassemble split packets 2 0 0 0 cece cece eee ceeece teen secu seen eeaes 110 9 4 1 How to reassemble split UDP packets 0 0 0 0 eee ee eeee eee 110 9 4 2 How to reassemble split TCP Packets 2 0 0 0 cece eeeeee cece eee 113 95 HOW tO tap protocols 0 00 cseecssvsosebophentess es Sgedieny vegess SEE YEE ORS 115 9 6 How to produce protocol stats cece cece cee ce eeceeeea teen seca eenneeaes 116 9 7 How to USE CONVETSATIONS 20 2 0 cece si e G EE EES 118 10 User Interface erei e EEE vines inte lees E REE A TEE EE 120 10 1 Introduction e aa vst vied ge sisted EAA NA ETNA EEE Eai 120 10 2 The GTR brary esotera snie e RR S TEES dese 121 10 2 1 GIKR Versi n TX rini e E T A EET 121 10 22 GIR Version 2 X a enaena E a N ea iaae a 121 10 2 3 Compatibility between 1 x and 2 x oo cece ence eee ee eenee 122 10 2 4 GTK resources on the Web eccseceececeeececeeeeeaeeeeeeneneees 122 10 3 GUI Reference document 20 00 00 nrn cece a
34. C2005 uses the content of Microsoft VC80 CRT method 2 this is the 52 Tool Reference smallest package As MSVC2005EE and DOTNET20 doesn t provide the folder Mi crosoft VC80 CRT they use method 3 You ll have to download a vcredist_x86 exe from Microsoft that matches your compiler version The best way to determine this version is to open one of the generated manifest files e g wireshark exe manifest and look for the version of the Mi crosoft VC80 CRT entry e 8 0 50608 0 from Microsoft Visual C 2005 and probably the Express Edition as well ht tp 4 www microsoft com downloads de tails aspx FamilyId 32BC1BEE A3F9 4C 13 9C99 220B62A 19 LEE amp displaylang en e 8 0 50727 762 from Microsoft Visual C 2005 Express Edition ENU Service Pack 1 KB926748 http L www microsoft com downloads de tails aspx familyid 200B2FD9 AE1A 4A14 984D 389C36F85647 amp displaylang en Please report to the developer mailing list if you find a different version number 4 4 6 5 msvcr90 dll Version 9 0 2008 As the corresponding C compiler is preliminary it s too early to say 4 4 7 Windows Platform SDK 4 4 8 The Windows Platform SDK PSDK is a free as in beer download and contains platform specific headers and libraries e g windows h WSock32 lib As new Windows features evolve in time updated PSDK s become available that include new and updated APT s When you purchase a commercial Visual S
35. E es a 124 10 4 Adding Extending Dialogs 2 2 0 0 cece cece ce eeceeece eee eeeeeeeeeeeaeeenes 125 10 5 Wid pet namine sareat he E e tide ec St phe vei waren beeen acct ER 126 10 6 Common GTK programming pitfalls ee eeee nee ee cece eenee 127 10 6 1 Usage of gtk_widget_show gtk_widget_show_all 127 A Ths Documents License GPL vs sls sven sacesdsd esse ocad a E aE EEE KPEE SPIRES A eo 129 vii Preface 1 Foreword This book tries to give you a guide to start your own experiments into the wonderful world of Wire shark development Developers who are new to Wireshark often have a hard time getting their development environ ment up and running This is especially true for Win32 developers as a lot of the tools and methods used when building Wireshark are much more common in the UNIX world than on Win32 The first part of this book will describe how to set up the environment needed to develop Wireshark The second part of this book will describe how to change the Wireshark source code We hope that you find this book useful and look forward to your comments viii Preface 2 Who should read this document The intended audience of this book is anyone going into the development of Wireshark This book is not intended to explain the usage of Wireshark in general Please refer the Wireshark User s Guide about Wireshark usage By reading this book you will learn how to develop Wires
36. ET Frame work 3 0 Runtime Components Color Legend Good Not so good Might be a problem tho longer officially available might still be available through the MSDN subscriptions as the Platform SDK is already integrated in the package you obviously don t need to install it and don t even need to call a separate environment setting batch file for the Platform SDK 3vcredist_x86 exe 3MB free download is required to build Wireshark setup exe 4Wireshark setup exe cannot be created with this package as msvcr dll is not available or not re distributable XXX MSDN remarks that the corresponding NET runtime is required It s currently unclear if the runtime needs to be installed for the C compiler to work or is this only needed to compile run NET programs beta version not suitable for production use 4 Note The Visual C Toolkit 2003 should NOT be used to compile Wireshark Legal issues with MSVC gt V6 Please note The following is not legal advice ask your preferred lawyer instead It s the authors view but this view might be wrong The myriad of Win32 support lib port projects all seem to believe there are legal issues involved in 49 Tool Reference using newer versions of Visual Studio This FUD essentially stems from two misconceptions 1 Unfortunately it is believed by many that the Microsoft Visual Studio 2003 EULA explicitly forbids linking with GPL ed programs This
37. OPYRIGHT HOLDER OR ANY OTHER PARTY WHO MAY MODIFY AND OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE BE LIABLE TO YOU FOR DAMAGES INCLUDING ANY GENERAL SPECIAL INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES END OF TERMS AND CONDITIONS How to Apply These Terms to Your New Programs If you develop a new program and you want it to be of the greatest possible use to the public the best way to achieve this is to make it free software which everyone can redistribute and change under these terms To do so attach the following notices to the program It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty and each file should have at least the copyright line and a pointer to where the full notice is found lt one line to give the program s name and a brief idea of what it does gt Copyright C lt year gt lt name of author gt This program is free software you can redistribute it and or modify it under the terms of the GNU General Public License as published by the Free Software Foundation either version 2 of the License or at yo
38. Wireshark Developer s Guide 24295 for Wireshark 0 99 7 Ulf Lamping Wireshark Developer s Guide 24295 for Wireshark 0 99 7 by Ulf Lamping Copyright 2004 2007 Ulf Lamping Permission is granted to copy distribute and or modify this document under the terms of the GNU General Public License Version 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 Contents Preface 265 ssc cebssievonces tah ecdade e ae aae E e r T E E aS viii Le Foreword sas fete sg ssid cosas oodo eeen d aE E E Ea SIERE GEESI EUERE EIEE na viii 2 Who should read this document 0 00 0 eee e eee ceeeceeeca seca eee eeeaeeea tenn eeu eens ix 3 Acknowledgements sisinio sarees peaneaagast EE E e E oer ads E X 4 About this document sssini EE ESE EE EEE EEEIEE xi 5 Where to get the latest copy of this document seeseseeeeseesreresrrerrsrrerrereere xii 6 Providing feedback about this document sseeeesseesssrrsseerrsreerrrresreersrrerrere xiii I Wireshark Build Environment ccc ecece cece ence neceneceeeeeeceeeceeeeaeeeaeseu esau eeaeeeaes 1 Le Introduction seenen an Sent ent aE E ss bh E a teas EEE uae ss oye 2 VA Introduction vrini recat bb cscek EE EE y wea rtel SES EE OR TTEN 2 1 2 Whatis Wireshark tornen paea Ea EEEE A E O ES 3 1 3 Platforms Wireshark runs on 2 0 2 cece eee c cence ee ee ence eeeeee
39. a few minutes even on fast machines If everything went well you will now find something like wireshark setup 0 99 7 exein the packaging nsis directory 41 Work with the Wireshark sources 42 Chapter 4 Tool Reference 4 1 Introduction This chapter will provide you with information about the various tools needed for Wireshark devel opment None of the tools mentioned in this chapter is needed to run Wireshark they are only needed to build it Most of these tools have their roots on UNIX like platforms but Win32 ports are also available Therefore the tools are available in different flavours e UNIX or Win32 Cygwin the tools should be commonly available on the supported UNIX platforms and for Win32 platforms by using the Cygwin UNIX emulation e Win32 native some tools are available as native Win32 tools no special emulation is required A Warning Unless you know exactly what you are doing you should strictly follow the re commendations given in Chapter 2 Quick Setup The following sections give a very brief description of what a particular tool is doing how it is used in the Wireshark project and how it can be installed and tested Don t expect a lot of documentation regarding these tools in this document If you need further doc umentation of a specific tool you should find lot s of useful information on the web as these tools are commonly used You can also try to get help for the UNIX ba
40. able as a package for your platform you can get it at ht tp www gnu org software adns 5 6 2 Win32 MSVC You can get the latest version at http adns jgaa com 75 Library Reference 5 7 PCRE optional Perl compatible regular expressions 5 7 1 Unix If this library isn t already installed or available as a package for your platform you can get it at ht tp www pcre org 5 7 2 Win32 MSVC You can get the latest version at http gnuwin32 sourceforge net packages pcre htm 76 Library Reference 5 8 zlib optional zlib is designed to be a free general purpose legally unencumbered that is not covered by any patents lossless data compression library for use on virtually any computer hardware and operat ing system 5 8 1 Unix If this library isn t already installed or available as a package for your platform you can get it at ht tp www gzip org zlib 5 8 2 Win32 MSVC You can get the latest version at http gnuwin32 sourceforge net packages zlib htm A version for the MS VC2003 compiler can be found at http www winimage com zLibDIL 77 Library Reference 5 9 libpcap WinPcap optional packet capture library 5 9 1 Unix libpcap If this library isn t already installed or available as a package for your platform you can get it at ht tp www tcpdump org 5 9 2 Win32 MSVC WinPcap You can get the Windows packet capture library at h
41. ams and that you know you can do these things To protect your rights we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights These restrictions translate to certain responsibilities for you if you distribute copies of the software or if you modify it For example if you distribute copies of such a program whether gratis or for a fee you must give the recipients all the rights that you have You must make sure that they too receive or can get the source code And you must show them these terms so they know their rights We protect your rights with two steps 1 copyright the software and 2 offer you this license which gives you legal permission to copy distribute and or modify the software Also for each author s protection and ours we want to make certain that everyone understands that there is no warranty for this free software If the software is modified by someone else and passed on we want its recipients to know that what they have is not the original so that any problems introduced by others will not reflect on the original authors reputations Finally any free program is threatened constantly by software patents We wish to avoid the danger that redistributors of a free program will individually obtain patent licenses in effect making the program proprietary To prevent this we have made it clear that any patent must be licensed for everyone s free use or
42. an use the handy function tvb_get_guint8 to do this With this value in hand there are a couple of things we can do First we can set the INFO column of the non detailed view to show what sort of PDU it is which is ex tremely helpful when looking at protocol traces Second we can also display this information in the dissection window Example 9 13 Enhancing the display static void dissect_foo tvbuff_t tvb packet_info pinfo proto_tree tree guint8 packet_type tvb_get_guint8 tvb 0 if check_col pinfo gt cinfo COL_PROTOCOL col_set_str pinfo gt cinfo COL_PROTOCOL FOO Clear out stuff in the info column if check_col pinfo gt cinfo COL_INFO col_clear pinfo gt cinfo COL_INFO if check_col pinfo gt cinfo COL_INFO col_add_fstr pinfo gt cinfo COL_INFO Type s val_to_str packet_type packettypenames Unknown 0x 02x if tree we are being asked for details proto_item ti NULL proto_tree foo_tree NULL gint offset 0 ti proto_tree_add_item tree proto_foo tvb 0 1 FALSE proto_item_append_text ti Type s val_to_str packet_type packettypenames Unknown 0x 02x foo_tree proto_item_add_subtree ti ett_foo proto_tree_add_item foo_tree hf_foo_pdu_type tvb offset 1 FALSE offset 1 So here after grabbing the value of the first 8 bits we use it with one of the built in utility routines val_to_str to lookup the value If th
43. ark provides a general purpose interface to read write all the file formats If you need to add another capture file format this is the place to start 91 How Wireshark Works 6 5 Dissect packets While Wireshark is loading packets from a file each packet is dissected Wireshark tries to detect the packet type and gets as much information from the packet as possible In this run though only the information shown in the packet list pane is needed As the user selects a specific packet in the packet list pane this packet will be dissected again This time Wireshark tries to get every single piece of information and put it into the packet details pane 92 How Wireshark Works 93 Chapter 7 Introduction 7 1 Source overview Wireshark consists of the following major parts e Packet dissection in the epan dissector and plugin directory e File I O using Wireshark s own wiretap library e Capture using the libpcap winpcap library e User interface using the GTK and corresponding libraries e Help using an external webbrowser and GTK text output Beside this some other minor parts and additional helpers exist Currently there s no clean separation of the modules in the code However as the development team switched from CVS to SVN some time ago directory cleanup is much easier now So there s a chance that the directory structure will become clean in the future 94 Introduction 7
44. atch in that directory and run it with p0 If you run it without p at all the patch tool flattens path names so that if you have a patch file with patches to Makefile am and wiretap Makefile am it ll try to apply the first patch to the top level Makefile am and then apply the wiretap Makefile am patch to the top level Makefile am as well At which position in the filesystem should the patch tool be called If the pathnames are relative to the top level source directory or to a directory above that directory you d run it in the top level source directory If they re relative to a subdirectory for example if somebody did a patch to packet ip c and ran diff or svn diff in the epan dissectors directory you d run it in that subdirectory It is pre ferred that people NOT submit patches like that especially if they re only patching files that exist in multiple directories such as Makefile am 3 10 2 CVS diff obsolete One other thing to note cvs diff produces output that at least some versions of patch can t handle you d get something such as Index missing dlnames c RCS file tcpdump master tcpdump missing dlnames c v retrieving revision 1 5 diff c r1 5 dlnames c missing dlnames c 18 Nov 2003 23 09 43 0000 15 missing dlnames c 31 Aug 2004 21 45 16 0000 KKEKKKKKKKKKKKKK from cvs diff c and something similar from cvs diff u and patch unfortunately would use the
45. braries e GDK GDK is the abstraction layer that allows GTK to support multiple windowing systems GDK provides drawing and window system facilities on X11 Windows and the Linux frame buffer device e GLib A general purpose utility library not specific to graphical user interfaces GLib provides many useful data types macros type conversions string utilities file utilities a main loop ab straction and so on GTK 1 x is working on GLib 1 x typical for Unix like systems or 2 x typical for Win32 like sys tems XXX include Wireshark GTK1 screenshot 10 2 2 GTK Version 2 x Advantages compared to GTK 1 x e nice look and feel compared to version 1 x e recommended for future developments 121 User Interface Disadvantages e not available on all platforms compared to version 1 x e maybe a bit less stable compared to version 1 x but should be production stable too e more dependencies compared to 1 x see below GTK 2 x depends on the following libraries e GObject Object library Basis for GTK and others e GLib A general purpose utility library not specific to graphical user interfaces GLib provides many useful data types macros type conversions string utilities file utilities a main loop ab straction and so on e Pango Pango is a library for internationalized text handling It centers around the PangoLayout object representing a paragraph of text Pango provides the engine for
46. caeeeaeeea eens eeaes 4 1R a EN DIX oes eos ag test eals oes Lassa ih ad debte assed ob ae shot ess eost ews reba E 4 1 3 2 LINUR sess 2 c8eets geese de re aea e E ties EEE E RETER 4 1 3 3 Microsoft WindOWS ss 32 5 ss ecssassezetns desteteesatperta okii iere a ES 5 1 4 Development and maintenance of Wireshark ccc cece esee eee eee eeeees 6 1 4 1 Programming language s used 0 ee ceeeeeeeeeee ee eeee een eees 6 1 4 2 Open Source Software 2 0 0 0 cee eeeeeeeeeeeree EEEE EIS E EEES 6 1 5 Releases and distributions 0c eee cee ce eeceeeceeeeaeeca seen sean eene cogs 8 1 52 Binary distri Dutons sx 0c sneren ae en eon seeyesuaesshosed sees 8 1 5 2 Source code distributions cee ee eee eee ceeeceeeeaeeea teen eene eens 8 1 6 Automated Builds Buildbot 0 0 cec ccc ec cence cece eeee sence ee eeneeeenenes 9 1 621 Advantages n hse nel heeded 9 1 6 2 What does the Buildbot do 20 0 0 eee ceeeeeee ea eeea eee eene eens 9 1 7 Reporting problems and getting help eee cece cee ce ecco neces 10 T 7 1 WeDSILE sisne enrik boise e sa T EEE Date O EE PEET 10 E72 WIR er E S EEEE EEEE EE EEE ES EE 10 17 3 a O EE nes sis vote E vb ied wae E ng sovdese es beta ngs heoss sak sede agseeo een 10 1 7 4 Other SOULCES lt e E seas seein EEEE e TEE 10 L7 Maline Lists eoe s T a E E S EEI NAS NSN 10 1 7 6 Bug database Bugzilla e sseeesseesneressueressre
47. collection A Win32 Warn Using Cygwin gcc to compile Wireshark is EXPERT ONLY and therefore NOT re commended If you really want to try it anyway see http wiki wireshark org Devel opment CygwinGCC for some details The GCC C compiler is available for most of the UNIX like platforms and as the Devel gcc package from the Cygwin setup If GCC isn t already installed or available as a package for your platform you can get it at http gcc gnu org After correct installation typing at the bash command line prompt gcc version should result in something like gcc GCC 3 4 4 cygwin special gdc 0 12 using dmd 0 125 Copyright C 2004 Free Software Foundation Inc This is free software see the source for copying conditions There is NO warranty not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE However the version string may vary gdb GNU project debugger GDB is the debugger for the GCC compiler It is available for many if not all UNIX like platforms and as the Devel gdb package from the Cygwin setup If you don t like debugging using the command line there are some GUI frontends for it available most notably GNU DDD If gdb isn t already installed or available as a package for your platform you can get it at http www gnu org software gdb gdb html After correct installation gdb version should result in something like GNU gdb 6 5 50 20060706 cvs cygwin special Copyr
48. d to use a SVN client to get the latest source files For de tailed information about the different ways to obtain the Wireshark sources see Section 3 3 Obtain the Wireshark sources You will find more instructions in Section 3 3 1 Anonymous Subversion access on how to use the Subversion client 4 11 1 UNIX or Win32 Cygwin svn SVN is available for most of the UNIX like platforms and as the Subversion package from the Cyg win setup If Subversion isn t already installed or available as a package for your platform you can get it at ht tp subversion tigris org together with the server software After correct installation typing at the bash command line prompt svn version should result in something like svn version 1 0 5 r9954 compiled Jun 20 2004 23 28 30 Copyright C 2000 2004 CollabNet Subversion is open source software see http subversion tigris org This product includes software developed by CollabNet http www Collab Net However the version string may vary 4 11 2 Win32 native svn The Subversion command line tools for Win32 can be found at http subversion tigris org This will come with both client and server software only the client software will be used After correct installation typing at the command line prompt cmd exe gt svn version should result in something like svn Version 1 4 0 121228 Copyright C 2000 2006 CollabNet However the vers
49. diffs between different revisions You can also download individual files but not entire directories Buildbot Snapshots Recommended for development purposes if direct Subversion access isn t possible e g because of a restrictive firewall Age some number of minutes a bit older than the anonymous Subversion access The buildbot server will automatically start to generate a snapshot of Wireshark s source tree after a 24 3 3 4 Work with the Wireshark sources source code change is committed These snapshots can be found at http www wireshark org download automated src If anonymous Subversion access isn t possible e g if the connection to the server isn t possible be cause of a corporate firewall the sources can be obtained by downloading the buildbot snapshots However if you are going to maintain your sources in parallel to the official sources for some time it s recommended to use the anonymous Subversion access if possible believe it it will save you a lot of time Released sources Recommended for productive purposes Age from days to weeks The officially released source files can be found at http www wireshark org download You should use these sources if you want to build Wireshark on your platform for productive use The differences between the released sources and the sources stored at the Subversion repository will keep on growing until the next release is done at the release time the
50. e all the tools and libraries required to build The following chapters will describe the required tools and libraries in detail Introduction 1 6 Automated Builds Buildbot 1 6 1 1 6 2 The Wireshark Buildbot automatically rebuilds Wireshark on every change of the source code re pository and indicates problematic changes This frees the developers from repeating and annoying work so time can be spent on more interesting tasks Advantages e Recognizing cross platform build problems early Compilation problems can be narrowed down to a few commits making a fix much easier e Health status overview of the sources A quick look at http buildbot wireshark org trunk gives a good feeling if the sources are currently well On the other hand if all is red an update of a personal source tree might better be done later e Up to date binary packages are available After a change was committed to the repository a binary package installer is usually available within a few hours at http www wireshark org download automated This can be quite helpful e g a bug reporter can easily verify a bugfix by installing a recent build e Automated regression tests In particular the fuzz tests often indicate real life problems that are otherwise hard to find What does the Buildbot do The Buildbot will do the following to a different degree on the different platforms e checkout from the source reposit
51. e corresponding machine readable source code which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange or b Accompany it with a written offer valid for at least three years to give any third party for a charge no more than your cost of physically performing source distribution a complete machine readable copy of the corresponding source code to be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange or c Accompany it with the information you received as to the offer to distribute corresponding source code This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form with such an offer in accord with Subsection b above 130 This Document s License GPL The source code for a work means the preferred form of the work for making modifications to it For an executable work complete source code means all the source code for all modules it contains plus any associated interface definition files plus the scripts used to control compilation and installation of the executable However as a special exception the source code distributed need not include anything that is normally distributed in either source or binary form with the major components compiler kernel and so on of the operating system on which the executable runs unl
52. e history of how your data 9 changed In this regard many people think of a version control system as a sort of time machine Subversion is often abbreviated as SVN as the command line tools are abbreviated that way You will find both terms with the same meaning in this book in mailing list discussions and elsewhere b Tip Subversion and SVN is the same Using Wireshark s Subversion repository you can e keep your private sources up to date with very little effort e geta mail notification if someone changes the latest sources e get the source files from any previous release or any other point in time e have a quick look at the sources using a web interface e see which person changed a specific piece of code e and a lot more things related to the history of the Wireshark source code development Subversion is divided into a client and a server part Thanks to Gerald Combs the maintainer of the Subversion server no user has to deal with the maintenance of the Subversion server You will only need a Subversion client which is available as both a command line and a GUI tool for many differ ent platforms For further reference about Subversion have a look at the homepage of the Subversion project ht tp subversion tigris org There is a good and free book about it available at http svn book red bean com Please note that Wireshark s public anonymous Subversion repository is separate from the main re pository
53. e last time tested Version 1 1 0 this feature failed to apply patches known to be ok 64 Tool Reference 4 15 Win32 GNU wget optional GNU weet is used to download files from the internet using the command line GNU weet is available for most of the UNIX like platforms and as the wget package from the Cyg win setup You will only need wget if you want to use the Win32 automated library download see Section 5 3 Win32 Automated library download for details If GNU weet isn t already installed or available as a package for your platform well for Win32 it is available as a Cygwin package you can get it at http www gnu org software wget wget html If wget is trying to download files but fails to do so your Internet connection might use a HTTP proxy Some Internet providers use such a proxy and it is common for company networks today In this case you must set the environment variable HTTP_PROXY before using wget For example if you are behind proxy com which is listening on port 8080 you have to set it to something like HTTP_PROXY http proxy com 8080 If you are unsure about the settings you might ask your system administrator 65 Tool Reference 4 16 Win32 GNU unzip optional GNU unzip is used to well unzip the zip files downloaded using the wget tool GNU unzip is available for most of the UNIX like platforms and as the unzip package from the Cygwin setup You will only need
54. e tae dtt tae die 82 3 13 2 Win3 2 MSV Ge cose hes a e a E oun oa da eaders seth asta ase aeons 82 5 14 PortAudio optional 20 0 0 ceeeeeeeeeeeeeeceeeeeeeeeeeeeeeeeeereseereeenereeener 83 DAT UM eect eescaiss Sos ads ved siades vied s seed eaiee T 83 5 14 2 Win32 MSVC et ices tero e sev cks casos desta E E EE TIES 83 5 15 Win32 GTK WIMP optional for GTK 2 x only 2 0 0 84 H Wireshark Development incomplete seessssessssesrssrerrrrrsrrerrsrrrrrsrerrrrresrerrerreees 86 6 How Wireshark WOrKS cess ad emeena dea e REEE AEAEE ALE SETO REIP EA TRTE 87 6 1 Introd ction esan r a o a TE S E leader E EE 87 6 25 OVE eW eE nE EEE EE AE ious dade EEE aude O E NARE 88 6 3 Capturing packets s serene SOE E E EE S E S dene 90 vi Wireshark Developer s Guide 6 4 Capture Pues cscs Sasese sient Seve snaes seta ad ss conn sles stead ss oedeealss soteag sh caes 91 6 5 DISSECT PACKS mri e ands Vedas sy Oi Sedu AERE EASES 92 T Introdu hon sein EE baa eek el acceded as eA AS 94 Tal SOULCE OVELVIEW ee yE os eau E NEN Dad beer y shine SEE tote tees Cee OTe 94 7 2 Coding Stylesuides Sccses2dtapwstedin reg Mie E EE st dolapiasedaueme use eae 95 T3 Me GLAD MDLary eea a E E Ea E N a a dese AE 96 8 Packet capt rint a e ae O E is ee N A e TE E ENSY 98 8 1 How to add a new capture type to libpcap 0 eee cence neces 98 9 Packet dissection n rresii isens Teri ara E T Rea E SE 100 9 1 HOW AL WOKS ii ena a a a E A
55. e value isn t found we provide a fallback which just prints the value in hex We use this twice once in the INFO field of the columns if it s displayed and simil 107 Packet dissection arly we append this data to the base of our dissecting tree 108 Packet dissection 9 3 How to handle transformed data Some protocols do clever things with data They might possibly encrypt the data or compress data or part of it If you know how these steps are taken it is possible to reverse them within the dissect or As encryption can be tricky let s consider the case of compression These techniques can also work for other transformations of data where some step is required before the data can be examined What basically needs to happen here is to identify the data that needs conversion take that data and transform it into a new stream and then call a dissector on it Often this needs to be done on the fly based on clues in the packet Sometimes this needs to be used in conjunction with other techniques such as packet reassembly The following shows a technique to achieve this effect Example 9 14 Decompressing data packets for dissection guint8 flags tvb_get_guint8 tvb offset offset if flags amp FLAG_COMPRESSED the remainder of the packet is compressed guint1l6 orig_size tvb_get_ntohs tvb offset guchar decompressed_buffer guchar g_malloc orig_size offset 2 decompress_packe
56. eassembled in field amp hf_msg_reassembled_in Tag Message fragments static hf_register_info hf hf_msg_fragments Message fragments msg fragments T_NONE BASE_NONE NULL 0x00 NULL 7 hf_msg_fragment Message fragment msg fragment FT_FRAMENUM BASE_NONE NULL 0x00 fragment_overlap Message fragment overlap FT BOOLEAN BASE_NONE NULL 0x00 N msg fragment overlap conflicts FT BOOLEAN BASE_NONE NULL 0x00 N Message has multiple tail fragment msg fragment multiple_tails FT BOOLEAN BASE_NONE NULL 0x00 N Message fragment too long FT BOOLEAN BASE_NONE NULL 0x00 N Message defragmentation error FT_FRAMENUM BASE_NONE NULL 0x00 m Reassembled in msg reassembled FT_FRAMENUM BASE_NONE NULL 0x00 static gint ett A NU UL UL S UL UL sg U in NU HFIL LL msg fragment L H L H Eun msg fragment L H LL iil HF HF Lili too_long_fragment Lili fragment error LL LL 112 9 4 2 Packet dissection ett_msg_fragment ett_msg_fragments These hf variables are used internally within the reassembly routines to make useful links and to add data to the dissection It produces links from one packet to another such as a partial packet having a link to the fully reass
57. ectors 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 have a look at the http anonsvn wireshark org wireshark trunk AUTHORS page on the Wireshark web site The communication between the developers is usually done through the developer mailing list which can be joined by anyone interested in the development process At the time this document was written more than 500 persons were subscribed to this mailing list It is strongly recommended to join the developer mailing list if you are going to do any Wireshark development See Section 1 7 5 Mailing Lists about the different Wireshark mailing lists avail able Programming language s used Almost any part of Wireshark is implemented in plain ANSI C The typical task for a new Wireshark developer is to extend an existing or write a new dissector for a specific network protocol As almost any dissector is written in plain old ANSI C a good know ledge about ANSI C will be sufficient for Wireshark development in almost any case So unless you are going to change the development process of Wireshark itself you won t come in touch with any other programming language than ANSI C such as perl or python which are used only in the Wireshark build process Beside the usual tools for developing a program in C compiler make the build process use
58. ee neon 44 4 3 GNU compiler toolchain UNIX or Win32 Cygwin eee 45 4 3 1 gcc GNU compiler collection 2 0 0 0 cece cece neceeeeeneeeeeees 45 4 3 2 gdb GNU project debugger 2 0 0 0 eee ee cece eee eeeeeeceeeeenees 45 4 3 3 ddd GNU Data Display Debugger 1 0 0 0 eee eee ee teens 45 4 3 4 make GNU Make 00 00 cee cee ce eeceeeca ei 46 4 4 Microsoft compiler toolchain Win32 Native ce eeeeeeeeee eee eeeeeeeeees 47 4 4 1 Toolchain Package Alternatives ceeceeceecneeeeeeeeeeeeeeenees 47 4 4 2 Legal issues with MSVC gt V6 o oo e eee eneece een eene eens 49 4A ocl exe C Compiler oren es e A cane Goes te E la eosteseew alent 50 4 4 4 nmake exe Make 2 0 0 0 cc cececceceecec eee eeeecece ee eeneeceeaeeeensanenenes 51 44 5 Tink exe Linker ye e yes oh uae A ee n ceed 51 4 4 6 C Runtime Redistributable files 0 00 0 eee eee eeee eens 51 4 4 7 Windows Platform SDK ccc ce ceceec cece cece eeeeeeeeeeeneeeeneees 53 4 4 8 HIME Helpe s iein eepe ren EEEE AE AEE EES 53 449 Debugger 552s cocssses os coats cose ees Ere sedi eases totaadpsessiwas Febmeeggesanes 54 ADs pash so eree a ahs inc E RE E E E Tea E SEEE O ESN ees 55 4 5 1 UNIX or Win32 Cygwin GNU bash ssseeseesseeeesesrereerrerrerrrees 55 4 5 2 WiN32 MAUVE aeee ena ee e eT EE EErEE 55 46 AAA 00 a EEEE ESE E EE EE 56 4 6 1 UNIX or Win32 Cygwin python sessssessseessesrerrereerrerrererreeees 56 4 6 2 Win
59. eep the default C Program Files 2 c MSVC_VARIANT search for the line MSVC_VARIANT MSVC2005EE and remove the tailing comment char from this line l Compiler dependent This step depends on the compiler variant used for other variants than the re commended Visual C 2005 Express Edition see the table at Section 4 4 Microsoft compiler toolchain Win32 native International Windows might use different values here e g a german version uses C Programme take this also in account where C Program Files appears elsewhere Prepare cmd exe Prepare cmd exe set environment and current dir 1 start cmd exe 2 call C Program Files Microsoft Platform SDK for Windows Server 2003 R2 SetEnv Cmd to set environment variables of Platform SDK Server 2003 R2 3 call C Program Files Microsoft Visual Studio 8 VC bin vcvars32 bat to set environment variables of Visual C 2005 Express Edition 1 2 4 cd C wireshark to jump into the source directory Compiler dependent This step depends on the compiler variant used for other variants than the re commended Visual C 2005 Express Edition see the table at Section 4 4 Microsoft compiler toolchain Win32 native International Windows might use different values here e g a german version uses C Programme take this also in account where C Program Files appears elsewhereNote You need to repeat steps 1 4each time you open a new cmd exe Verify installed t
60. embled packet Likewise there are back pointers to the individual packets from the reassembled one The other variables are used for flagging up errors How to reassemble split TCP Packets A dissector gets a tvbuff_t pointer which holds the payload of a TCP packet This payload contains the header and data of your application layer protocol When dissecting an application layer protocol you cannot assume that each TCP packet contains ex actly one application layer message One application layer message can be split into several TCP packets You also cannot assume the a TCP packet contains only one application layer message and that the message header is at the start of your TCP payload More than one messages can be transmitted in one TCP packet so that a message can start at an abitrary position This sounds complicated but there is a simple solution tcp_dissect_pdus does all this tcp packet reassembling for you This function is implemented in epan dissect ors packet tcp h Example 9 19 Reassembling TCP fragments ifdef HAVE_CONFIG_H include config h endif include lt epan packet h gt include lt epan emem h gt include lt epan dissectors packet tcp h gt include lt epan prefs h gt define FRAME_HEADER_LEN 8 The main dissecting routine static void dissect_foo tvbuff_t tvb packet_info pinfo proto_tree tree tcp_dissect_pdus tvb pinfo tree TRUE FRAME _HEADER_LEN get_foo_message_len dissect_foo_
61. es or other changes are made and generally keeping it in tune with what is happening 6 Introduction with Wireshark So if Wireshark is updated which is done often you can get a new Wireshark version from the website and your changes will already be included without any effort for you The Wireshark source code and binary kits for some platforms are all available on the download page of the Wireshark website http www wireshark org download Introduction 1 5 Releases and distributions 1 5 1 1 5 2 The officially released files can be found at http www wireshark org download A new Wireshark version is released after significant changes compared to the last release are completed or a serious security issue is encountered The typical release schedule is about every 4 8 weeks although this may vary There are two kinds of distributions binary and source both have their advantages and disadvant ages Binary distributions Binary distributions are usually easy to install as simply starting the appropriate file is usually the only thing to do They are available for the following systems e Win32 exe file The typical Windows end user method is used to get a setup exe file which will install all the required things for him e Win32 U3 u3 file Special distribution for U3 capable USB memory sticks e Debian deb file A user of a Debian Package Manager DPKG based system obtains a deb file f
62. ess that component itself accompanies the executable If distribution of executable or object code is made by offering access to copy from a designated place then offering equivalent access to copy the source code from the same place counts as distribution of the source code even though third parties are not compelled to copy the source along with the object code 4 You may not copy modify sublicense or distribute the Program except as expressly provided under this License Any attempt otherwise to copy modify sublicense or distribute the Program is void and will automatically terminate your rights under this License However parties who have received copies or rights from you under this License will not have their licenses terminated so long as such parties remain in full compliance 5 You are not required to accept this License since you have not signed it However nothing else grants you permission to modify or distribute the Program or its derivative works These actions are prohibited by law if you do not accept this License Therefore by modifying or distributing the Program or any work based on the Program you indicate your acceptance of this License to do so and all its terms and conditions for copying distributing or modifying the Program or works based on it 6 Each time you redistribute the Program or any work based on the Program the recipient automatically receives a license from the original licensor to co
63. eturn 1 In this case the processing of the stats is quite simple First we call the tick_stat_node for the st_str_packets packet node to count packets Then a call to stats_tree_tick_pivot on the st_node_packet_types subtree allows us to record statistics by packet type 117 Packet dissection 9 7 How to use conversations Some info about how to use conversations in a dissector can be found in the file doc README developer chapter 2 2 118 Packet dissection 119 Chapter 10 User Interface 10 1 Introduction Wireshark can be logically separated into the backend dissecting of protocols file load save cap turing and the frontend the user interface However there s currently no clear separation between these two parts no clear API definition but this might change in the future The following frontends are currently maintained by the Wireshark development team e Wireshark GTK 1 x based e Wireshark GTK 2 x based e TShark console based There exist other Wireshark frontends not developed nor maintained by the Wireshark development team e Packetyzer Win32 native interface written in Delphi and released under the GPL see http www networkchemistry com products packetyzer e hethereal web based frontend not actively maintained and not finished This chapter is focussed on the Wireshark frontend and especially on the GTK specific things 120 User Interface 10 2
64. eviously asked the same ques tion and maybe already got an answer That way you don t have to wait until someone answers your question Bug database Bugzilla The Wireshark community collects bug reports in a Bugzilla database at http bugs wireshark org This database is filled with manually filed bug reports usually after some discussion on wireshark dev and bug reports from the QA build tools Reporting Problems Note Before reporting any problems please make sure you have installed the latest version of Wireshark If you report problems provide as much information as possible In general just think about what you would need to find that problem if someone else sends you such a problem report Also keep in mind that people compile run Wireshark on a lot of different platforms 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 e g GTK etc You 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 Ifyou get an error warning message copy the text of that message and also a few lines before 11 Introduction and after it if there are some so others may find the build step where things go wrong Please don t give something like I get a warning when compiling x as this won t give any directio
65. f ett items hf data items and a string tag The ett and hf values should be included in the relevant tables like all the other variables your protocol may use The hf variables need to be placed in the structure fragment_table_init amp msg_fragment_table reassembled_table_init amp msg_reassembled_table something like the following Of course the names may need to be adjusted Example 9 18 Reassembling fragments Data static static static static static static static static static static static Qe r hf_msg hf_msg_fragment_overlap_conflicts Message fragment overlapping with conflicting data hf_msg_fragment_multiple_tails hf_msg_fragment_too_long_fragment hf_msg_fragment_error hf_msg_reassembled_in int hf_msg_fragments 1 int hf_msg_fragment 1 int hf_msg_fragment_overlap 1 int hf_msg_fragment_overlap_conflicts int hf_msg_fragment_multiple_tails int hf_msg_fragment_too_long_fragment int hf_msg_fragment_error 1 int hf_msg_reassembled_in 1 gint ett_msg_fragment 1 gint ett_msg_fragments 1 const fragment_items msg_frag_items Fragment subtrees ett_msg_fragment ett_msg_fragments Fragment fields amp hf_msg_fragments amp hf_msg_fragment amp hf_msg_fragment_overlap hf_msg_fragment_overlap_conflicts amp hf_msg_fragment_multiple_tails amp hf_msg_fragment_too_long_fragment amp hf_msg_fragment_error R
66. ffort for you There s no direct way to commit changes to the SVN repository Only a few people are authorised to actually make changes to the source code check in changed files If you want to submit your changes you should make a diff file a patch and upload it to the bug tracker What is a diff file a patch A diff file is a plain text file containing the differences between a pair of files or a multiple of such file pairs A diff file is often also called a patch as it can be used to patch an existing source file or tree with changes from somewhere else The Wireshark community is using patches to transfer source code changes between the authors A patch is both readable by humans and as it is specially formatted by some dedicated tools Here is a small example of a patch for file h that makes the second argument in cf_continue_tail volatile It was created using svn diff described below Index file h file h revision 21134 file h revision 22401 142 7 142 7 param err the error code if an error had occured return one of cf_read_status_t cf_read_status_t cf_continue_tail capture_file cf int to_read int err cf_read_status_t cf_continue_tail capture_file cf volatile int to_read int err Finish reading from end of a capture file The plus sign at the start of a line indicates an added line a minus sign indicates a deleted line com pared to the original sou
67. fix each problem and upload another patch 35 Work with the Wireshark sources e You don t get any reponse to your patch even after a few days or so Possible reason your patch might simply get lost as all core maintainers were busy at that time and forgot to look at your patch Simply send a mail asking if the patch was forgotten or if someone is still looking at it 36 Work with the Wireshark sources 3 10 Apply a patch from someone else Sometimes you need to apply a patch to your private source tree Maybe because you want to try a patch from someone on the developer mailing list or you want to check your own patch before sub mitting A Warning If you have problems applying a patch make sure the line endings CR NL of the patch and your source files match 3 10 1 Using patch Given the file new diff containing a unified diff the right way to call the patch tool depends on what the pathnames in new diff look like If they re relative to the top level source directory for example if a patch to prefs c just has prefs c as the file name you d run it as patch p0 lt new diff If they re relative to a higher level directory you d replace 0 with the number of higher level direct ories in the path e g if the names are Wireshark orig prefs c and wireshark mine prefs c you d run it with patch p1 lt new diff If they re relative to a subdirectory of the top level directory you d run p
68. fo packet_type tvb_get_guint8 tvb 0 pinfo priority tvb_get_ntohs tvb 8 tap_queue_packet foo_tap pinfo amp pinfo This now enables those interested parties to listen in on the details of this protocol conversation 115 Packet dissection 9 6 How to produce protocol stats Given that you have a tap interface for the protocol you can use this to produce some interesting statistics well presumably interesting from protocol traces This can be done in a separate plugin or in the same plugin that is doing the dissection The latter scheme is better as the tap and stats module typically rely on sharing protocol specific data which might get out of step between two different plugins Here is a mechanism to produce statistics from the above TAP interface Example 9 22 Initialising a stats interface register all http trees static void register_foo_stat_trees void stats_tree_register foo foo Foo Packet Types foo_stats_tree_packet foo_stats_tree_init NULL ifndef ENABLE_STATIC G_MODULE_EXPORT const gchar version 0 0 G_MODULE_EXPORT void plugin_register_tap_listener void register_foo_stat_trees endif Working from the bottom up first the plugin interface entry point is defined plu gin_register_tap_listener This simply calls the initialisation function register_foo_stat_trees This in turn calls the stats_tree_register function which takes three strings and t
69. hark It will hopefully guide you around some common problems that frequently appear for new and sometimes even advanced developers of Wireshark Preface 3 Acknowledgements The authors would like to thank the whole Wireshark team for their assistance In particular the au thors would like to thank e Gerald Combs for initiating the Wireshark project e Guy Harris for many helpful hints and his effort in maintaining the various contributions on the mailing lists The authors would also like to thank the following people for their helpful feedback on this docu ment e XXX Please give feedback And of course a big thank you to the many many contributors of the Wireshark development com munity Preface 4 About this document This book was developed by Ulf Lamping It is written in DocBook XML You will find some specially marked parts in this book 2 v 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 developing Wireshark xi Preface 5 Where to get the latest copy of this document The latest copy of this documentation can always be found at http www wireshark org docs in PDF A4 and US letter HTML single and chunked and CHM format Preface 6 Providi
70. he moment we ll leave it as a basic placehold er Example 9 3 Dissection static void dissect_foo tvbuff_t tvb packet_info pinfo proto_tree tree if check_col pinfo gt cinfo COL_PROTOCOL col_set_str pinfo gt cinfo COL_PROTOCOL FOO Clear out stuff in the info column if check_col pinfo gt cinfo COL_INFO col_clear pinfo gt cinfo COL_INFO This function is called to dissect the packets presented to it The packet data is held in a special buf fer referenced here as tvb We shall become fairly familiar with this as we get deeper into the details of the protocol The packet info structure contains general data about the protocol and we can up date information here The tree parameter is where the detail dissection takes place For now we ll do the minimum we can get away with The first two lines check to see if the Protocol column is being displayed in the UI If it is we set the text of this to our protocol so everyone can see it s been recognised The only other thing we do is to clear out any data in the INFO column if it s being displayed At this point we should have a basic dissector ready to compile and install It doesn t do much at present other than identify the protocol and label it 102 9 2 2 Packet dissection In order to compile this dissector and create a plugin a couple of support files are required besides the dissector source in packet foo c e Makefile am T
71. heck_col pinfo gt cinfo COL_INFO col_append_fstr pinfo gt cinfo COL_INFO Message fragment u msg_num if new_tvb take it all next_tvb new_tvb else make a new subset next_tvb tvb_new_subset tvb offset 1 1 else Not fragmented next_tvb tvb_new_subset tvb offset 1 1 pinfo gt fragmented save_fragmented Having passed the fragment data to the reassembly handler we can now check if we have the whole message If there is enough information this routine will return the newly reassembled data buffer After that we add a couple of informative messages to the display to show that this is part of a se quence Then a bit of manipulation of the buffers and the dissection can proceed Normally you will probably not bother dissecting further unless the fragments have been reassembled as there won t be much to find Sometimes the first packet in the sequence can be partially decoded though if you wish Now the mysterious data we passed into the fragment_add_seq_check Example 9 17 Reassembling fragments Initialisation static GHashTable msg_fragment_table NULL static GHashTable msg_reassembled_table NULL static void msg_init_protocol void 111 Packet dissection First a couple of hash tables are declared and these are initialised in the protocol initialisation routine Following that a fragment_items structure is allocated and filled in with a series o
72. hing in the sources you could simply throw away your old sources and reinstall everything just like the first time But be sure that you really haven t changed anything It might be a good idea to simply rename the old dir to have it around just in case you remember later that you really did change something before Well if you did change something in your source tree you have to merge the official changes since the last update into your source tree You will install the content of the zip file into a new directory and use a good merge tool e g http winmerge sourceforge net for Win32 to bring your personal source tree in sync with the official sources again 26 Work with the Wireshark sources 3 5 Build Wireshark 3 5 1 3 5 2 The sources contain several documentation files it s a good idea to look at these files first So after obtaining the sources tools and libraries the first place to look at is doc README developer here you will get the latest infos for Wireshark development for all suppor ted platforms Tip It is a very good idea to first test your complete build environment including running and debugging Wireshark before doing any changes to the source code unless other wise noted The following steps for the first time generation differ on the two major platforms Unix Run the autogen sh script at the top level wireshark directory to configure your build directory autogen
73. his is the UNIX Linux makefile template e Makefile common This contains the file names of this plugin e Makefile nmake This contains the Wireshark plugin makefile for Windows e moduleinfo h This contains plugin version info e moduleinfo nmake This contains DLL version info for Windows e packet foo c This is your dissector source e plugin rc in This contains the DLL resource template for Windows You can find a good example for these files in the agentx plugin directory Makefile common and Makefile am have to be modified to reflect the relevant files and dissector name moduldeinfo h and moduleinfo nmake have to be filled in with the version information Compile the dissector to a DLL or shared library and copy it into the plugin directory of the installation Dissecting the details of the protocol Now that we have our basic dissector up and running let s do something with it The simplest thing to do to start with is to just label the payload This will allow us to set up some of the parts we will need The first thing we will do is to build a subtree to decode our results into This helps to keep things looking nice in the detailed display Now the dissector is called in two different cases In one case it is called to get a summary of the packet in the other case it is called to look into details of the pack et These two cases can be distinguished by the tree pointer If the tree pointer is NULL then we are being asked for a
74. hould result in something like This is perl v5 8 7 built for cygwin thread multi 64int with 1 registered patch see perl V for more detail Copyright 1987 2005 Larry Wall Perl may be copied only under the terms of either the Artistic License or the GNU General Public License which may be found in the Perl 5 source kit Complete documentation for Perl including FAQ lists should be found on this system using man perl or perldoc perl If you have access to the Internet point your browser at http www perl com the Perl Home Page However the version string may vary Win32 native perl A native Win32 perl package can be obtained from http www ActiveState com The installation should be straightforward After correct installation typing at the command line prompt cmd exe gt perl v should result in something like This is perl v5 8 0 built for MSWin32 x86 multi thread with 1 registered patch see perl V for more detail Copyright 1987 2002 Larry Wall Binary build 805 provided by ActiveState Corp http www ActiveState com Built 18 08 02 Feb 4 2003 However the version string may vary 57 Tool Reference 4 8 sed 4 8 1 4 8 2 Sed it the streaming editor It makes it easy for example to replace specially marked texts inside a source code file The Wireshark build process uses this to stamp version strings into various places UNIX or Win32 Cygwin sed Sed is available for most of
75. hree functions 1 This is the tap name that is registered 2 An abbreviation of the stats name 3 The name of the stats module A character can be used to make sub menus 4 The function that will called to generate the stats 5 A function that can be called to initialise the stats data 6 A function that will be called to clean up the stats data In this case we only need the first two functions as there is nothing specific to clean up Example 9 23 Initialising a stats session static const guint8 st_str_packets Total Packets static const guint8 st_str_packet_types FOO Packet Types static int st_node_packets 1 static int st_node_packet_types 1 static void foo_stats_tree_init stats_tree st st_node_packets stats_tree_create_node st st_str_packets 0 TRUE st_node_packet_types stats_tree_create_pivot st st_str_packet_types st_node_packets 116 Packet dissection In this case we create a new tree node to handle the total packets and as a child of that we create a pivot table to handle the stats about different packet types Example 9 24 Generating the stats static int foo_stats_tree_packet stats_tree st packet_info pinfo epan_dissect_t edt const void p struct FooTap pi struct FooTap p tick_stat_node st st_str_packets 0 FALSE stats_tree_tick_pivot st st_node_packet_types val_to_str pi gt packet_type msgtypevalues Unknown packet type d r
76. ight 2003 Free Software Foundation Inc GDB is free software covered by the GNU General Public License and you are welcome to change it and or distribute copies of it under certain conditions Type show copying to see the conditions There is absolutely no warranty for GDB Type show warranty for details This GDB was configured as i686 pc cygwin However the version string may vary ddd GNU Data Display Debugger The GNU Data Display Debugger is a good GUI frontend for GDB and a lot of other command line 45 4 3 4 Tool Reference debuggers so you have to install GDB first It is available for many UNIX like platforms and as the ddd package from the Cygwin setup If GNU DDD isn t already installed or available as a package for your platform you can get it at ht tp www gnu org software ddd make GNU Make Win32 Note Although some effort is made to use make from the Cygwin environment the mainline is still using Microsoft Visual Studio s nmake GNU Make is available for most of the UNIX like platforms and also as the Devel make package from the Cygwin setup If GNU Make isn t already installed or available as a package for your platform you can get it at ht tp www gnu org software make After correct installation make version should result in something like GNU Make 3 81 Copyright C 2006 Free Software Foundation Inc This is free software see the source for copying conditions
77. ile docbook Make file 4 4 8 2 HTML Help Build Files htmlhelp c htmlhelp lib The files htmlhelp c and htmlhelp lib are required to be able to open chm files from Wireshark to show the online help 53 Tool Reference Both files are part of the Platform SDK standalone PSDK or MSVC since 2002 If you still use MSVC 6 you can get them from the HTML Help Workshop mentioned above The related settings in config nmake depend on the MSVC variant you use e MSVC 6 if the HTML Help Workshop is installed set HHC_DIR to its directory e gt MSVC 6 set HHC_DIR to use it the actual value doesn t matter in this case 4 4 9 Debugger Well using a good debugger can save you a lot of development time The debugger you use must match the C compiler Wireshark was compiled with otherwise the de bugger will simply fail or you will only see a lot of garbage 4 4 9 1 Visual Studio integrated debugger You can use the integrated debugger of Visual Studio only available in some of the toolchain pack ages However setting up the environment is a bit tricky as the Win32 build process is using makefiles instead of the dsp dsw files usually used XXX add instructions how to do it 4 4 9 2 Debugging Tools for Windows You could also use the Microsoft Debugging Tools for Windows toolkit which is a standalone GUI debugger Although it s not that comfortable compared to debugging with the Visual Studio integ ra
78. information We can certainly improve the display of the protocol with a bit of extra data The first step is to add some text labels Let s start by labeling the packet types There is some useful support for this sort of thing by adding a couple of extra things First we add a simple table of type to name Example 9 10 Naming the packet types static const value_string packettypenames 1 Initialise 2 Terminate 25 Data Ffy 0 NULL This is a handy data structure that can be used to look up a name for a value There are routines to directly access this lookup table but we don t need to do that as the support code already has that added in We just have to give these details to the appropriate part of the data using the VALS macro Example 9 11 Adding Names to the protocol amp hf_foo_pdu_type FOO PDU Type foo type FT_UINT8 BASE_DEC VALS packettypenames 0x0 NULL HFILL This helps in deciphering the packets and we can do a similar thing for the flags structure For this we need to add some more data to the table though Example 9 12 Adding Flags to the protocol define FOO_START_FLAG 0x01 define FOO_END_FLAG 0x02 define FOO_PRIORITY_FLAG 0x04 static int hf_foo_startflag 1 static int hf_foo_endflag 1 static int hf_foo_priorityflag 1 amp hf_foo_startflag FOO PDU Start Flags foo flags start FT_BOOLEAN 8 NULL FOO_START_FLAG NULL HFILL
79. into chunks and somehow signaled within its protocol To deal with such streams we need several things to trigger from We need to know that this packet is part of a multi packet sequence We need to know how many packets are in the sequence We also need to know when we have all the packets For this example we ll assume there is a simple in protocol signaling mechanism to give details A flag byte that signals the presence of a multi packet sequence and also the last packet followed by an ID of the sequence and a packet sequence number flags SEQUENCE fragment BOOLEAN last_fragment BOOLEAN msg_id INTEGER 0 65535 frag_id INTEGER 0 65535 Example 9 15 Reassembling fragments Part 1 include lt epan reassemble h gt save_fragmented pinfo gt fragmented flags tvb_get_guint8 tvb offset offset if flags amp FL_FRAGMENT fragmented tvbuff_t new_tvb NULL fragment_data frag_msg NULL guint16 msg_seqid tvb_get_ntohs tvb offset offset 2 guintl6 msg_num tvb_get_ntohs tvb offset offset 2 pinfo gt fragmented TRUE frag_msg fragment_add_seq_check tvb offset pinfo msg_seqid ID for fragments belonging together msg_fragment_table list of message fragments msg_reassembled_table list of reassembled messages msg_num fragment sequence number tvb_length_remaining tvb offset fragment length to the end flags amp FL_FRAG_LAST More frag
80. ion string may vary 61 Tool Reference 4 12 Subversion SVN GUI client optional Along with the traditional command line client several GUI clients are available for a number of platforms see http subversion tigris org project_links html A Keep Subversion program versions in sync If you are working with both command line and GUI clients keep the Subversion pro gram versions in sync at least the major minor versions e g 1 4 4 12 1 UNIX or Win32 Cygwin rapidSVN subcommander RapidSVN is a cross platform Subversion frontend based on wxWidgets It can be found at http rapidsvn tigris org Subcommander is another cross platform Subversion frontend It can be found at http subcommander tigris org Cygwin doesn t provide any GUI client for Subversion 4 12 2 Win32 native TortoiseSVN A good Subversion client for Win32 can be found at http tortoisesvn tigris org It will nicely in tegrate into the Windows Explorer window 62 Tool Reference 4 13 diff optional Diff is used to get a file of all differences between two source files trees sometimes called a patch The diff tool isn t needed for building Wireshark but it s needed if you are going to commit your changes back to the Wireshark community Note The recommended way to build patches is using the Subversion client see Sec tion 4 11 Subversion SVN client optional for details You will find more instruct
81. ions in Section 3 9 2 3 Using the diff tool on how to use the diff tool 4 13 1 UNIX or Win32 Cygwin GNU diff Diff is available for most of the UNIX like platforms and as the diffutils package from the Cygwin setup If GNU diff isn t already installed or available as a package for your platform you can get it at ht tp www gnu org software diffutils diffutils html After correct installation typing at the bash command line prompt diff version should result in something like diff GNU diffutils 2 8 7 Written by Paul Eggert Mike Haertel David Hayes Richard Stallman and Len Tower Copyright C 2004 Free Software Foundation Inc This is free software see the source for copying conditions There is NO warranty not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE However the version string may vary 4 13 2 Win32 native diff A native Win32 diff package can be obtained from http gnuwin32 sourceforge net The installa tion should be straightforward The Subversion client TortoiseSVN has a built in diff feature see Section 4 12 2 Win32 native TortoiseSVN It is currently unknown if this tool can be used to create diff files in the required format so other persons can use them 63 Tool Reference 4 14 patch optional The patch utility is used to merge a diff file into your own source tree This tool is only needed if you want to apply a patch diff file fro
82. ireshark sources are sorted in decreasing source timeliness If you plan to commit changes you ve made to the sources it s a good idea to keep your private source tree as current as possible The age mentioned in the following sections indicates the age of the most recent change in that set of the sources Anonymous Subversion access Recommended for development purposes Age a few minutes You can use a Subversion client to download the source code from Wireshark s anonymous Subver sion repository The URL for the repository trunk is http anonsvn wireshark org wireshark trunk See Section 4 11 Subversion SVN client optional on how to install a Subversion client For example to check out using the command line Subversion client you would type svn checkout http anonsvn wireshark org wireshark trunk wire shark The checkout has to be only done once This will copy all the sources of the latest version including directories from the server to your machine This will take some time depending on the speed of your internet connection Anonymous Subversion web interface Recommended for informational purposes only as only individual files can be downloaded Age a few minutes same as anonymous Subversion access The entire source tree of the Subversion repository is available via a web interface at http anons vn wireshark org viewvc viewvc cgi You can view each revision of a particular file as well as
83. it controls and will generate for you a unified diff file compiling the differences To do so after updating your sources from the SVN repository if needed just right click on the highest level dir ectory and choose TortoiseSVN gt Create patch You will be asked for a name and then the diff file will be created The names of the files in the patch will be relative to the directory you have right clicked on so it will need to be applied on that level too When you create the diff file it will include any difference TortoiseSVN finds in files in and under the directory you have right clicked on and nothing else This means that changes you might have made for your specific configuration like modifying config nmake so that it uses your lib direct ory will also be included and you will need to remove these lines from the diff file It also means that only changes will be recorded i e if you have created new files say a new packet xxx for a new protocol dissector it will not be included in the diff you need to add it separately And of course if you have been working separately in two different patches the diff file will include both topics which is probably not a good idea 3 9 2 3 Using the diff tool A diff file is generated by comparing two files or directories between your own working copy and the official source tree So to be able to do a diff you should have two source trees on your com puter one with your w
84. ive but does not normally print such an announcement your work based on the Program is not required to print an announcement hese requirements apply to the modified work as a whole If dentifiable sections of that work are not derived from the Program nd can be reasonably considered independent and separate works in hemselves then this License and its terms do not apply to those ections when you distribute them as separate works But when you istribute the same sections as part of a whole which is a work based n the Program the distribution of the whole must be on the terms of his License whose permissions for other licensees extend to the ntire whole and thus to each and every part regardless of who wrote it DO A e Thus it is not the intent of this section to claim rights or contest your rights to work written entirely by you rather the intent is to exercise the right to control the distribution of derivative or collective works based on the Program In addition mere aggregation of another work not based on the Program with the Program or with a work based on the Program on a volume of a storage or distribution medium does not bring the other work under the scope of this License 3 You may copy and distribute the Program or a work based on it under Section 2 in object code or executable form under the terms of Sections 1 and 2 above provided that you also do one of the following a Accompany it with the complet
85. l dissection For this step we ll need to construct a couple of tables that help with dissection This needs some changes to proto_register_foo First a couple of statically declare arrays Example 9 5 Registering data structures static hf_register_info hf amp hf_foo_pdu_type FOO PDU Type foo type FT_UINT8 BASE_DEC NULL 0x0 NULL HFILL l Setup protocol subtree array static gint ett amp ett_foo Then after the registration code we register these arrays Example 9 6 Registering data structures proto_register_field_array proto_foo hf array_length hf proto_register_subtree_array ett array_length ett The variables hf_foo_pdu_type and ett_foo also need to be declared somewhere near the top of the file Example 9 7 Dissector data structure globals static int hf_foo_pdu_type 1 static gint ett_foo 1 Now we can enhance the protocol display with some detail Example 9 8 Dissector starting to dissect the packets if tree we are being asked for details proto_item ti NULL proto_tree foo_tree NULL ti proto_tree_add_item tree proto_foo tvb 0 1 FALSE foo_tree proto_item_add_subtree ti ett_foo proto_tree_add_item foo_tree hf_foo_pdu_type tvb 0 1 FALSE 104 Packet dissection Now the dissection is starting to look more interesting We have picked apart our first bit of the pro tocol One byte of data at the sta
86. l start with a Frame dissector which dissects the packet details of the capture file itself e g timestamps passes the data on to an Ethernet frame dissector that decodes the Ethernet head er and then passes the payload to the next dissector e g IP and so on At each stage details of the packet will be decoded and displayed Dissection can be implemented in two possible ways One is to have a dissector module compiled into the main program which means it s always available Another way is to make a plugin a shared library DLL that registers itself to handle dissection There is little difference in having your dissector as either a plugin or build in On the Win32 plat form you have limited function access through what s listed in libwireshark def but that is mostly complete The big plus is that your rebuild cycle for a plugin is much shorter than for a build in one So start ing with a plugin makes initial development simpler while deployment of the finished code may well be done as build in dissector 100 Packet dissection 9 2 Adding a basic dissector 9 2 1 Let s step through adding a basic dissector We ll start with the made up foo protocol It consists of the following basic items e A packet type 8 bits possible values 1 initialisation 2 terminate 3 data e A set of flags stored in 8 bits 0x01 start packet 0x02 end packet 0x04 priority packet e A sequence number 16 bits e An IP
87. le for your platform you should download the source and try to build it Please report your experiences to wireshark dev AT wireshark org Binary packages are available for at least the following platforms Unix e Apple Mac OS X e BeOS e FreeBSD e HP UX e IBM AIX e NetBSD e OpenBSD e SCO UnixWare OpenUnix e SGI Irix e Sun Solaris Intel e Sun Solaris Sparc e Tru64 UNIX formerly Digital UNIX Linux e Debian GNU Linux e Gentoo Linux e IBM S 390 Linux Red Hat e Mandrake Linux e PLD Linux e Red Hat Linux e Rock Linux e Slackware Linux Introduction e Suse Linux 1 3 3 Microsoft Windows Thanks to the Win32 API development on all Windows platforms will be done in a very similar way All Windows platforms referred to as Win32 Win or Windows may be used with the same meaning Older Windows versions are no longer supported by Wireshark As Windows CE differs a lot compared to the other Windows platforms mentioned Wireshark will not run on Windows CE and there are no plans to support it e Windows Server 2003 XP 2000 1 4 Introduction Development and maintenance of Wireshark 1 4 1 1 4 2 Wireshark was initially developed by Gerald Combs Ongoing development and maintenance of Wireshark is handled by the Wireshark team a loose group of individuals who fix bugs and provide new functionality There have also been a large number of people who have contributed protocol diss
88. ledge on a specific topic maybe a net work protocol you know well you can edit the wiki pages by simply using your webbrowser 1 7 3 FAQ The Frequently Asked Questions will list often asked questions and the corresponding answers Read the FAQ Before sending any mail to the mailing lists below be sure to read the FAQ as it will often answer the question s you might have This will save yourself and others a lot of time keep in mind that a lot of people are subscribed to the mailing lists You will find the FAQ inside Wireshark by clicking the menu item Help Contents and selecting the FAQ page in the upcoming dialog An online version is available at the Wireshark website http Awww wireshark org faq html You might prefer this online version as it s typically more up to date and the HTML format is easier to use 1 7 4 Other sources If you don t find the information you need inside this book there are various other sources of in formation e the file doc README developer and all the other README xxx files in the source code these are various documentation files on different topics e the Wireshark source code e tool documentation of the various tools used e g manpages of sed gcc e the different mailing lists see Section 1 7 5 Mailing Lists 1 7 5 Mailing Lists There are several mailing lists available on specific Wireshark topics 1 7 6 1 7 7 Introduction wireshark a
89. llution down Normally this isn t a problem unless your dissector gets so big it has to span multiple files Then a module variable which contains the UDP port that we ll assume we are dissecting traffic for 101 Packet dissection Next a dissector reference that we ll initialise later Now we have the basics in place to interact with the main program we had better fill in those miss ing functions Let s start with register function First a call to proto_register_protocol that registers the protocol We can give it three names that will be used for display in various places The full and short name are used in e g the Preferences and Enabled protocols dialogs as well as the generated field name list in the documentation The ab breviation is used as the display filter name Next we need a handoff routine Example 9 2 Dissector Handoff void proto_reg_handoff_foo void static gboolean initialized FALSE if initialized foo_handle create_dissector_handle dissect_foo proto_foo dissector_add udp port global_foo_port foo_handle What s happening here We are initialising the dissector if it hasn t been initialised yet First we cre ate the dissector This registers a routine to be called to do the actual dissecting Then we associate it with a UDP port number so that the main program will know to call us when it gets UDP traffic on that port Now at last we get to write some dissecting code For t
90. m someone else probably from the developer mailing list to try out in your own private source tree Tip Ny Unless you are in the rare case needing to apply a patch to your private source tree you won t need the patch tool installed You will find more instructions in Section 3 10 Apply a patch from someone else on how to use the patch tool 4 14 1 UNIX or Win32 Cygwin patch Patch is available for most of the UNIX like platforms and as the patch package from the Cygwin setup If GNU patch isn t already installed or available as a package for your platform you can get it at ht tp www gnu org software patch patch html After correct installation typing at the bash command line prompt patch version should result in something like patch 2 5 8 Copyright C 1988 Larry Wall Copyright C 2002 Free Software Foundation Inc This program comes with NO WARRANTY to the extent permitted by law You may redistribute copies of this program under the terms of the GNU General Public License For more information about these matters see the file named COPYING written by Larry Wall and Paul Eggert However the version string may vary 4 14 2 Win32 native patch A native Win32 patch package can be obtained from http gnuwin32 sourceforge net The installa tion should be straightforward The Subversion client TortoiseSVN has a built in patch feature see Section 4 12 2 Win32 native TortoiseS VN Th
91. ments We start by saving the fragmented state of this packet so we can restore it later Next comes some protocol specific stuff to dig the fragment data out of the stream if it s present Having decided it is present we let the function fragment_add_seq_check do its work We need to provide this with a certain amount of data e The tvb buffer we are dissecting e The offset where the partial packet starts 110 Packet dissection e The provided packet info e The sequence number of the fragment stream There may be several streams of fragments in flight and this is used to key the relevant one to be used for reassembly e The msg_fragment_table and the msg_reassembled_table are variables we need to declare We ll consider these in detail later e msg_num is the packet number within the sequence e The length here is specified as the rest of the tvb as we want the rest of the packet data e Finally a parameter that signals if this is the last fragment or not This might be a flag as in this case or there may be a counter in the protocol Example 9 16 Reassembling fragments part 2 new_tvb process_reassembled_data tvb offset pinfo Reassembled Message frag_msg amp msg_frag_items NULL msg_tree if frag_msg Reassembled if check_col pinfo gt cinfo COL_INFO col_append_str pinfo gt cinfo COL_INFO Message Reassembled else Not last packet of reassembled Short Message if c
92. message This method dissects fully reassembled messages static void dissect_foo_message tvbuff_t tvb packet_info pinfo proto_tree tree TODO implement your dissecting code determine PDU length of protocol foo static guint get_foo_message_len packet_info pinfo tvbuff_t tvb int offset TODO change this to your needs return guint tvb_get_ntohl tvb offsett 4 e g length is at offset 4 As you can see this is really simple Just call tcp_dissect_pdus in your main dissection routine and move you message parsing code into another function This function gets called 113 Packet dissection whenever a message has been reassembled The parameters tvb pinfo and tree are just handed over to tcp_dissect_pdus The 4th parameter is a flag to indicate if the data should be reassebled or not This could be set according to a dissector preference as well Parameter 5 indicates how much data has at least to be available to be able to determine the length of the foo message Parameter 6 is a function pointer to a method that returns this length It gets called when at least the number of bytes given in the previous parameter is available Parameter 7 is a function pointer to your real message dissector 114 Packet dissection 9 5 How to tap protocols Adding a Tap interface to a protocol allows it to do some useful things In particular you can pro duce protocol statistics from the tap
93. n to look at 4 4 Don t send large files Do not send large files gt 100KB to the mailing lists just place a note that further data is available on request Large files will only annoy a lot of people on the list who are not interested in your specific problem If required you will be asked for further data by the persons who really can help you Don t send confidential information If you send captured data to the mailing lists or add it to your bug report be sure it doesn t contain any sensitive or confidential information such as passwords 1 7 8 Reporting Crashes on UNIX Linux platforms When reporting crashes with Wireshark it is helpful if you supply the traceback information besides the information mentioned in Section 1 7 7 Reporting Problems You can obtain this traceback information with the following commands gdb whereis wireshark cut f2 d cut d f2 core gt amp bt txt backtrace 3 2 J 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 shown above but it will not be echoed The D Control D that is press the Control key and the D key together will cause gdb to exit This will leave you with a file called bt t xt 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 you
94. n 3 3 Obtain the Wireshark sources By default the libraries will be downloaded and installed into C wireshark win32 libs You can change this to any other location by editing the file config nmake and changing the line containing the WIRESHARK_LIBS setting to your favourite place use an absolute path here Then enter at the command line gt nmake f Makefile nmake setup This will first check for all the various tools needed to build Wireshark as described already in Sec tion 2 2 7 Verify installed tools Then it will download the zipped libraries together around 30MB from the server location at ht tp anonsvn wireshark org wireshark win32 libs trunk packages into the directory specified by WIRESHARK_LIBS and install unzip all required library files there If you have problems downloading the library files you might be connected to the internet through a proxy firewall In this case see the wget proxy comment in Section 4 15 Win32 GNU wget optional Update of a previous download As new versions of the libraries become available maybe with bugfixes or some new functionality your libraries get outdated You could simply remove everything in the WIRESHARK LIBS dir and call the setup target again but that would require a download of every file again which isn t necessary The following will bring your libraries up to date e Update your Wireshark sources to the latest SVN files
95. n show the decompressed bytes as well as the original One procedural step is to add a handler to free the data when it s no longer needed In this case as g_malloc was used to allocate the memory g_free is the appropriate function After this has been set up the remainder of the dissector can dissect the buffer next_tvb as it s a new buffer the offset needs to be 0 as we start again from the beginning of this buffer To make the rest of the dissector work regardless of whether compression was involved or not in the case that com pression was not signaled we use the tvb_new_subset to deliver us a new buffer based on the old one but starting at the current offset and extending to the end This makes dissecting the packet from this point on exactly the same regardless of compression 109 Packet dissection 9 4 How to reassemble split packets Some protocols have times when they have to split a large packet across multiple other packets In this case the dissection can t be carried out correctly until you have all the data The first packet doesn t have enough data and the subsequent packets don t have the expect format To dissect these packets you need to wait until all the parts have arrived and then start the dissection 9 4 1 How to reassemble split UDP packets As an example let s examine a protocol that is layered on top of UDP that splits up its own data stream If a packet is bigger than some given size it will be split
96. nd easy to understand For further reference see the following documents e GNOME Human Interface Guidelines at http developer gnome org projects gup hig e KDE user interface related documents at http developer kde org documentation library ui html e Win32 XXX where are good Win32 styleguides available 124 User Interface 10 4 Adding Extending Dialogs This is usually the main area for contributing new user interface features XXX add the various functions from gtk dlg_utils h 125 User Interface 10 5 Widget naming It seems to be common sense to name the widgets with some descriptive trailing characters like e xy_lb gtk_label_newQ e xy_cb gtk_checkbox_new e XXX add more examples However this schema isn t used at all places inside the code 126 User Interface 10 6 Common GTK programming pitfalls There are some common pitfalls in GTK programming 10 6 1 Usage of gtk_widget_show gtk_widget_show_all When a GTK widget is created it will be hidden by default In order to show it a call to gtk_widget_show has to be done It isn t necessary to do this for each and every widget created A call to gtk_widget_show_all on the parent of all the widgets in question e g a dialog window can be done so all of its child wid gets will be shown too 127 User Interface 128 Appendix A This Document s License GPL As with the original licence
97. ng feedback about this document Should you have any feedback about this document please send it to the authors through wireshark dev AT wireshark org xiii Preface xiv Part I Wireshark Build Environment Part I Wireshark Build Environment The first part describes how to set up the tools libraries and source needed to generate Wire shark and how to do some typical development tasks Part II Wireshark Development The second part describes how the Wireshark sources are structured and how to change the sources e g adding a new dissector Chapter 1 Introduction 1 1 Introduction This chapter will provide you with information about Wireshark development in general Introduction 1 2 What is Wireshark Well if you want to start Wireshark development you might already know what Wireshark is do ing If not please have a look at the Wireshark User s Guide which will provide a lot of general in formation about it Introduction 1 3 Platforms Wireshark runs on 1 3 1 1 3 2 Wireshark currently runs on most UNIX platforms and various Windows platforms It requires GTK GLib libpcap and some other libraries in order to run As Wireshark is developed in a platform independent way and uses libraries such as the GTK GUI library which are available for a lot of different platforms it s thus available on a wide variety of platforms If a binary package is not availab
98. nnounce This mailing list will inform you about new program releases which usually 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 People post questions about the development of Wireshark others hopefully provide answers If you want to start developing a protocol dissector join this list wireshark bugs This list is for Wireshark developers Everytime a change to the bug database occurs a mail to this mailing list is generated If you want to be notified about all the changes to the bug database join this list De tails about the bug database can be found in Section 1 7 6 Bug data base Bugzilla wireshark commits This list is for Wireshark developers Everytime a change to the SVN repository is checked in a mail to this mailing list is generated If you want to be notified about all the changes to the SVN repository join this list Details about the SVN repository can be found in Section 3 2 6 The Wireshark Subversion repository You can subscribe to each of these lists from the Wireshark web site http www wireshark org Simply select the mailing lists link on the left hand side of the site The lists are archived at the Wireshark web site as well Tip You can search in the list archives to see if someone pr
99. nt in Visual C 2005 and in Visual C NET 4 4 6 1 msvert dll Version 6 0 Redistributables weren t an issue with MSVC 6 as any realistic installer target system gt Win95 already contains the corresponding msvert dll 4 4 6 2 msvcr70 dll Version 7 0 2002 Visual Studio NET 2002 comes with this dll and it s mentioned in redist txt NET Framework SDK 1 0 doesn t even come with this dll XXX Is this file available with the NET 1 0 runtime dotnetfx exe so it could be shipped instead Do we want it that way 4 4 6 3 msvcr71 dll Version 7 1 2003 Visual Studio NET 2003 comes with this dll and it s mentioned in redist txt NET Framework SDK 1 1 comes with this dll but it s NOT mentioned in redist txt XXX Is this file available with the NET 1 1 runtime dotnetfx exe so it could be shipped instead Do we want it that way 4 4 6 4 msvcr80 dll vcredist_x86 exe Version 8 0 2005 There are three redistribution methods that MSDN mentions for MSVC 8 see Choosing a De ployment Method 1 Redistributable Merge Modules kind of loadable modules for building msi installers not suitable for Wireshark s NSIS based installer 2 copy the folder content of Microsoft VC80 CRT to the target directory e g C program files Wireshark 3 vcredist_x86 exe needs to be executed on the target machine MSDN recommends this for the 2005 Express Editions To save installer size MSV
100. o Visual Stu Yes Commercial MSVC2003 Microsoft dio NET 1 Visual Stu 2003 dio NET 2003 Vc7 bi n vcvars32 b at Visual Stu Yes Commercial MSVC2005_ Microsoft dio 2005 Visual Stu dio 8 VC bin vc vars32 bat Visual C Yes Free __Down Free_Down MS Microsoft vcre 2005 Ex 474MB load VC2005EE Visual Stu dist_x86 exe press Edition load dio 3 420MB 8 V C bin vc recommend vars32 bat ed Visual Stu Yes Beta No Microsoft beta only dio 2008 Visual Stu not yet im dio Code Name plemented 9 0 VC bin v Orcas cvars32 bat Visual Stu Yes Beta No Microsoft beta only dio 2008 Ex Visual Stu press Edition not yet im dio plemented 9 0 VC bin v Code Name cvars32 bat Orcas 48 4 4 2 Tool Reference NET Frame No Free Down DOTNET10 Mi can t build work SDK 104MB crosoft NET setup 3 version 1 0a load Frame workS DK Bin corv ars bat Free Down NET Frame No Free Down load DOTNETI11 Mi can t build work SDK 106MB crosoft NET setup Version 1 1 5 load 420MB SDK v1 1 Bi n sdkvars bat NET Frame No Free Down DOTNET20 Mi vcre work 2 0 363MB crosoft NET dist_x86 exe SDK load SDK v2 0 Bi 3 n sdkvars bat Windows No Free_Down No Microsoft vcre SDK for 1188M SDKs Wind dist_x86 exe Windows loadB not yet im ows v6 0 Bi 3 Vista and plemented n SetEnv C md N
101. o test also on a different machine than the developer machine Compiler dependent This step depends on the compiler variant used for other variants than the re commended Visual C 2005 Express Edition see the table at Section 4 4 Microsoft compiler toolchain Win32 native Quick Setup 20 Chapter 3 Work with the Wireshark sources 3 1 Introduction This chapter will explain how to work with the Wireshark source code It will show you how to get the source compile the source submit changes However this chapter will not explain the source file contents in detail such as where to find a spe cific functionality This is done in Section 7 1 Source overview 21 Work with the Wireshark sources 3 2 The Wireshark Subversion repository 3 2 1 Subversion is used to keep track of the changes made to the Wireshark source code The Wireshark source code is stored inside Wireshark project s Subversion repository located at a server at the wireshark org domain To qoute the Subversion book about What is Subversion Subversion is a free open source version control system That is Subversion manages files and dir ectories over time A tree of files is placed into a central repository The repository is much like an ordinary file server except that it remembers every change ever made to your files and directories This allows you to recover older versions of your data or examine th
102. o look useful Now let s finish off dissecting the simple protocol We need to add a few more variables to the hf ar ray and a couple more procedure calls Example 9 9 Wrapping up the packet dissection static int hf_foo_flags 1 static int hf_foo_sequenceno 1 static int hf_foo_initialip 1 amp hf_foo_flags FOO PDU Flags foo flags FT_UINT8 BASE_HEX NULL 0x0 NULL HFILL amp hf_foo_sequenceno FOO PDU Sequence Number foo seqn FT_UINT16 BASE_DEC NULL 0x0 NULL HFILL ky amp hf_foo_initialip FOO PDU Initial IP foo initialip FT_IPv4 BASE_NONE NULL 0x0 NULL HFILL Ky gint offset 0 ti proto_tree_add_item tree proto_foo tvb 0 1 FALSE foo_tree proto_item_add_subtree ti ett_foo 105 Packet dissection proto_tree_add_item proto_tree_add_item proto_tree_add_item proto_tree_add_item foo_tree hf_foo_pdu_type tvb offset 1 FALSE offset 1 foo_tree hf_foo_flags tvb offset 1 FALSE offset 1 foo_tree hf_foo_sequenceno tvb offset 2 FALSE offset 2 foo_tree hf_foo_initialip tvb offset 4 FALSE offset 4 This dissects all the bits of this simple hypothetical protocol We ve introduced a new variable offset into the mix to help keep track of where we are in the packet dissection With these extra bits in place the whole protocol is now dissected 9 2 3 Improving the dissection
103. ompletely dif ferent functionality you ll need the MSVC link If your link command looks something like usr bin link the link command of cygwin takes precedence over the MSVC one To fix this you can change your PATH environment setting or simply rename the link exe in cygwin If you rename it make sure to remember that a cygwin update may provide a new version of it Install Libraries 1 If you ve closed cmd exe in the meantime prepare cmd exe again 2 nmake f Makefile nmake setup downloads libraries using wget and installs them this may take a while 3 Ifthe download fails you may be behind a restrictive firewall see the wget manual for ways to use a proxy Distclean Sources The released Wireshark sources contain files that are prepared for a UNIX build e g config h You must distclean your sources before building the first time 1 If you ve closed cmd exe in the meantime prepare cmd exe again 2 nmake f Makefile nmake distclean to cleanup the Wireshark sources 2 2 10 Build Wireshark 18 Quick Setup Now it s time to build Wireshark 1 If you ve closed cmd exe in the meantime prepare cmd exe again 2 nmake f Makefile nmake all to build Wireshark 3 wait for Wireshark to compile this may take a while 4 run C wireshark wireshark gtk2 wireshark exe and check if it starts 5 check Help About if it shows your private program version e g Version 0 99 4 myprotocol123 you might
104. ons There is NO warranty not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE However the version string may vary Win32 native bison A native Win32 yacc bison package can be obtained from http gnuwin32 sourceforge net The in stallation should be straightforward 59 Tool Reference 4 10 flex Flex is a free implementation of lexx 4 10 1 UNIX or Win32 Cygwin flex Flex is available for most of the UNIX like platforms and as the flex package from the Cygwin setup If GNU flex isn t already installed or available as a package for your platform you can get it at ht tp www gnu org software flex After correct installation typing at the bash command line prompt flex version should result in something like flex version 2 5 4 However the version string may vary 4 10 2 Win32 native flex A native Win32 lexx flex package can be obtained from http gnuwin32 sourceforge net The in stallation should be straightforward 60 Tool Reference 4 11 Subversion SVN client optional The Wireshark project uses its own Subversion or short SVN server to keep track of all the changes done to the source code Details about the usage of Subversion in the Wireshark project can be found in Section 3 2 The Wireshark Subversion repository If you want to work with the source code and are planning to commit your changes back to the Wireshark community it is recommende
105. ools After you ve installed the Wireshark sources see Section 3 3 Obtain the Wireshark sources you can check the correct installation of all tools by using the verify_tools target of the Make file nmake from the source package 2 2 8 2 2 9 Quick Setup A Warning You will need the Wireshark sources and some tools nmake bash installed before this verification is able to work Enter at the command line cmd exe not Cygwin s bash gt nmake f Makefile nmake verify_tools This will check for the various tools needed to build Wireshark Checking for required applications cl cygdrive c Programme Microsoft Visual Studio 8 VC BIN cl link cygdrive c Programme Microsoft Visual Studio 8 VC BIN 1link nmake cygdrive c Programme Microsoft Visual Studio 8 VC BIN nmake bash usr bin bash bison usr bin bison flex usr bin flex env usr bin env grep usr bin grep usr bin find usr bin find perl usr bin perl env usr bin env C python24 python exe cygdrive c python24 python exe sed usr bin sed unzip usr bin unzip wget usr bin wget If you have problems with all the first three items cl link nmake check if you called vevars32 SetEnv as mentioned in Section 2 2 6 Prepare cmd exe which will fix your PATH settings However the exact text will be slightly different depending on the MSVC version used Unfortunately the link command is defined both in cygwin and in MSVC each with c
106. orking copy containing your changes and one with the official source tree hopefully the latest SVN files from www wireshark org If you have only changed a single file you could type something like this diff r u strip trailing cr svn file c work file c gt foo diff To get a diff file for your complete directory including subdirectories you could type something like this diff N r u strip trailing cr svn dir working dir gt foo diff It s a good idea to do a make distclean before the actual diff call as this will remove a lot of 33 Work with the Wireshark sources temporary files which might be otherwise included in the diff After doing the diff you should edit the foo diff file and remove unnecessary things like your private changes to the con fig nmake file Table 3 1 Some useful diff options Option Purpose N Add new files when used in conjuction with r r Recursively compare any subdirectories found u Output unified context strip trailing cr Strip trailing carriage return on input This is useful for Win32 x PAT Exclude files that match PAT This could be something like x obj to exclude all win32 ob ject files The diff tool has a lot options they can be listed with diff help 3 9 3 Some tips for a good patch Some tips that will make the merging of your changes into the SVN tree much more likely and you want exactly that don t you
107. ory e build e create binary package s installer e create source package and check completeness e run regression tests Each step is represented at the status page by a rectangle green if it succeeded or red if it failed Most steps provide a link to the corresponding console logfile to get additional information The Buildbot runs on a platform collection that represents the different platform specialties quite well e Windows XP x86 Win32 little endian MSVC e Ubuntu x86 Linux little endian gcc e Solaris SPARC Solaris big endian gcc e Mac OS X PPC BSD big endian gcc Each platform is represented at the status page by a single column the most recent entries are at the top Introduction 1 7 Reporting problems and getting help If you have problems or need help with Wireshark there are several places that may be of interest to you well beside this guide of course 1 7 1 Website You will find lot s of useful information on the Wireshark homepage at http www wireshark org 1 7 2 Wiki The Wireshark Wiki at http wiki wireshark org provides a wide range of information related to Wireshark and packet capturing in general You will find a lot of information not part of this de veloper s guide For example there is an explanation how to capture on a switched network an on going effort to build a protocol reference and a lot more And best of all if you would like to contribute your know
108. ou have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation If the Program does not specify a version number of this License you may choose any version ever published by the Free Software Foundation 10 If you wish to incorporate parts of the Program into other free programs whose distribution conditions are different write to the author to ask for permission For software which is copyrighted by the Free Software Foundation write to the Free Software Foundation we sometimes make exceptions for this Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally NO WARRANTY 11 BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE THERE IS NO WARRANTY FOR THE PROGRAM TO THE EXTENT PERMITTED BY APPLICABLE LAW EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND OR OTHER PARTIES PROVIDE THE PROGRAM AS IS WITHOUT WARRANTY OF ANY KIND EITHER EXPRESSED OR IMPLIED INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU SHOULD THE PROGRAM PROVE DEFECTIVE YOU ASSUME THE COST OF ALL NECESSARY SERVICING REPAIR OR CORRECTION 12 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY C
109. process creates a clean build environment in pack aging rpm BUILD every time the RPM is built The settings controlling the build are in pack aging rpm SPECS wireshark spec in After editing the settings in this file configure must be run again in the wireshark direcrory to generate the actual specification script A Warn The SPEC file contains settings for the configure used to set the RPM build envir onment These are completely independent of any settings passed to the usual Wire shark configure In the wireshark directory type make rpm package to build the RPM Once it is done there will be a message stating where the built RPM can be found Tip Because this does a clean build as well as constructing the package this can take quite a long time 3 12 3 Win32 NSIS exe installer The Nullsoft Install System is a free installer generator for Win32 based systems instructions how to install it can be found in Section 4 17 Win32 NSIS optional NSIS is script based you will find the Wireshark installer generation script at packaging nsis wireshark nsi You will probably have to modify the MAKENSIS setting in the config nmake file to specify where the NSIS binaries are installed In the wireshark directory type gt nmake f makefile nmake packaging to build the installer 40 Work with the Wireshark sources Please be patient while the compression is done it will take some time
110. protecting the integrity of the free software distribution system which is implemented by public license practices Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system it is up to the author donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License 8 If the distribution and or use of the Program is restricted in certain countries either by patents or by copyrighted interfaces the original copyright holder who places the Program under this License may add an explicit geographical distribution limitation excluding those countries so that distribution is permitted only in or among countries not thus excluded In such case this License incorporates the limitation as if written in the body of this License 9 The Free Software Foundation may publish revised and or new versions of the General Public License from time to time Such new versions will be similar in spirit to the present version but may differ in detail to address new problems or concerns 131 This Document s License GPL Each version is given a distinguishing version number If the Program specifies a version number of this License which applies to it and any later version y
111. py distribute or modify the Program subject to these terms and conditions You may not impose any further restrictions on the recipients exercise of the rights granted herein You are not responsible for enforcing compliance by third parties to this License 7 If as a consequence of a court judgment or allegation of patent infringement or for any other reason not limited to patent issues conditions are imposed on you whether by court order agreement or otherwise that contradict the conditions of this License they do not excuse you from the conditions of this License If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations then as a consequence you may not distribute the Program at all For example if a patent license would not permit royalty free redistribution of the Program by all those who receive copies directly or indirectly through you then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Program If any portion of this section is held invalid or unenforceable under any particular circumstance the balance of the section is intended to apply and the section as a whole is intended to apply in other circumstances It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims this section has the sole purpose of
112. r operating system s debugger You should mail the traceback to the wireshark dev AT wireshark org mailing list or append it to your bug report 1 7 9 Reporting Crashes on Windows platforms The Windows distributions don t contain the symbol files pdb because they are very large For this reason it s not possible to create a meaningful backtrace file from it You should report your crash just like other problems using the mechanism from Section 1 7 7 Reporting Problems 12 Introduction Chapter 2 Quick Setup 2 1 UNIX Installation All the tools required are usually installed on a UNIX developer machine If a tool is not already installed on your system you will typically use the installation package from your distribution by your favourite package manager aptitude yum synaptics If an install package is not available or you have a reason not to use it maybe because it s simply too old you can install that tool from source code The following sections will provide you with the webpage addresses where you can get these sources Quick Setup 2 2 Win32 Step by Step Guide 2 2 1 2 2 2 A quick setup guide for Win32 with recommended configuration A Warning Unless you know exactly what you are doing you should strictly follow the re commendations Install Microsoft C compiler and Platform SDK You need to install 1 C compiler Download 474MB and install Visual C 200
113. rces We prefer to use so called unified diff files in Wireshark development three unchanged lines be fore and after the actual changed parts are included This makes it much easier for a merge patch 32 Work with the Wireshark sources tool to find the right place s to change in the existing sources 3 9 2 Generate a patch There are several ways to generate patches The preferred way is to generate them from an updated Subversion tree since it avoids unnecessary integration work 3 9 2 1 Using the svn command line client svn diff changed_files gt svwn diff Use the command line svn client to generate a patch in the required format from the changes you ve made to your working copy If you leave out the name of the changed file the svn client searches for all changes in the working copy and usually produces a patch containing more than just the change you want to send Therefore you should always check the produced patch file If you ve added a new file e g packet myprotocol c you can use svn add to add it to your local tree before generating the patch Similarly you can use svn rm for files that should be re moved 3 9 2 2 Using the diff feature of the GUI Subversion clients Most if not all of the GUI Subversion clients RapidSVN TortoiseSVN have a built in diff feature If you use TortoiseS VN TortoiseSVN to be precise Subversion keeps track of the files you have changed in the directories
114. released and latest Sub version repository versions are then identical again 25 Work with the Wireshark sources 3 4 Update the Wireshark sources After you ve obtained the Wireshark sources for the first time you might want to keep them in sync with the sources at the Subversion repository 3 Take a look at the buildbot first As development evolves the Wireshark sources are compilable most of the time but not always You may take a look at the Section 1 6 Automated Builds Buildbot first to see if the sources are currently in a good shape 3 4 1 with Anonymous Subversion access After the first time checkout is done updating your sources is simply done by typing in the Wire shark source dir svn update This will only take a few seconds even on a slow internet connection It will replace old file ver sions by new ones If you and someone else have changed the same file since the last update Sub version will try to merge the changes into your private file this works remarkably well 3 4 2 from zip files Independent of the way you retrieve the zip file of the Wireshark sources as described in Sec tion 3 3 Obtain the Wireshark sources the way to bring the changes from the official sources in to your personal source tree is identical First of all you will download the new zip file of the official sources the way you did it the first time If you haven t changed anyt
115. rms and as the python package from the Cyg win setup If Python isn t already installed or available as a package for your platform you can get it at http www python org After correct installation typing at the bash command line prompt python V should result in something like Python 2 4 3 However the version string may vary Win32 native python Have a look at http python org download to download the latest stable release You can download a setup there which will install the python system typically into C Python25 or similiar After correct installation typing at the command line prompt cmd exe this must be entered in the Python directory the installer won t set the PATH C Python25 gt python V should result in something like Python 2 5 However the version string may vary 56 Tool Reference 4 7 perl 4 7 1 4 7 2 Perl is an interpreter based programming language The homepage of the perl project is http www perl com Perl is used to convert various text files into usable source code Perl version 5 6 and above should be working fine UNIX or Win32 Cygwin perl Perl is available for most of the UNIX like platforms and as the perl package from the Cygwin setup If perl isn t already installed or available as a package for your platform you can get it at http www perl com After correct installation typing at the bash command line prompt perl version s
116. rom which the package manager checks the dependencies and installs the software e Red Hat rpm file A user of a Red Hat Package Manager RPM based system obtains an rpm file from which the package manager checks the dependencies and installs the software e Solaris A Solaris user obtains a file from which the package manager PKG checks the depend encies and installs the software However if you want to start developing with Wireshark the binary distributions won t be too help ful as you need the source files of course For details about how to build these binary distributions yourself e g if you need a distribution for a special audience see Section 3 12 Binary packaging Source code distributions It s still common for UNIX developers to give the end user a source tarball and let the user compile it on their target machine configure make make install However for different UNIX Linux dis tributions it s becoming more common to release binary packages e g deb or rpm files these days You should use the released sources if you want to build Wireshark from source on your platform for productive use However if you going to develop changes to the Wireshark sources it might be better to use the latest SVN sources For details about the different ways to get the Wireshark source code see Section 3 3 Obtain the Wireshark sources Before building Wireshark from a source distribution make sure you hav
117. rrsersrrreerrrereree 11 1 7 7 Reporting Problems ceeceeceecsceeeceeeeeceeceeeeeatereeenereeaner 11 1 7 8 Reporting Crashes on UNIX Linux platforms 1 0 0 0 eee 12 1 7 9 Reporting Crashes on Windows platforms ce cceeeeee eee 12 2 QUICK Setup isi eaor ee bec b ane tee dy EENS EEEE EEEE esa EPER EER NEE E ES 14 2 1 UNEX Installation nsec eei a oere oeoa iiss 14 2 2 Win32 Step by Step Guide sorires niise ar eeann e a ses 15 2 2 1 Install Microsoft C compiler and Platform SDK 15 2 2 2 Install Cy 9 Wim s ei fs csag dae d i oE aa eae ER a E STRESA EER PADER uies 15 2 2 3 Install Python isss soiien e e re E a a ia 16 2 2 4 Install Subversion Client sseesneeeeseeeesrerrsrerrrrresrerrsrrrerene 16 2 2 5 Install and Prepare Sources seessesesseererrerrsrerrerrerrsrrerreeeere 16 2 2 0 Prepare cmd EXE ao eE E E T EENE I E ETAS 17 2 2 le N enfymstaled tools nnn a A ER 17 2 2 8 Install LIBES o o esse eh ee 18 2 2 9 DisStCl an SOUrCES onono E RE A SEE ERS SE 18 2 2 10 Build Wireshark i asinine norgeiir ip o reaR TEES EES 18 2 2 11 Debug Environment Setup XXX eeseseseerrsrrerrrrerrrrrerrrerene 19 2 2 12 Optional Create User s and Developer s Guide 08 19 2 2 13 Optional Create a Wireshark Installer 1 0 0 0 cece eee 19 3 Work with the Wireshark sources 0c cee cee cence eee e cence eect eeene een eeneeeneeeees 21 321i Introductions 3
118. rt of the packet that defines the packet type for foo protocol The proto_item_add_subtree call has added a child node to the protocol tree which is where we will do our detail dissection The expansion of this node is controlled by the ett_foo variable This re members if the node should be expanded or not as you move between packets All subsequent dis section will be added to this tree as you can see from the next call A call to proto_tree_add_item in the foo_tree this time using the hf_foo_pdu_type to control the formatting of the item The pdu type is one byte of data starting at 0 We assume it is in network order so that is why we use FALSE Although for 1 byte there is no order issue it s best to keep this correct If we look in detail at the hf_foo_pdu_type declaration in the static array we can see the details of the definition e hf_foo_pdu_type the index for this node e FOO PDU Type the label for this item e foo type this is the filter string It enables us to type constructs such as foo type 1 into the filter box e FT_UNIT8 this specifies this item is an 8bit unsigned integer This tallies with our call above where we tell it to only look at one byte e BASE_DEC for an integer type this tells it to be printed as a decimal number It could be BASE_HEX or BASE_OCT if that made more sense We ll ignore the rest of the structure for now If you install this plugin and try it out you ll see something that begins t
119. run a release version previously installed Tip If compilation fails for suspicious reasons after you changed some source files try to distclean the sources and make all again 2 2 11 Debug Environment Setup XXX XXX debug needs to be written e g an idea is the create a simple MSVC 6 workspace project s to ease Visual Studio debugging 2 2 12 Optional Create User s and Developer s Guide Detailed information to build these guides can be found in the file docbook README txt in the Wireshark sources 2 2 13 Optional Create a Wireshark Installer Note You should have successfully built Wireshark before doing the following If you want to build your own wireshark setup exe you ll need NSIS 1 NSIS Download and install NSIS You may check the MAKENSIS setting in the file config nmake of the Wireshark sources 2 vcredist_x86 exe Download the C Runtime redistributable for Visual C 2005 Express Edi tion vcredist_x86 exe and copy it into C wireshark win32 libs l A Beware of Visual Studio Service Packs If you have installed the Visual Studio Service Pack 1 you need a different vcre dist_x86 exe version See Section 4 4 Microsoft compiler toolchain Win32 nat ive for details 3 If you ve closed cmd exe in the meantime prepare cmd exe again 4 nmake f Makefile nmake packaging build Wireshark installer 5 run C wireshark packaging nsis wireshark setup lt version gt exe and test it it s a good idea t
120. s some additional helper tools Perl Python Sed which are needed for the build process when Wireshark is to be installed from the released source packages If Wireshark is installed from a bin ary package none of these helper tools are needed on the target system Open Source Software 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 worrying about 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 built into the source and they often do You are welcome to modify Wireshark to suit your own needs and it would be appreciated if you contribute your improvements back to the Wireshark team You gain three benefits by contributing your improvements back to the community e Other people who find your contributions useful will appreciate them and you will know that you have helped people in the same way that the developers of Wireshark have helped people e The developers of Wireshark might improve your changes even more as there s always room for improvements Or they may implement some advanced things on top of your code which can be useful for yourself too e The maintainers and developers of Wireshark will maintain your code as well fixing it when API chang
121. s org and simply in stall it 2 2 4 2 TortoiseSVN If you want to work with the Wireshark Subversion source repositories which is highly recommen ded see Section 3 3 Obtain the Wireshark sources it s recommended to use TortoiseSVN for your everyday work You can download the setup from http tortoisesvn tigris org and simply in stall it 2 2 5 Install and Prepare Sources Tip It s a good idea to successfully compile and run Wireshark at least once before you start hacking the Wireshark sources for your own project 1 Download sources Download Wireshark sources into C wireshark using TortoiseSVN a right click on the C drive in Windows Explorer b in the upcoming context menu select SVN checkout and then set 16 2 2 6 2 2 1 Quick Setup i URL of repository ht tp anonsvn wireshark org wireshark trunk ii Checkout directory C wireshark d TortoiseSVN might ask you to create this directory say yes e TortoiseSVN starts downloading the sources f if the download fails you may be behind a restrictive firewall see Section 3 3 Obtain the Wireshark sources for alternative download methods 2 Edit config nmake edit the settings in C wireshark config nmake especially a VERSION_EXTRA give Wireshark your private version info e g myprotocol123 to distinguish it from an official release b PROGRAM_FILES where your programs reside usually just k
122. sclaimer of warranty keep intact all the notices that refer to this License and to the absence of any warranty and give any other recipients of the Program a copy of this License along with the Program You may charge a fee for the physical act of transferring a copy and you may at your option offer warranty protection in exchange for a fee 2 You may modify your copy or copies of the Program or any portion of it thus forming a work based on the Program and copy and distribute such modifications or work under the terms of Section 1 above provided that you also meet all of these conditions a You must cause the modified files to carry prominent notices stating that you changed the files and the date of any change b You must cause any work that you distribute or publish that in whole or in part contains or is derived from the Program or any part thereof to be licensed as a whole at no charge to all third parties under the terms of this License c If the modified program normally reads commands interactively when run you must cause it when started running for such interactive use in the most ordinary way to print or display an announcement including an appropriate copyright notice anda notice that there is no warranty or else saying that you provide a warranty and that users may redistribute the program under these conditions and telling the user how to view a copy of this License Exception if the Program itself is interact
123. sed tools with toolname help or read the manpage man toolname You will find explanations of the tool usage for some of the specific development tasks in Chapter 3 Work with the Wireshark sources 43 Tool Reference 4 2 Win32 Cygwin 4 2 1 Cygwin provides a lot of UNIX based tools on the Win32 platform It uses a UNIX emulation layer which might be a bit slower compared to the native Win32 tools but at an acceptable level The in stallation and update is pretty easy and done through a single web based setup exe The native Win32 tools will typically be a bit faster but more complicated to install as you would have to download the tools from different webpages and install them in different ways tweaking the PATH and alike Note As there s no Win32 native bash version available at least a basic installation of cyg win is required in any case Although Cygwin consists of several separate packages the installation and update is done through a single setup exe which acts similar to other web based installers All tools will be installed into one base folder the default is C cygwin You will find this network based setup exe at http www cygwin com Click on one of the Install Cygwin now appearances to download the setup exe After the download completed start this setup exe on your machine The setup will ask you for some settings the defaults should usually work well for a first start At the Selec
124. sh configure make If you need to build with a GTK 1 x version you have to use configure disable gtk2 instead of just configure Win32 native The first thing to do will be to check the file config nmake to determine if it reflects your con figuration The settings in this file are well documented so please have a look at that file However if you ve installed the libraries and tools as recommended there should be no need to edit things here Many of the file and directory names used in the build process go past the old 8 3 naming limita tions As a result you should use the cmd exe command interpreter instead of the old com mand com Be sure that your command line environment is set up to compile and link with MSVC When in stalling MSVC 4 you can have your system s environment set up to always allow compiling from the command line or you can invoke the vcvars32 bat script which can usually be found in the VC98 Bin subdirectory of the directory in which Visual Studio was installed You should then cleanup any intermediate files which are shipped for convenience of Unix users by typing at the command line prompt cmd exe gt nmake f Makefile nmake distclean After doing this typing at the command line prompt cmd exe gt nmake f Makefile nmake all will start the whole Wireshark build process After the build process has successfully finished you should find a wireshark exe and some 27
125. summary If it is non null we can pick apart the protocol for display So with that in mind let s enhance our dissector Example 9 4 Plugin Packet Dissection static void dissect_foo tvbuff_t tvb packet_info pinfo proto_tree tree if check_col pinfo gt cinfo COL_PROTOCOL col_set_str pinfo gt cinfo COL_PROTOCOL FOO Clear out stuff in the info column if check_col pinfo gt cinfo COL_INFO col_clear pinfo gt cinfo COL_INFO if tree we are being asked for details proto_item ti NULL ti proto_tree_add_item tree proto_foo tvb 0 1 FALSE What we re doing here is adding a subtree to the dissection This subtree will hold all the details of this protocol and so not clutter up the display when not required We are also marking the area of data that is being consumed by this protocol In our case it s all that has been passed to us as we re assuming this protocol does not encapsulate another Therefore we add the new tree node with proto_tree_add_item adding it to the passed in tree label it with the pro tocol use the passed in tvb buffer as the data and consume from 0 to the end 1 of this data The 103 Packet dissection FALSE we ll ignore for now After this change there should be a label in the detailed display for the protocol and selecting this will highlight the remaining contents of the packet Now let s go to the next step and add some protoco
126. t tvb_get_ptr tvb offset 1 tvb_length_remaining tvb offset decompressed_buffer orig_size Now re setup the tvb buffer to have the new data next_tvb tvb_new_real_data decompressed_buffer orig_size orig_size tvb_set_child_real_data_tvbuff tvb next_tvb add_new_data_source pinfo next_tvb Decompressed Data else next_tvb tvb_new_subset tvb offset 1 1 offset 0 process next_tvb from here on The first steps here are to recognise the compression In this case a flag byte alerts us to the fact the remainder of the packet is compressed Next we retrieve the original size of the packet which in this case is conveniently within the protocol If it s not it may be part of the compression routine to work it out for you in which case the logic would be different So armed with the size a buffer is allocated to receive the uncompressed data using g_malloc and the packet is decompressed into it The tvb_get_ptr function is useful to get a pointer to the raw data of the packet from the offset onwards In this case the decompression routine also needs to know the length which is given by the tvb_length_remaining function Next we build a new tvb buffer from this data using the tvb_new_treal_data call This data is a child of our original data so we acknowledge that in the next call to tvb_set_child_real_data_tvbuff Fi nally we add this data as a new data source so that the detailed display ca
127. t Packages page you ll need to select some additional packages which are not installed by default Navigate to the required Category Package row and click on the Skip item in the New column so it shows a version number for the required package After clicking the Next button several times the setup will then download and install the selected packages this may take a while depending on the package size Under Start gt Programs gt Cygwin gt Cygwin Bash Shell you should now be able to start a new Cygwin bash shell which is similar to the command line command com cmd exe in Win32 but much more powerful Add Update Remove Cygwin Packages If you want to add additional update installed or remove packages later you have to start the setup exe again At the Select Packages page the entry in the New column will control what is done or not with the package If a new version of a package is available the new version number will be displayed so it will be automatically updated You can change the current setting by simply clicking at it it will change between e a specific version number this different package version will be installed e Skip not installed no changes e Keep already installed no changes e Uninstall uninstall this package e Reinstall reinstall this package 44 Tool Reference 4 3 GNU compiler toolchain UNIX or Win32 Cygwin 4 3 1 4 3 2 4 3 3 gcc GNU compiler
128. t in the program Gnomovision which makes passes at compilers written by James Hacker lt signature of Ty Coon gt 1 April 1989 Ty Coon President of Vice This General Public License does not permit incorporating your program into proprietary programs If your program is a subroutine library you may consider it more useful to permit linking proprietary applications with the library If this is what you want to do use the GNU Library General Public License instead of this License 133
129. t to Wireshark 5 13 1 Unix If this library isn t already installed or available as a package for your platform you can get it at ht tp www lua org download html 5 13 2 Win32 MSVC You can get the latest version at http luaforge net frs group_id 110 82 Library Reference 5 14 PortAudio optional The PortAudio library enables audio output for RTP streams 5 14 1 Unix If this library isn t already installed or available as a package for your platform you can get it at ht tp www portaudio com download html 5 14 2 Win32 MSVC You can get the latest version at http www portaudio com download html 83 5 15 only Library Reference Win32 GTK WIMP optional for GTK 2 x GTK Wimp Windows impersonator is a GTK theme that blends well into the Windows desktop environment GTK Wimp can be used to get a native Look and Feel on WinXP machines especially with the col oured WinXP theme It will only take effect together with the GTK2 version of Wireshark No changes to the Wireshark sources are needed GTK Wimp simply changes the way GTK2 dis plays the widgets by changing the GTK2 default theme Wimp is available at http gtk wimp sourceforge net Since GTK version 2 8 the GTK Wimp is included in the GTK releases where it s called GTK MS Windows Engine now so no need to download install it separately if these versions used 84 Library Reference 85
130. ted debugger it can be helpful if you have to debug on a machine where an integrated debugger is not available You can get it free of charge at http www microsoft com whdc devtools debugging default mspx as links to microsoft pages change from time to time search for Debugging Tools at their page if this link should be outdated 54 Tool Reference 4 5 bash 4 5 1 4 5 2 The bash shell is needed to run several shell scripts UNIX or Win32 Cygwin GNU bash The bash shell is available for most of the UNIX like platforms and as the bash package from the Cygwin setup If bash isn t already installed or available as a package for your platform you can get it at http www gnu org software bash bash html After correct installation typing at the bash command line prompt bash version should result in something like GNU bash version 3 1 17 6 release i686 pc cygwin Copyright C 2005 Free Software Foundation Inc However the version string may vary Win32 native The authors don t know of any working Win32 native bash implementation 55 Tool Reference 4 6 python 4 6 1 4 6 2 Python is an interpreter based programming language The homepage of the python project is http python org Python is used to generate some source files Python version 2 2 and above should be working fine UNIX or Win32 Cygwin python Python is available for most of the UNIX like platfo
131. terpreters perl Quick Setup e Utils patch e Web wget After clicking the Next button several times the setup will then download and install the selected packages this may take a while Why this is recommended Cygwin s bash version is required as no native Win32 version is avail able As additional packages can easily be added the perl and alike packages are also used Install Python Get the python 2 4 installer from http python org download and install python into the default loc ation currently C Python24 Beware python 2 5 won t work without modifications Why this is recommended Cygwin s python package doesn t work on some machines so the Win32 native package is recommended Install Subversion Client Please note that the following is not required to build Wireshark but can be quite helpful when working with the sources Why this is recommended updating a personal source tree is significantly easier to do with Subver sion than downloading a zip file and merging new sources into a personal source tree by hand 2 2 4 1 Subversion If you want to work with the Wireshark Subversion source repositories which is highly recommen ded see Section 3 3 Obtain the Wireshark sources it s recommended to install Subversion This makes the first time setup easy and enables the Wireshark build process to determine your current source code revision You can download the setup from http subversion tigri
132. the UNIX like platforms and as the sed package from the Cygwin setup If sed isn t already installed or available as a package for your platform you can get it at http dir ectory fsf org GNU sed html After correct installation typing at the bash command line prompt sed version should result in something like GNU sed version 4 1 5 Copyright C 2003 Free Software Foundation Inc This is free software see the source for copying conditions There is NO warranty not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE to the extent permitted by law However the version string may vary Win32 native sed A native Win32 sed package can be obtained from http gnuwin32 sourceforge net The installation should be straightforward 58 Tool Reference 4 9 yacc bison 4 9 1 4 9 2 Bison is a free implementation of yacc UNIX or Win32 Cygwin bison Bison is available for most of the UNIX like platforms and as the bison package from the Cygwin setup If GNU Bison isn t already installed or available as a package for your platform you can get it at http www gnu org software bison bison html After correct installation typing at the bash command line prompt bison version should result in something like bison GNU Bison 2 3 Written by Robert Corbett and Richard Stallman Copyright C 2006 Free Software Foundation Inc This is free software see the source for copying conditi
133. ttp www winpcap org install default htm 78 Library Reference 5 10 GnuTLS optional The GNU Transport Layer Security Library is used to dissect SSL and TLS protocols aka HT TPS 5 10 1 Unix If this library isn t already installed or available as a package for your platform you can get it at ht tp www gnu org software gnutls download html 5 10 2 Win32 MSVC We roll our own version using http josefsson org gnutls4win 79 Library Reference 5 11 Gcrypt optional The Gcrypt Library is Low level encryption library and provides support for many ciphers such as DES 3DES AES Blowfish and others 5 11 1 Unix If this library isn t already installed or available as a package for your platform you can get it at ht tp directory fsf org security libgcrypt html 5 11 2 Win32 MSVC Part of our homemade GnuTLS package 80 Library Reference 5 12 Kerberos optional The Kerberos library is used to dissect Kerberos sealed DCERPC and secureLDAP protocols 5 12 1 Unix If this library isn t already installed or available as a package for your platform you can get it at ht tp web mit edu Kerberos dist XXX Is it supported on NIX at all 5 12 2 Win32 MSVC You can get the latest version of KfW Kerberos for Windows at http web mit edu Kerberos dist 81 Library Reference 5 13 LUA optional The LUA library is used to add scripting suppor
134. tudio it will include a PSDK The free as in beer down loadable C compiler versions VC 2005 Express NET Framework do not contain a PSDK you ll need to download a PSDK in order to have the required C header files and libraries Older Versions of the Platform SDK should also work However the command to set the environ ment settings will be different try search for SetEnv in the SDK directory BTW Windows SDK seems to be the new name of the Platform SDK for Vista The current SDK name is misleading Microsoft Windows Software Development Kit for Windows Vista and NET Framework 3 0 Runtime Components translated this means the Windows SDK for Win dows Vista and Platforms like WinXP that have the NET 3 0 runtime installed HTML Help The HTML Help is used to create the User s and Developer s Guide in chm format and to show the User s Guide as the Wireshark Online Help Both features are currently optional but might be mandatory in future versions 4 4 8 1 HTML Help Compiler hhc exe This compiler is used to generate a chm file from a bunch of HTML files in our case to generate the User s and Developer s Guide in chm format The compiler is only available as the free as in beer HTML Help Workshop download If you want to compile the guides yourself you need to download and install this If you don t install it into the default directory you may also have a look at the HHC_DIR setting in the f
135. unzip if you want to use the Win32 automated library download see Sec tion 5 3 Win32 Automated library download for details If GNU unzip isn t already installed or available as a package for your platform well for Win32 it is available as a Cygwin package you can get it at http gnuwin32 sourceforge net packages un zip htm 66 Tool Reference 4 17 Win32 NSIS optional The NSIS Nullsoft Scriptable Install System is used to generate a wireshark setup lt version gt exe from all the files needed to be installed including all required DLL s and such To install it simply download the latest released version currently 2 28 from http nsis sourceforge net and start the downloaded installer You will need NSIS version 2 final or high er You will find more instructions in Section 3 12 3 Win32 NSIS exe installer on how to use the NSIS tool 67 Tool Reference 68 Chapter 5 Library Reference 5 1 Introduction Several libraries are needed to build run Wireshark Most of the libraries are split into three pack ages 1 Runtime package binaries e g win32 DLL s and alike 2 Developer package documentation header files and alike 3 Source package library sources usually not required to build Wireshark Tip Win32 All required libraries for the MSVC generation are available at http anons vn wireshark org wireshark win32 libs trunk packages but
136. ur option any later version This program is distributed in the hope that it will be useful but WITHOUT ANY WARRANTY without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE See the GNU General Public License for more details You should have received a copy of the GNU General Public License along with this program if not write to the Free Software Foundation Inc 59 Temple Place Suite 330 Boston MA 02111 1307 USA Also add information on how to contact you by electronic and paper mail If the program is interactive make it output a short notice like this when it starts in an interactive mode Gnomovision version 69 Copyright C year name of author Gnomovision comes with ABSOLUTELY NO WARRANTY for details type show w This is free software and you are welcome to redistribute it under certain conditions type show c for details The hypothetical commands show w and show c should show the appropriate parts of the General Public License Of course the commands you use may be called something other than show w and show c they could even be mouse clicks or menu items whatever suits your program You should also get your employer if you work as a programmer or your school if any to sign a copyright disclaimer for the program if necessary Here is a sample alter the names 132 This Document s License GPL Yoyodyne Inc hereby disclaims all copyright interes
137. various protocol dissectors in epan dissectors e Plugins Some of the protocol dissectors are implemented as plugins Source code can be found at plugins e Display Filters the display filter engine at epan dfilter Capture engine The wiretap library is used to read write capture files in libp cap and a lot of other file formats Source code in the wiretap directory The platform dependent packet capture library including the capture filter engine That s the reason why we still have dif ferent display and capture filter syntax as two different filter ing engines are used 89 How Wireshark Works 6 3 Capturing packets Capturing will take packets from a network adapter and save them to a file on your harddisk To hide all the lowlevel machine dependent details from Wireshark the libpcap WinPcap see Sec tion 5 9 libpcap WinPcap optional library is used This library provides a general purpose in terface to capture packets from a lot of different network interface types Ethernet Token Ring 90 How Wireshark Works 6 4 Capture Files Wireshark can read and write capture files in its natural file format the libpcap format which is used by many other network capturing tools e g tcpdump In addition to this as one of its strengths Wireshark can read write files in many different file formats of other network capturing tools The wiretap library developed together with Wiresh
138. veloper mailing list see Section 1 7 5 Mailing Lists and explain your idea Someone else might already be working on the same topic so double effort can be re duced or someone can give you some tips that should be thought about like side ef fects that are sometimes very hard to see 31 Work with the Wireshark sources 3 9 Contribute your changes 3 9 1 If you have finished changing the Wireshark sources to suit your needs you might want to contrib ute your changes back to the Wireshark community You gain the following benefits by contributing your improvements e It s the right thing to do Other people who find your contributions useful will appreciate them and you will know that you have helped people in the same way that the developers of Wire shark have helped you e You get free enhancements By making your code public other developers have a chance to make improvements as there s always room for improvements In addition someone may imple ment advanced features on top of your code which can be useful for yourself too e You save time and effort The maintainers and developers of Wireshark will maintain your code as well updating it when API changes or other changes are made and generally keeping it in tune with what is happening with Wireshark So if Wireshark is updated which is done often you can get a new Wireshark version from the website and your changes will already be in cluded without any e

Download Pdf Manuals

Related Search

Related Contents

Mode Emploi Guide - 2014-2015_V5 - EN  Elgato Turbo.264 HD  取扱説明書 - Panasonic  Informe Técnico  The Macroplastique® Implantation System  取扱説明書 - Onkyo  LABOSHAKE LS 2/5, RO 2/5  取扱説明書及び寸法表  TV Service Manual - Mikrocontroller.net  Communiqué de presse au format pdf  

Copyright © All rights reserved. Failed to retrieve file